Ubuntu Manpage: salt - Salt Documentation

Provided by: salt-doc_2017.7.4+dfsg1-1ubuntu18.04.2_all

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:

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

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

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

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

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

salt '*' test.ping

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

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

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

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

pacman -S salt

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

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

NOTE:
yaourt

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

The command to install salt using the yaourt tool is:

yaourt salt-git

Post-installation tasks
systemd

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

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

Start the Master

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

systemctl start salt-master

Now go to the Configuring Salt page.

Debian GNU/Linux / Raspbian
Debian GNU/Linux distribution and some derivatives such as Raspbian already have included
Salt packages to their repositories. However, current stable 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 9 (Stretch) and Debian 8 (Jessie) are available in the Official
SaltStack repository.

Instructions are at https://repo.saltstack.com/#debian.

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

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:

1. Add jessie-backports and stretch repositories:

Debian:

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

Raspbian:

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

2. Make Jessie a default release:

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

3. Install Salt dependencies:

Debian:

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

Raspbian:

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

4. Install Salt minion package from Stretch:

apt-get install salt-minion/stretch

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

• apt-get install salt-api

• apt-get install salt-cloud

• apt-get install salt-master

• apt-get install salt-minion

• apt-get install salt-ssh

• apt-get install salt-syndic

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

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

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

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

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

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

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

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

Install the Extension
Copy the Salt package to extension

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

Install the SWIX

veos#extension salt-eos-latest.swix force

Verify the installation

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

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

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

Make sure you enable the eAPI with unix-socket

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

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

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

salt-minion should be running

Copy the installed extensions to boot-extensions

veos#copy installed-extensions boot-extensions

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

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

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

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

1. Remove the extension from boot-extensions

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

2. Remove the extension from extensions folder

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

2. Remove boot-up script

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

Additional Information
This SWIX extension contains the following RPM packages:

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

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

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

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

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

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

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

yum install salt-master
yum install salt-minion

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

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

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

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

Installing from pip has a few additional requirements:

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

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

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

Installation from pip:

pip install salt

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

Post-installation tasks
Master

To have the Master start automatically at boot time:

systemctl enable salt-master.service

To start the Master:

systemctl start salt-master.service

Minion

To have the Minion start automatically at boot time:

systemctl enable salt-minion.service

To start the Minion:

systemctl start salt-minion.service

Now go to the Configuring Salt page.

FreeBSD
Installation
Salt is available in 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.

pkg install py27-salt

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:

saltstack: {
url: "https://repo.saltstack.com/freebsd/${ABI}/",
enabled: yes
}

You should now be able to install Salt from this new repository:

pkg install py27-salt

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:

cp /usr/local/etc/salt/master.sample /usr/local/etc/salt/master

rc.conf

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

sysrc salt_master_enable="YES"

Start the Master

Start the Salt Master as follows:

service salt_master start

Minion

Copy the sample configuration file:

cp /usr/local/etc/salt/minion.sample /usr/local/etc/salt/minion

rc.conf

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

sysrc salt_minion_enable="YES"

Start the Minion

Start the Salt Minion as follows:

service salt_minion start

Now go to the Configuring Salt page.

Gentoo
Salt can be easily installed on Gentoo via Portage:

emerge app-admin/salt

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

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

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

devel/py-futures
devel/py-progressbar
net/py-msgpack
net/py-zmq
security/py-crypto
security/py-M2Crypto
textproc/py-MarkupSafe
textproc/py-yaml
www/py-jinja2
www/py-requests
www/py-tornado

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

pkg_add salt

Post-installation tasks
Master

To have the Master start automatically at boot time:

rcctl enable salt_master

To start the Master:

rcctl start salt_master

Minion

To have the Minion start automatically at boot time:

rcctl enable salt_minion

To start the Minion:

rcctl start salt_minion

Now go to the Configuring Salt page.

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

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

Earlier builds from supported branches

Archived builds from unsupported branches

Installation from Homebrew
brew install saltstack

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

Installation from MacPorts
sudo port install salt

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

sudo pip install salt

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

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

max_open_files: 8192

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

sudo launchctl limit maxfiles 4096 8192

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

Now the salt-master should run without errors:

sudo salt-master --log-level=all

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

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

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

• Red Hat / CentOS

• Amazon Linux

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

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

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

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

Installation 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:
Packages in these repositories are built by community, and it can take a little while
until the latest stable SaltStack release become available.

RHEL/CentOS 6 and 7, Scientific Linux, etc.
WARNING:
Salt 2015.8 is currently not available in EPEL due to unsatisfied dependencies:
python-crypto 2.6.1 or higher, and python-tornado version 4.2.1 or higher. These
packages are not currently available in EPEL for Red Hat Enterprise Linux 6 and 7.

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:

rpm -Uvh epel-release-X-Y.rpm

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.

• yum install salt-master

• yum install salt-minion

• yum install salt-ssh

• yum install salt-syndic

• yum install salt-cloud

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:

yum --enablerepo=epel-testing install salt-minion

Installation Using pip
Since Salt is on PyPI, it can be installed using pip, though most users prefer to install
using RPM packages (which can be installed from EPEL).

Installing from pip has a few additional requirements:

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

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

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

Installation from pip:

pip install salt

ZeroMQ 4
We recommend using ZeroMQ 4 where available. 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:
RHEL/CentOS 5 Users Using COPR repos on RHEL/CentOS 5 requires that the python-hashlib
package be installed. Not having it present will result in checksum errors because YUM
will not be able to process the SHA256 checksums used by COPR.

NOTE:
For RHEL/CentOS 5 installations, if using the SaltStack repo or Fedora COPR to install
Salt (as described above), then it is not necessary to enable the zeromq4 COPR, because
those repositories already include ZeroMQ 4.

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

chkconfig salt-master on

RHEL/CentOS 7

systemctl enable salt-master.service

To start the Master:

RHEL/CentOS 5 and 6

service salt-master start

RHEL/CentOS 7

systemctl start salt-master.service

Minion
To have the Minion start automatically at boot time:

RHEL/CentOS 5 and 6

chkconfig salt-minion on

RHEL/CentOS 7

systemctl enable salt-minion.service

To start the Minion:

RHEL/CentOS 5 and 6

service salt-minion start

RHEL/CentOS 7

systemctl start salt-minion.service

Now go to the Configuring Salt page.

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

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

For example, to install the develop version of salt:

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

NOTE:
SaltStack does offer commerical support for Solaris which includes packages.

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.

• apt-get install salt-api

• apt-get install salt-cloud

• apt-get install salt-master

• apt-get install salt-minion

• apt-get install salt-ssh

• apt-get install salt-syndic

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

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

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

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

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

Earlier builds from supported branches

Archived builds from unsupported branches

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

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.

There are installers available for Python 2 and Python 3.

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

Salt Minion Installation
After the Welcome and the License Agreement, the installer asks for two bits of
information to configure the minion; the master hostname and the minion name. The
installer will update the minion config with these options. If the installer finds an
existing minion config file, these fields will be populated with values from the existing
config.

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

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

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

sc start salt-minion
net start salt-minion

NOTE:
If the minion won't start, you may need to install 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:

┌──────────────────────┬──────────────────────────────────┐
│Option │ Description │
├──────────────────────┼──────────────────────────────────┤
│/minion-name= │ A string value to set the minion │
│ │ name. Default is 'hostname' │
├──────────────────────┼──────────────────────────────────┤
│/master= │ A string value to set the IP │
│ │ address or host name of the │
│ │ master. Default value is 'salt' │
├──────────────────────┼──────────────────────────────────┤
│/start-minion= │ Either a 1 or 0. '1' will start │
│ │ the salt-minion service, '0' │
│ │ will not. Default is to start │
│ │ the service after installation. │
├──────────────────────┼──────────────────────────────────┤
│/start-minion-delayed │ Set the minion start type to │
│ │ Automatic (Delayed Start) │
└──────────────────────┴──────────────────────────────────┘

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

Here are some examples of using the silent installer:

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

Salt-Minion-2017.7.1-Py2-AMD64-Setup.exe /S /master=yoursaltmaster /minion-name=yourminionname

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

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

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

• These instructions were tested with Windows Server 2008 R2

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

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

2. Click Add or remove user accounts.

3. Click Create new account.

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

5. Select the Standard user radio button.

6. Click the Create Account button.

7. Click on the newly created user account.

8. Click the Create a password link.

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

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

11. Click the Create password button.

12. Close the Change an Account window.

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

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

3. Click on the Security tab.

4. Click the Edit button.

5. Click the Add button.

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

7. Check the box to Allow the Modify permission.

8. Click the OK button.

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

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

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

3. Click the Log On tab.

4. Click the This account radio button.

5. Provide the account credentials created in section A.

6. Click the OK button.

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

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

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

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

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

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

Scripts:
┌────────────────┬──────────────────────────────────┐
│Script │ Description │
├────────────────┼──────────────────────────────────┤
│build_env_2.ps1 │ A PowerShell script that sets up │
│ │ a Python 2 build environment │
├────────────────┼──────────────────────────────────┤
│build_env_3.ps1 │ A PowerShell script that sets up │
│ │ a Python 3 build environment │
├────────────────┼──────────────────────────────────┤
│build_pkg.bat │ A batch file that builds a │
│ │ Windows installer based on the │
│ │ contents of the C:\Python27 │
│ │ directory │
├────────────────┼──────────────────────────────────┤
│build.bat │ A batch file that fully │
│ │ automates the building of the │
│ │ Windows installer using the │
│ │ above two scripts │
└────────────────┴──────────────────────────────────┘

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

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

Prerequisite Software
The only prerequisite is Git for Windows.

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

Open a command line and type:

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

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

cd salt
git checkout 2017.7.2

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

cd pkg\windows
powershell -file build_env_2.ps1

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

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

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

Set-ExecutionPolicy RemoteSigned

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

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

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

NOTE:
The . is important

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cd salt
git checkout 2017.7.2

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

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

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

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

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

3. Edit C:\salt\conf\minion

master: ipaddress or hostname of your salt-master

4. Start the salt-minion

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

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

sudo salt-key -A

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

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

sudo salt '*' test.ping

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.

zypper install salt-master
zypper install salt-minion

Post-installation tasks openSUSE
Master

To have the Master start automatically at boot time:

systemctl enable salt-master.service

To start the Master:

systemctl start salt-master.service

Minion

To have the Minion start automatically at boot time:

systemctl enable salt-minion.service

To start the Minion:

systemctl start salt-minion.service

Post-installation tasks SLES
Master

To have the Master start automatically at boot time:

chkconfig salt-master on

To start the Master:

rcsalt-master start

Minion

To have the Minion start automatically at boot time:

chkconfig salt-minion on

To start the Minion:

rcsalt-minion start

Unstable Release
openSUSE
For openSUSE Tumbleweed run the following as root:

zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/openSUSE_Tumbleweed/systemsmanagement:saltstack.repo
zypper refresh
zypper install salt salt-minion salt-master

For openSUSE 42.1 Leap run the following as root:

zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/openSUSE_Leap_42.1/systemsmanagement:saltstack.repo
zypper refresh
zypper install salt salt-minion salt-master

For openSUSE 13.2 run the following as root:

zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/openSUSE_13.2/systemsmanagement:saltstack.repo
zypper refresh
zypper install salt salt-minion salt-master

SUSE Linux Enterprise
For SLE 12 run the following as root:

zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/SLE_12/systemsmanagement:saltstack.repo
zypper refresh
zypper install salt salt-minion salt-master

For SLE 11 SP4 run the following as root:

zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/SLE_11_SP4/systemsmanagement:saltstack.repo
zypper refresh
zypper install salt salt-minion salt-master

Now go to the Configuring Salt page.

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

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

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

- #interface: 0.0.0.0
+ interface: 10.0.0.1

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

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

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

- #master: salt
+ master: 10.0.0.1

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

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

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

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

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

salt-master

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

salt-minion

Having trouble?

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

salt-master --log-level=debug

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

Run as an unprivileged (non-root) user

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

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

• /etc/salt

• /var/cache/salt

• /var/log/salt

• /var/run/salt

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

There is also a full troubleshooting guide available.

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

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

salt-key -F master

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

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

salt-call --local key.finger

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

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

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

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

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

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

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

CONFIGURING SALT

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

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

SEE ALSO:
Example master configuration file.

The configuration file for the salt-master is located at /etc/salt/master by default. A
notable exception is FreeBSD, where the configuration file is located at
/usr/local/etc/salt. The available options are as follows:

Primary Master Configuration
interface
Default: 0.0.0.0 (all interfaces)

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

interface: 192.168.0.1

ipv6
Default: False

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

ipv6: True

publish_port
Default: 4505

The network port to set up the publication interface.

publish_port: 4505

master_id
Default: None

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

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

master_id: MasterOfMaster

user
Default: root

The user to run the Salt processes

user: root

ret_port
Default: 4506

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

ret_port: 4506

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

Specify the location of the master pidfile.

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

root_dir
Default: /

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

root_dir: /

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

conf_file
Default: /etc/salt/master

The path to the master's configuration file.

conf_file: /etc/salt/master

pki_dir
Default: /etc/salt/pki/master

The directory to store the pki authentication keys.

pki_dir: /etc/salt/pki/master

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

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

extension_modules: /root/salt_extmods

extmod_whitelist/extmod_blacklist
New in version 2017.7.0.

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

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

extmod_blacklist:
modules:
- specific_module

Valid options:

• modules

• states

• grains

• renderers

• returners

• output

• proxy

• runners

• wheel

• engines

• queues

• pillar

• utils

• sdb

• cache

• clouds

• tops

• roster

module_dirs
Default: []

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

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

cachedir
Default: /var/cache/salt/master

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

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

cachedir: /var/cache/salt/master

verify_env
Default: True

Verify and set permissions on configuration directories at startup.

verify_env: True

keep_jobs
Default: 24

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

keep_jobs: 24

gather_job_timeout
New in version 2014.7.0.

Default: 10

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

gather_job_timeout: 10

timeout
Default: 5

Set the default timeout for the salt command and api.

loop_interval
Default: 60

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

output
Default: nested

Set the default outputter used by the salt command.

outputter_dirs
Default: []

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

outputter_dirs: []

output_file
Default: None

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

output_file: /path/output/file

show_timeout
Default: True

Tell the client to show minions that have timed out.

show_timeout: True

show_jid
Default: False

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

show_jid: False

color
Default: True

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

color: False

cli_summary
Default: False

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

cli_summary: False

sock_dir
Default: /var/run/salt/master

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

sock_dir: /var/run/salt/master

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

job_cache: True

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

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

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

minion_data_cache
Default: True

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

minion_data_cache: True

cache
Default: localfs

Cache subsystem module to use for minion data cache.

cache: consul

memcache_expire_seconds
Default: 0

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

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

memcache_expire_seconds: 30

memcache_max_items
Default: 1024

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

memcache_max_items: 1024

memcache_full_cleanup
Default: False

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

memcache_full_cleanup: True

memcache_debug
Default: False

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

memcache_debug: True

ext_job_cache
Default: ''

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

ext_job_cache: redis

event_return
New in version 2015.5.0.

Default: ''

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

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

event_return:
- syslog
- splunk

event_return_queue
New in version 2015.5.0.

Default: 0

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

event_return_queue: 0

event_return_whitelist
New in version 2015.5.0.

Default: []

Only return events matching tags in a whitelist.

Changed in version 2016.11.0: Supports glob matching patterns.

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

event_return_blacklist
New in version 2015.5.0.

Default: []

Store all event returns _except_ the tags in a blacklist.

Changed in version 2016.11.0: Supports glob matching patterns.

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

max_event_size
New in version 2014.7.0.

Default: 1048576

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

max_event_size: 1048576

ping_on_rotate
New in version 2014.7.0.

Default: False

By default, the master AES key rotates every 24 hours. The next command following a key
rotation will trigger a key refresh from the minion which may result in minions which do
not respond to the first command after a key refresh.

To tell the master to ping all minions immediately after an AES key refresh, set
ping_on_rotate to True. This should mitigate the issue where a minion does not appear to
initially respond after a key is rotated.

Note that ping_on_rotate may cause high load on the master immediately after the key
rotation event as minions reconnect. Consider this carefully if this salt master is
managing a large number of minions.

master_job_cache
New in version 2014.7.0.

Default: local_cache

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

master_job_cache: redis

enforce_mine_cache
Default: False

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

enforce_mine_cache: False

max_minions
Default: 0

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

max_minions: 100

con_cache
Default: False

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

con_cache: True

presence_events
Default: False

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

presence_events: False

ping_on_rotate
Default: False

If disabled, it is recommended to handle this event by listening for the aes_key_rotate
event with the key tag and acting appropriately.

ping_on_rotate: False

transport
Default: zeromq

Changes the underlying transport layer. ZeroMQ is the recommended transport while
additional transport layers are under development. Supported values are zeromq, 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: zeromq

transport_opts
Default: {}

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

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

sock_pool_size
Default: 1

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

sock_pool_size: 15

ipc_mode
Default: ipc

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

ipc_mode: ipc

tcp_master_pub_port
Default: 4512

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

tcp_master_pub_port: 4512

tcp_master_pull_port
Default: 4513

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

tcp_master_pull_port: 4513

tcp_master_publish_pull
Default: 4514

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

tcp_master_publish_pull: 4514

tcp_master_workers
Default: 4515

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

tcp_master_workers: 4515

auth_events
New in version 2017.7.3.

Default: True

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

auth_events: True

minion_data_cache_events
New in version 2017.7.3.

Default: True

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

minion_data_cache_events: True

Salt-SSH Configuration
roster_file
Default: /etc/salt/roster

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

roster_file: /root/roster

ssh_passwd
Default: ''

The ssh password to log in with.

ssh_passwd: ''

ssh_port
Default: 22

The target system's ssh port number.

ssh_port: 22

ssh_scan_ports
Default: 22

Comma-separated list of ports to scan.

ssh_scan_ports: 22

ssh_scan_timeout
Default: 0.01

Scanning socket timeout for salt-ssh.

ssh_scan_timeout: 0.01

ssh_sudo
Default: False

Boolean to run command via sudo.

ssh_sudo: False

ssh_timeout
Default: 60

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

ssh_timeout: 60

ssh_user
Default: root

The user to log in as.

ssh_user: root

ssh_log_file
New in version 2016.3.5.

Default: /var/log/salt/ssh

Specify the log file of the salt-ssh command.

ssh_log_file: /var/log/salt/ssh

ssh_minion_opts
Default: None

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

ssh_minion_opts:
gpg_keydir: /root/gpg

ssh_use_home_key
Default: False

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

ssh_use_home_key: False

ssh_identities_only
Default: False

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

ssh_identities_only: False

ssh_list_nodegroups
Default: {}

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

ssh_list_nodegroups:
groupA: minion1,minion2
groupB: minion1,minion3

thin_extra_mods
Default: None

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

min_extra_mods
Default: None

Identical as thin_extra_mods, only applied to the Salt Minimal.

Master Security Settings
open_mode
Default: False

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

open_mode: False

auto_accept
Default: False

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

auto_accept: False

keysize
Default: 2048

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

keysize: 2048

autosign_timeout
New in version 2014.7.0.

Default: 120

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

autosign_file
Default: not defined

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

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.

permissive_pki_access
Default: False

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

permissive_pki_access: False

publisher_acl
Default: {}

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

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

publisher_acl_blacklist
Default: {}

Blacklist users or modules

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

This is completely disabled by default.

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

sudo_acl
Default: False

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

sudo_acl: False

external_auth
Default: {}

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

external_auth:
pam:
fred:
- test.*

token_expire
Default: 43200

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

Default: 12 hours

token_expire: 43200

token_expire_user_override
Default: False

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

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

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

keep_acl_in_token
Default: False

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

keep_acl_in_token: False

eauth_acl_module
Default: ''

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

eauth_acl_module: django

file_recv
Default: False

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

file_recv: False

file_recv_max_size
New in version 2014.7.0.

Default: 100

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

file_recv_max_size: 100

master_sign_pubkey
Default: False

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

master_sign_pubkey: True

master_sign_key_name
Default: master_sign

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

master_sign_key_name: <filename_without_suffix>

master_pubkey_signature
Default: master_pubkey_signature

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

master_pubkey_signature: <filename>

master_use_pubkey_signature
Default: False

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

master_use_pubkey_signature: True

rotate_aes_key
Default: True

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

rotate_aes_key: True

publish_session
Default: 86400

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

publish_session: Default: 86400

ssl
New in version 2016.11.0.

Default: None

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

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

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

allow_minion_key_revoke
Default: False

By default, the master deletes its cache of minion data when the key for that minion is
removed. To preserve the cache after key deletion, set preserve_minion_cache to True.

WARNING: This may have security implications if compromised minions auth with a previous
deleted minion ID.

preserve_minion_cache: False

allow_minion_key_revoke
Default: True

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

rotate_aes_key: True

Master Large Scale Tuning Settings
max_open_files
Default: 100000

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

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

max_open_files: 100000

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

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

raise max open files hard limit debian

worker_threads
Default: 5

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

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

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

worker_threads: 5

pub_hwm
Default: 1000

The zeromq high water mark on the publisher interface.

pub_hwm: 1000

zmq_backlog
Default: 1000

The listen queue size of the ZeroMQ backlog.

zmq_backlog: 1000

salt_event_pub_hwm and event_publisher_pub_hwm
These two ZeroMQ High Water Mark settings, salt_event_pub_hwm and event_publisher_pub_hwm
are significant for masters with thousands of minions. When these are insufficiently high
it will manifest in random responses missing in the CLI and even missing from the job
cache. Masters that have fast CPUs and many cores with appropriate worker_threads will not
need these set as high.

The ZeroMQ high-water-mark for the SaltEvent pub socket default is:

salt_event_pub_hwm: 20000

The ZeroMQ high-water-mark for the EventPublisher pub socket default is:

event_publisher_pub_hwm: 10000

As an example, on single master deployment with 8,000 minions, 2.4GHz CPUs, 24 cores, and
32GiB memory has these settings:

salt_event_pub_hwm: 128000
event_publisher_pub_hwm: 64000

Master Module Management
runner_dirs
Default: []

Set additional directories to search for runner modules.

runner_dirs:
- /var/lib/salt/runners

cython_enable
Default: False

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

cython_enable: False

Master State System Settings
state_top
Default: top.sls

The state system uses a "top" file to tell the minions what environment to use and what
modules to use. The state_top file is defined relative to the root of the base
environment.

state_top: top.sls

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

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

state_top_saltenv: dev

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

Default: merge

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

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

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

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

top_file_merging_strategy: same

env_order
Default: []

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

env_order:
- base
- dev
- qa

master_tops
Default: {}

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

master_tops:
ext_nodes: <Shell command which returns yaml>

external_nodes
Default: None

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

external_nodes: cobbler-ext-nodes

renderer
Default: yaml_jinja

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

renderer: yaml_jinja

userdata_template
New in version 2016.11.4.

Default: None

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

userdata_template: jinja

jinja_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_trim_blocks: False

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.

jinja_lstrip_blocks: False

failhard
Default: False

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

failhard: False

state_verbose
Default: True

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

state_verbose: False

state_output
Default: full

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

state_output: full

state_output_diff
Default: False

The state_output_diff setting changes whether or not the output from successful states is
returned. Useful when even the terse output of these states is cluttering the logs. Set it
to True to ignore them.

state_output_diff: False

state_aggregate
Default: False

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

state_aggregate:
- pkg

state_aggregate: True

state_events
Default: False

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

state_events: True

yaml_utf8
Default: False

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

yaml_utf8: False

runner_returns
Default: False

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

runner_returns: True

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

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

Example:

fileserver_backend:
- roots
- git

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

fileserver_followsymlinks
New in version 2014.1.0.

Default: True

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

fileserver_followsymlinks: True

fileserver_ignoresymlinks
New in version 2014.1.0.

Default: False

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

fileserver_ignoresymlinks: False

fileserver_limit_traversal
New in version 2014.1.0.

Default: False

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

fileserver_limit_traversal: False

fileserver_list_cache_time
New in version 2014.1.0.

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

Default: 20

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

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

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

fileserver_list_cache_time: 5

fileserver_verify_config
New in version 2017.7.0.

Default: True

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

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

fileserver_verify_config: False

hash_type
Default: sha256

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

hash_type: sha256

file_buffer_size
Default: 1048576

The buffer size in the file server in bytes.

file_buffer_size: 1048576

file_ignore_regex
Default: ''

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

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

file_ignore_glob
Default ''

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

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

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

roots: Master's Local File Server
file_roots
Default:

base:
- /srv/salt

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

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

Example:

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

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

master_roots
Default: /srv/salt-master

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

master_roots: /srv/salt-master

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.

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

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

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

gitfs_provider
New in version 2014.7.0.

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

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

gitfs_provider: gitpython

gitfs_ssl_verify
Default: True

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

gitfs_ssl_verify: False

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

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

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

gitfs_mountpoint
New in version 2014.7.0.

Default: ''

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

gitfs_mountpoint: salt://foo/bar

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

gitfs_root
Default: ''

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

gitfs_root: somefolder/otherfolder

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

gitfs_base
Default: master

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

gitfs_base: salt

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

gitfs_saltenv
New in version 2016.11.0.

Default: []

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

gitfs_saltenv:
- dev:
- ref: develop

gitfs_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_whitelist:
- base
- v1.*
- 'mybranch\d+'

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_env_blacklist:
- base
- v1.*
- 'mybranch\d+'

gitfs_global_lock
New in version 2015.8.9.

Default: True

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

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

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

# Disable global lock
gitfs_global_lock: False

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

gitfs_user
New in version 2014.7.0.

Default: ''

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

gitfs_user: git

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

gitfs_password
New in version 2014.7.0.

Default: ''

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

gitfs_password: mypassword

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

gitfs_insecure_auth
New in version 2014.7.0.

Default: False

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

gitfs_insecure_auth: True

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

gitfs_pubkey
New in version 2014.7.0.

Default: ''

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

gitfs_pubkey: /path/to/key.pub

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

gitfs_privkey
New in version 2014.7.0.

Default: ''

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

gitfs_privkey: /path/to/key

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

gitfs_passphrase
New in version 2014.7.0.

Default: ''

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

gitfs_passphrase: mypassphrase

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

gitfs_refspecs
New in version 2017.7.0.

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

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

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

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.

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

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

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

hgfs_branch_method
New in version 0.17.0.

Default: branches

Defines the objects that will be used as fileserver environments.

• branches - Only branches and tags will be used

• bookmarks - Only bookmarks and tags will be used

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

hgfs_branch_method: mixed

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

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

hgfs_mountpoint
New in version 2014.7.0.

Default: ''

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

hgfs_mountpoint: salt://foo/bar

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

hgfs_root
New in version 0.17.0.

Default: ''

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

hgfs_root: somefolder/otherfolder

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

hgfs_base
New in version 2014.1.0.

Default: default

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

hgfs_base: salt

hgfs_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_whitelist:
- base
- v1.*
- 'mybranch\d+'

hgfs_env_blacklist
New in version 2014.7.0.

Default: []

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

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

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

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.

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

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

• svnfs_root

• svnfs_mountpoint

• svnfs_trunk

• svnfs_branches

• svnfs_tags

For example:

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

svnfs_mountpoint
New in version 2014.7.0.

Default: ''

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

svnfs_mountpoint: salt://foo/bar

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

svnfs_root
New in version 0.17.0.

Default: ''

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

svnfs_root: somefolder/otherfolder

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

svnfs_trunk
New in version 2014.7.0.

Default: trunk

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

svnfs_trunk: trunk

svnfs_branches
New in version 2014.7.0.

Default: branches

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

svnfs_branches: branches

svnfs_tags
New in version 2014.7.0.

Default: tags

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

svnfs_tags: tags

svnfs_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_whitelist:
- base
- v1.*
- 'mybranch\d+'

svnfs_env_blacklist
New in version 2014.7.0.

Default: []

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

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

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

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

minionfs_mountpoint
New in version 2014.7.0.

Default: ''

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

minionfs_mountpoint: salt://foo/bar

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

minionfs_whitelist
New in version 2014.7.0.

Default: []

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

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

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

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

minionfs_blacklist
New in version 2014.7.0.

Default: []

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

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

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

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

Pillar Configuration
pillar_roots
Default:

base:
- /srv/pillar

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

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

on_demand_ext_pillar
New in version 2016.3.6,2016.11.3,2017.7.0.

Default: ['libvirt', 'virtkey']

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

on_demand_ext_pillar:
- libvirt
- virtkey
- git

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

decrypt_pillar
New in version 2017.7.0.

Default: []

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

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

Entries in this list can be formatted either as a simple string, or as a key/value pair,
with the key being the pillar location, and the value being the renderer to use for pillar
decryption. If the former is used, the renderer specified by decrypt_pillar_default will
be used.

decrypt_pillar_delimiter
New in version 2017.7.0.

Default: :

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

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

decrypt_pillar_default
New in version 2017.7.0.

Default: gpg

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

decrypt_pillar_default: my_custom_renderer

decrypt_pillar_renderers
New in version 2017.7.0.

Default: ['gpg']

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

decrypt_pillar_renderers:
- gpg
- my_custom_renderer

pillar_opts
Default: False

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

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

pillar_opts: False

pillar_safe_render_error
Default: True

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

Rendering SLS 'my.sls' failed. Please see master log for details.

pillar_safe_render_error: True

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

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

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

Default: []

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

There are additional details at salt-pillars

ext_pillar_first
New in version 2015.5.0.

Default: False

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

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

ext_pillar_first: False

pillarenv_from_saltenv
Default: False

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

pillarenv_from_saltenv: True

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

pillar_raise_on_missing
New in version 2015.5.0.

Default: False

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

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

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

git_pillar_provider: gitpython

git_pillar_base
New in version 2015.8.0.

Default: master

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

git_pillar_base: foo

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

git_pillar_branch
New in version 2015.8.0.

Default: master

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

git_pillar_branch: pillardata

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

git_pillar_env
New in version 2015.8.0.

Default: '' (unset)

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

git_pillar_env: base

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

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

git_pillar_root
New in version 2015.8.0.

Default: ''

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

git_pillar_root: pillar

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

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

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

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

git_pillar_ssl_verify
New in version 2015.8.0.

Changed in version 2016.11.0.

Default: False

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

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

git_pillar_ssl_verify: True

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

git_pillar_global_lock
New in version 2015.8.9.

Default: True

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

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

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

# Disable global lock
git_pillar_global_lock: False

git_pillar_includes
New in version 2017.7.0.

Default: True

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

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

git_pillar_includes: False

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

git_pillar_user
New in version 2015.8.0.

Default: ''

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

git_pillar_user: git

git_pillar_password
New in version 2015.8.0.

Default: ''

Along with git_pillar_user, is used to authenticate to HTTPS remotes. This parameter is
not required if the repository does not use authentication.

git_pillar_password: mypassword

git_pillar_insecure_auth
New in version 2015.8.0.

Default: False

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

git_pillar_insecure_auth: True

git_pillar_pubkey
New in version 2015.8.0.

Default: ''

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

git_pillar_pubkey: /path/to/key.pub

git_pillar_privkey
New in version 2015.8.0.

Default: ''

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

git_pillar_privkey: /path/to/key

git_pillar_passphrase
New in version 2015.8.0.

Default: ''

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

git_pillar_passphrase: mypassphrase

git_pillar_refspecs
New in version 2017.7.0.

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

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

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

git_pillar_verify_config
New in version 2017.7.0.

Default: True

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

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

git_pillar_verify_config: False

Pillar Merging Options
pillar_source_merging_strategy
New in version 2014.7.0.

Default: smart

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

• none:

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.

• recurse:

it will merge recursively mapping of data. For example, theses 2 sources:

foo: 42
bar:
element1: True

bar:
element2: True
baz: quux

will be merged as:

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

• aggregate:

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

For example, these two documents:

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

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

will be merged as:

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

• overwrite:

Will use the behaviour of the 2014.1 branch and earlier.

Overwrites elements according the order in which they are processed.

First pillar processed:

A:
first_key: blah
second_key: blah

Second pillar processed:

A:
third_key: blah
fourth_key: blah

will be merged as:

A:
third_key: blah
fourth_key: blah

• smart (default):

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

pillar_merge_lists
New in version 2015.8.0.

Default: False

Recursively merge lists by aggregating them instead of replacing them.

pillar_merge_lists: False

Pillar Cache Options
pillar_cache
New in version 2015.8.8.

Default: False

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

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

pillar_cache: False

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

pillar_cache_ttl
New in version 2015.8.8.

Default: 3600

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

pillar_cache_backend
New in version 2015.8.8.

Default: disk

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

• disk (default):

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

• memory [EXPERIMENTAL]:

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

pillar_cache_backend: disk

Master Reactor Settings
reactor
Default: []

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

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

reactor_refresh_interval
Default: 60

The TTL for the cache of the reactor configuration.

reactor_refresh_interval: 60

reactor_worker_threads
Default: 10

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

reactor_worker_hwm
Default: 10000

The queue size for workers in the reactor.

reactor_worker_hwm: 10000

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

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

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

order_masters
Default: False

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

order_masters: False

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

Default: masterofmasters

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

syndic_master: masterofmasters

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

syndic_master:
- masterofmasters1
- masterofmasters2

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

syndic_master_port
Default: 4506

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

syndic_master_port: 4506

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

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

syndic_pidfile: /var/run/syndic.pid

syndic_log_file
Default: /var/log/salt/syndic

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

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

syndic_failover
New in version 2016.3.0.

Default: random

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

syndic_failover: random

syndic_wait
Default: 5

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

syndic_wait: 5

syndic_forward_all_events
New in version 2017.7.0.

Default: False

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

syndic_forward_all_events: False

Peer Publish Settings
Salt minions can send commands to other minions, but only if the minion is allowed to. By
default "Peer Publication" is disabled, and when enabled it is enabled for specific
minions and specific commands. This allows secure compartmentalization of commands based
on individual minions.

peer
Default: {}

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

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

This will allow all minions to execute all commands:

peer:
.*:
- .*

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

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

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

peer_run
Default: {}

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

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

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

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

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

Examples:

log_file: /var/log/salt/master

log_file: file:///dev/log

log_file: udp://loghost:10514

log_level
Default: warning

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

log_level: warning

log_level_logfile
Default: warning

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

log_level_logfile: warning

log_datefmt
Default: %H:%M:%S

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

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

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

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

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

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

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

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

Console log colors are specified by these additional formatters:

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

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

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

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

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

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

log_granular_levels
Default: {}

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

Node Groups
Default: {}

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

nodegroups:
group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com'
group2: 'G@os:Debian and foo.domain.com'
group3: 'G@os:Debian and N@group1'
group4:
- 'G@foo:bar'
- 'or'
- 'G@foo:baz'

More information on using nodegroups can be found here.

Range Cluster Settings
range_server
Default: 'range:80'

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

range_server: range:80

Include Configuration
default_include
Default: master.d/*.conf

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

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

include
Default: not defined

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

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

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

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

Keepalive Settings
tcp_keepalive
Default: True

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

tcp_keepalive: True

tcp_keepalive_cnt
Default: -1

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

tcp_keepalive_cnt: -1

tcp_keepalive_idle
Default: 300

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

tcp_keepalive_idle: 300

tcp_keepalive_intvl
Default: -1

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

tcp_keepalive_intvl': -1

Windows Software Repo Settings
winrepo_provider
New in version 2015.8.0.

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

winrepo_provider: gitpython

winrepo_dir
Changed in version 2015.8.0: Renamed from win_repo to winrepo_dir.

Default: /srv/salt/win/repo

Location on the master where the winrepo_remotes are checked out for pre-2015.8.0 minions.
2015.8.0 and later minions use winrepo_remotes_ng instead.

winrepo_dir: /srv/salt/win/repo

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

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

Location on the master where the winrepo_remotes_ng are checked out for 2015.8.0 and later
minions.

winrepo_dir_ng: /srv/salt/win/repo-ng

winrepo_cachefile
Changed in version 2015.8.0: Renamed from win_repo_mastercachefile to winrepo_cachefile

NOTE:
2015.8.0 and later minions do not use this setting since the cachefile is now located
on the minion.

Default: winrepo.p

Path relative to winrepo_dir where the winrepo cache should be created.

winrepo_cachefile: winrepo.p

winrepo_remotes
Changed in version 2015.8.0: Renamed from win_gitrepos to winrepo_remotes.

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

List of git repositories to checkout and include in the winrepo for pre-2015.8.0 minions.
2015.8.0 and later minions use winrepo_remotes_ng instead.

winrepo_remotes:
- https://github.com/saltstack/salt-winrepo.git

To specify a specific revision of the repository, prepend a commit ID to the URL of the
repository:

winrepo_remotes:
- '<commit_id> https://github.com/saltstack/salt-winrepo.git'

Replace <commit_id> with the SHA1 hash of a commit ID. Specifying a commit ID is useful in
that it allows one to revert back to a previous version in the event that an error is
introduced in the latest revision of the repo.

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

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

List of git repositories to checkout and include in the winrepo for 2015.8.0 and later
minions.

winrepo_remotes_ng:
- https://github.com/saltstack/salt-winrepo-ng.git

To specify a specific revision of the repository, prepend a commit ID to the URL of the
repository:

winrepo_remotes_ng:
- '<commit_id> https://github.com/saltstack/salt-winrepo-ng.git'

winrepo_branch
New in version 2015.8.0.

Default: master

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

winrepo_branch: winrepo

ext_pillar:
- git:
- https://mygitserver/winrepo1.git
- https://mygitserver/winrepo2.git:
- foo https://mygitserver/winrepo3.git

winrepo_ssl_verify
New in version 2015.8.0.

Changed in version 2016.11.0.

Default: False

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

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

winrepo_ssl_verify: True

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

winrepo_user
New in version 2015.8.0.

Default: ''

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

winrepo_user: git

winrepo_password
New in version 2015.8.0.

Default: ''

Along with winrepo_user, is used to authenticate to HTTPS remotes. This parameter is not
required if the repository does not use authentication.

winrepo_password: mypassword

winrepo_insecure_auth
New in version 2015.8.0.

Default: False

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

winrepo_insecure_auth: True

winrepo_pubkey
New in version 2015.8.0.

Default: ''

Along with winrepo_privkey (and optionally winrepo_passphrase), is used to authenticate to
SSH remotes.

winrepo_pubkey: /path/to/key.pub

winrepo_privkey
New in version 2015.8.0.

Default: ''

Along with winrepo_pubkey (and optionally winrepo_passphrase), is used to authenticate to
SSH remotes.

winrepo_privkey: /path/to/key

winrepo_passphrase
New in version 2015.8.0.

Default: ''

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

winrepo_passphrase: mypassphrase

winrepo_refspecs
New in version 2017.7.0.

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

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

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

Configure Master on Windows
The master on Windows requires no additional configuration. You can modify the master
configuration by creating/editing the master config file located at c:\salt\conf\master.
The same configuration options available on Linux are available in Windows, as long as
they apply. For example, SSH options wouldn't apply in Windows. The main differences are
the file paths. If you are familiar with common salt paths, the following table may be
useful:

┌────────────┬───────┬───────────────┐
│linux Paths │ │ Windows Paths │
├────────────┼───────┼───────────────┤
│/etc/salt │ <---> │ c:\salt\conf │
├────────────┼───────┼───────────────┤
│/ │ <---> │ c:\salt │
└────────────┴───────┴───────────────┘

So, for example, the master config file in Linux is /etc/salt/master. In Windows the
master config file is c:\salt\conf\master. The Linux path /etc/salt becomes c:\salt\conf
in Windows.

Common File Locations
┌───────────────────────────────┬─────────────────────────────────┐
│Linux Paths │ Windows Paths │
├───────────────────────────────┼─────────────────────────────────┤
│conf_file: /etc/salt/master │ conf_file: c:\salt\conf\master │
├───────────────────────────────┼─────────────────────────────────┤
│log_file: /var/log/salt/master │ log_file: │
│ │ c:\salt\var\log\salt\master │
├───────────────────────────────┼─────────────────────────────────┤
│pidfile: │ pidfile: │
│/var/run/salt-master.pid │ c:\salt\var\run\salt-master.pid │
└───────────────────────────────┴─────────────────────────────────┘

Common Directories
───────────────────────────────────────────────────────────────────────────
Linux Paths Windows Paths
───────────────────────────────────────────────────────────────────────────
cachedir: /var/cache/salt/master cachedir:
c:\salt\var\cache\salt\master
───────────────────────────────────────────────────────────────────────────
extension_modules: c:\salt\var\cache\salt\master\extmods
/var/cache/salt/master/extmods
───────────────────────────────────────────────────────────────────────────
pki_dir: /etc/salt/pki/master pki_dir: c:\salt\conf\pki\master
───────────────────────────────────────────────────────────────────────────
root_dir: / root_dir: c:\salt
───────────────────────────────────────────────────────────────────────────
sock_dir: /var/run/salt/master sock_dir: c:\salt\var\run\salt\master
┌─────────────────────────────────┬───────────────────────────────────────┐
│ │ │
Roots │ │ │
--

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:
Grains resolve to lowercase letters. For example, FOO, and foo target the same grain.

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

salt '*' grains.ls

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

salt '*' grains.items

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:

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

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:

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

NOTE:
Grains in /etc/salt/grains are ignored if you specify the same grains in the minion
config.

NOTE:
Grains are static, and since they are not often changed, they will need a grains
refresh when they are updated. You can do this by calling: salt minion
saltutil.refresh_modules

NOTE:
You can equally configure static grains for Proxy Minions. As multiple Proxy Minion
processes can run on the same machine, you need to index the files using the Minion ID,
under /etc/salt/proxy.d/<minion ID>/grains. For example, the grains for the Proxy
Minion router1 can be defined under /etc/salt/proxy.d/router1/grains, while the grains
for the Proxy Minion switch7 can be put in /etc/salt/proxy.d/switch7/grains.

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:

'node_type:webserver':
- match: grain
- webserver

'node_type:postgres':
- match: grain
- postgres

'node_type:redis':
- match: grain
- redis

'node_type:lb':
- match: grain
- lb

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.

{% set the_node_type = salt['grains.get']('node_type', '') %}

{% if the_node_type %}
'node_type:{{ the_node_type }}':
- match: grain
- {{ the_node_type }}
{% endif %}

Using Jinja templating, only one match entry needs to be defined.

NOTE:
The example above uses the grains.get function to account for minions which do not have
the node_type grain set.

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:

def yourfunction():
# initialize a grains dictionary
grains = {}
# Some code for logic that sets grains like
grains['yourcustomgrain'] = True
grains['anothergrain'] = 'somevalue'
return grains

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:

...
...
{{ salt['module.function_name']('argument_1', 'argument_2') }}
{{ pillar['my_pillar_key'] }}
...
...

WARNING:
Custom grains will not be available in the top file until after the first highstate. To
make custom grains available on a minion's first highstate, it is recommended to use
this example to ensure that the custom grains are synced when the minion starts.

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:

#!/usr/bin/env python
def _my_custom_grain():
my_grain = {'foo': 'bar', 'hello': 'world'}
return my_grain

def main():
# initialize a grains dictionary
grains = {}
grains['my_grains'] = _my_custom_grain()
return grains

The output of this example renders like so:

# salt-call --local grains.items
local:
----------
<Snipped for brevity>
my_grains:
----------
foo:
bar
hello:
world

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:

# salt-call --local grains.items
local:
----------
<Snipped for brevity>
foo:
bar
<Snipped for brevity>
hello:
world
<Snipped for brevity>
my_grains:
----------
foo:
bar
hello:
world

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:

1. Core grains.

2. Custom grains in /etc/salt/grains.

3. Custom grains in /etc/salt/minion.

4. Custom grain modules in _grains directory, synced to minions.

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.

NOTE:
When the grains_cache is set to False, the grains dictionary is built and stored in
memory on the minion. Every time the minion restarts or saltutil.refresh_grains is run,
the grain dictionary is rebuilt from scratch.

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:
Storing sensitive data

Pillar data is compiled on the master. Additionally, pillar data for a given minion is
only accessible by the minion for which it is targeted in the pillar configuration.
This makes pillar useful for storing sensitive data specific to a particular minion.

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

pillar_roots:
base:
- /srv/pillar

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

base:
'*':
- packages

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:

base:
'*':
- packages
'web*':
- vim

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:

dev:
'os:Debian':
- match: grain
- servers

/srv/pillar/packages.sls

{% if grains['os'] == 'RedHat' %}
apache: httpd
git: git
{% elif grains['os'] == 'Debian' %}
apache: apache2
git: git-core
{% endif %}

company: Foo Industries

IMPORTANT:
See Is Targeting using Grain Data Secure? for important security information.

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:

apache:
pkg.installed:
- name: {{ pillar['apache'] }}

git:
pkg.installed:
- name: {{ pillar['git'] }}

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:

base:
'*':
- common_pillar

And the actual pillar file at '/srv/pillar/common_pillar.sls':

foo: bar
boo: baz

NOTE:
When working with multiple pillar environments, assuming that each pillar environment
has its own top file, the jinja placeholder {{ saltenv }} can be used in place of the
environment name:

{{ saltenv }}:
'*':
- common_pillar

Yes, this is {{ saltenv }}, and not {{ pillarenv }}. The reason for this is because the
Pillar top files are parsed using some of the same code which parses top files when
running states, so the pillar environment takes the place of {{ saltenv }} in the jinja
context.

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:

base:
'*':
- packages
- services

with packages.sls containing:

bind: bind9

and services.sls containing:

bind: named

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:
Pillar files are applied in the order they are listed in the top file. Therefore
conflicting keys will be overwritten in a 'last one wins' manner! For example, in the
above scenario conflicting key values in services will overwrite those in packages
because it's at the bottom of the list.

It can be better to structure your pillar files with more hierarchy. For example the
package.sls file could be configured like so:

packages:
bind: bind9

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:

bind:
package-name: bind9
version: 9.9.5

services.sls:

bind:
port: 53
listen-on: any

The resulting pillar dictionary will be:

$ salt-call pillar.get bind
local:
----------
listen-on:
any
package-name:
bind9
port:
53
version:
9.9.5

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:

include:
- users

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:

include:
- users:
defaults:
sudo: ['bob', 'paul']
key: users

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:

salt '*' saltutil.refresh_pillar

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:

• Running states

• Running pillar.items

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:

pillarenv: base

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:

salt '*' state.apply mystates pillarenv=testing

The above command will run the states with pillar data sourced exclusively from the
testing environment, without modifying the in-memory pillar data.

NOTE:
When running states, the pillarenv CLI option does not require a pillarenv option to be
set in the minion config file. When pillarenv is left unset, as mentioned above all
configured environments will be combined. Running states with pillarenv=testing in this
case would still restrict the states' pillar data to just that of the testing pillar
environment.

Starting in the 2017.7.0 release, it is possible to pin the pillarenv to the effective
saltenv, using the pillarenv_from_saltenv minion config option. When this is set to True,
if a specific saltenv is specified when running states, the pillarenv will be the same.
This essentially makes the following two commands equivalent:

salt '*' state.apply mystates saltenv=dev
salt '*' state.apply mystates saltenv=dev pillarenv=dev

However, if a pillarenv is specified, it will override this behavior. So, the following
command will use the qa pillar environment but source the SLS files from the dev saltenv:

salt '*' state.apply mystates saltenv=dev pillarenv=qa

So, if a pillarenv is set in the minion config file, pillarenv_from_saltenv will be
ignored, and passing a pillarenv on the CLI will temporarily override
pillarenv_from_saltenv.

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:

• pillar.item - Retrieves the value of one or more keys from the in-memory pillar datj.

• pillar.items - Compiles a fresh pillar dictionary and returns it, leaving the in-memory
pillar data untouched. If pillar keys are passed to this function however, this function
acts like pillar.item and returns their values from the in-memory pillar data.

• pillar.raw - Like pillar.items, it returns the entire pillar dictionary, but from the
in-memory pillar data instead of compiling fresh pillar data.

• pillar.get - Described in detail below.

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:

foo:
bar:
baz: qux

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:
pillar.get() vs salt['pillar.get']()

It should be noted that within templating, the pillar variable is just a dictionary.
This means that calling pillar.get() inside of a template will just use the default
dictionary .get() function which does not include the extra : delimiter functionality.
It must be called using the above syntax (salt['pillar.get']('foo:bar:baz', 'qux')) to
get the salt function, instead of the default dictionary behavior.

Setting Pillar Data at the Command Line
Pillar data can be set at the command line like the following example:

salt '*' state.apply pillar='{"cheese": "spam"}'

This will add a pillar key of cheese with its value set to spam.

NOTE:
Be aware that when sending sensitive data via pillar on the command-line that the
publication containing that data will be received by all minions and will not be
restricted to the targeted minions. This may represent a security concern in some
cases.

Pillar Encryption
Salt's renderer system can be used to decrypt pillar data. This allows for pillar items to
be stored in an encrypted state, and decrypted during pillar compilation.

Encrypted Pillar SLS
New in version 2017.7.0.

Consider the following pillar SLS file:

secrets:
vault:
foo: |

-----END PGP MESSAGE-----
When the pillar data is compiled, the results will be decrypted:

# salt myminion pillar.items
myminion:
----------
secrets:
----------
vault:
----------
bar:
this was unencrypted already
baz:
rosebud
foo:
supersecret
qux:
- foo
- bar
- baz

Salt must be told what portions of the pillar data to decrypt. This is done using the
decrypt_pillar config option:

decrypt_pillar:
- 'secrets:vault': gpg

The notation used to specify the pillar item(s) to be decrypted is the same as the one
used in pillar.get function.

If a different delimiter is needed, it can be specified using the decrypt_pillar_delimiter
config option:

decrypt_pillar:
- 'secrets|vault': gpg

decrypt_pillar_delimiter: '|'

The name of the renderer used to decrypt a given pillar item can be omitted, and if so it
will fall back to the value specified by the decrypt_pillar_default config option, which
defaults to gpg. So, the first example above could be rewritten as:

decrypt_pillar:
- 'secrets:vault'

Encrypted Pillar Data on the CLI
New in version 2016.3.0.

The following functions support passing pillar data on the CLI via the pillar argument:

• pillar.items

• state.apply

• state.highstate

• state.sls

Triggerring decryption of this CLI pillar data can be done in one of two ways:

1. Using the pillar_enc argument:

# salt myminion pillar.items pillar_enc=gpg pillar='{foo: "-----BEGIN PGP MESSAGE-----\n\nhQEMAw2B674HRhwSAQf+OvPqEdDoA2fk15I5dYUTDoj1yf/pVolAma6iU4v8Zixn\nRDgWsaAnFz99FEiFACsAGDEFdZaVOxG80T0Lj+PnW4pVy0OXmXHnY2KjV9zx8FLS\nQxfvmhRR4t23WSFybozfMm0lsN8r1vfBBjbK+A72l0oxN78d1rybJ6PWNZiXi+aC\nmqIeunIbAKQ21w/OvZHhxH7cnIiGQIHc7N9nQH7ibyoKQzQMSZeilSMGr2abAHun\nmLzscr4wKMb+81Z0/fdBfP6g3bLWMJga3hSzSldU9ovu7KR8rDJI1qOlENj3Wm8C\nwTpDOB33kWIKMqiAjY3JFtb5MCHrafyggwQL7cX1+tI+AbSO6kZpbcDfzetb77LZ\nxc5NWnnGK4pGoqq4MAmZshw98RpecSHKMosto2gtiuWCuo9Zn5cV/FbjZ9CTWrQ=\n=0hO/\n-----END PGP MESSAGE-----"}'

The newlines in this example are specified using a literal \n. Newlines can be replaced
with a literal \n using sed:

$ echo -n bar | gpg --armor --trust-model always --encrypt -r user@domain.tld | sed ':a;N;$!ba;s/\n/\\n/g'

NOTE:
Using pillar_enc will perform the decryption minion-side, so for this to work it
will be necessary to set up the keyring in /etc/salt/gpgkeys on the minion just as
one would typically do on the master. The easiest way to do this is to first export
the keys from the master:

# gpg --homedir /etc/salt/gpgkeys --export-secret-key -a user@domain.tld >/tmp/keypair.gpg

Then, copy the file to the minion, setup the keyring, and import:

# mkdir -p /etc/salt/gpgkeys
# chmod 0700 /etc/salt/gpgkeys
# gpg --homedir /etc/salt/gpgkeys --list-keys
# gpg --homedir /etc/salt/gpgkeys --import --allow-secret-key-import keypair.gpg

The --list-keys command is run create a keyring in the newly-created directory.

Pillar data which is decrypted minion-side will still be securely transferred to the
master, since the data sent between minion and master is encrypted with the master's
public key.

2. Use the decrypt_pillar option. This is less flexible in that the pillar key passed on
the CLI must be pre-configured on the master, but it doesn't require a keyring to be
setup on the minion. One other caveat to this method is that pillar decryption on the
master happens at the end of pillar compilation, so if the encrypted pillar data being
passed on the CLI needs to be referenced by pillar or ext_pillar during pillar
compilation, it must be decrypted minion-side.

Adding New Renderers for Decryption
Those looking to add new renderers for decryption should look at the gpg renderer for an
example of how to do so. The function that performs the decryption should be recursive and
be able to traverse a mutable type such as a dictionary, and modify the values in-place.

Once the renderer has been written, decrypt_pillar_renderers should be modified so that
Salt allows it to be used for decryption.

If the renderer is being submitted upstream to the Salt project, the renderer should be
added in salt/renderers/. Additionally, the following should be done:

• Both occurrences of decrypt_pillar_renderers in salt/config/__init__.py should be
updated to include the name of the new renderer so that it is included in the default
value for this config option.

• The documentation for the decrypt_pillar_renderers config option in the master config
file and minion config file should be updated to show the correct new default value.

• The commented example for the decrypt_pillar_renderers config option in the master
config template should be updated to show the correct new default value.

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:

pillar_opts: True

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:

mysql.pass: hardtoguesspassword

Master Provided Pillar Error
By default if there is an error rendering a pillar, the detailed error is hidden and
replaced with:

Rendering SLS 'my.sls' failed. Please see master log for details.

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

Pillar Walkthrough
NOTE:
This walkthrough assumes that the reader has already completed the initial Salt
walkthrough.

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:
Grains and Pillar are sometimes confused, just remember that Grains are data about a
minion which is stored or generated from the minion. This is why information like the
OS and CPU type are found in Grains. Pillar is information about a minion or many
minions stored or generated on the Salt Master.

Pillar data is useful for:

Highly Sensitive Data:
Information transferred via pillar is guaranteed to only be presented to the
minions that are targeted, making Pillar suitable for managing security
information, such as cryptographic keys and passwords.

Minion Configuration:
Minion modules such as the execution modules, states, and returners can often be
configured via data stored in pillar.

Variables:
Variables which need to be assigned to specific minions or groups of minions can be
defined in pillar and then accessed inside sls formulas and template files.

Arbitrary Data:
Pillar can contain any basic data structure in dictionary format, so a key/value
store can be defined making it easy to iterate over a group of values in sls
formulas.

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:

salt '*' pillar.items

NOTE:
Prior to version 0.16.2, this function is named pillar.data. This function name is
still supported for backwards compatibility.

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:
The pillar location can be configured via the pillar_roots option inside the master
configuration file. It must not be in a subdirectory of the state tree or file_roots.
If the pillar is under file_roots, any pillar targeting can be bypassed by minions.

To start setting up the pillar, the /srv/pillar directory needs to be present:

mkdir /srv/pillar

Now create a simple top file, following the same format as the top file used for states:

/srv/pillar/top.sls:

base:
'*':
- data

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:

info: some data

To ensure that the minions have the new pillar data, issue a command to them asking that
they fetch their pillars from the master:

salt '*' saltutil.refresh_pillar

Now that the minions have the new pillar, it can be retrieved:

salt '*' pillar.items

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:

users:
thatch: 1000
shouse: 1001
utahdave: 1002
redbeard: 1003

NOTE:
The same directory lookups that exist in states exist in pillar, so the file
users/init.sls can be referenced with users in the top file.

The top file will need to be updated to include this sls file:

/srv/pillar/top.sls:

base:
'*':
- data
- users

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

{% for user, uid in pillar.get('users', {}).items() %}
{{user}}:
user.present:
- uid: {{uid}}
{% endfor %}

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:

pkgs:
{% if grains['os_family'] == 'RedHat' %}
apache: httpd
vim: vim-enhanced
{% elif grains['os_family'] == 'Debian' %}
apache: apache2
vim: vim
{% elif grains['os'] == 'Arch' %}
apache: apache
vim: vim
{% endif %}

The new pkg sls needs to be added to the top file:

/srv/pillar/top.sls:

base:
'*':
- data
- users
- pkg

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:

apache:
pkg.installed:
- name: {{ pillar['pkgs']['apache'] }}

Or, if no pillar is available a default can be set as well:

NOTE:
The function pillar.get used in this example was added to Salt in version 0.14.0

/srv/salt/apache/init.sls:

apache:
pkg.installed:
- name: {{ salt['pillar.get']('pkgs:apache', 'httpd') }}

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:
Under the hood, pillar is just a Python dict, so Python dict methods such as get and
items can be used.

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:

vim:
pkg.installed: []

/etc/vimrc:
file.managed:
- source: salt://edit/vimrc
- mode: 644
- user: root
- group: root
- require:
- pkg: vim

Can be easily transformed into a powerful, parameterized formula:

/srv/salt/edit/vim.sls:

vim:
pkg.installed:
- name: {{ pillar['pkgs']['vim'] }}

/etc/vimrc:
file.managed:
- source: {{ pillar['vimrc'] }}
- mode: 644
- user: root
- group: root
- require:
- pkg: vim

Where the vimrc source location can now be changed via pillar:

/srv/pillar/edit/vim.sls:

{% if grains['id'].startswith('dev') %}
vimrc: salt://edit/dev_vimrc
{% elif grains['id'].startswith('qa') %}
vimrc: salt://edit/qa_vimrc
{% else %}
vimrc: salt://edit/vimrc
{% endif %}

Ensuring that the right vimrc is sent out to the correct minions.

The pillar top file must include a reference to the new sls pillar file:

/srv/pillar/top.sls:

base:
'*':
- pkg
- edit.vim

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:

salt '*' state.apply pillar='{"foo": "bar"}'
salt '*' state.apply my_sls_file pillar='{"hello": "world"}'

Nested pillar values can also be set via the command line:

salt '*' state.sls my_sls_file pillar='{"foo": {"bar": "baz"}}'

NOTE:
If a key is passed on the command line that already exists on the minion, the key that
is passed in will overwrite the entire value of that key, rather than merging only the
specified value set via the command line.

The example below will swap the value for vim with telnet in the previously specified
list, notice the nested pillar dict:

salt '*' state.apply edit.vim pillar='{"pkgs": {"vim": "telnet"}}'

This will attempt to install telnet on your minions, feel free to uninstall the package or
replace telnet value with anything else.

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

mysql.pass: hardtoguesspassword

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:

mysql-admin-passwd:
mysql_user.present:
- name: root
- password: somepasswd

mydb:
mysql_db.present

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:

base:
'web1':
- webserver

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 glob expression: "os:Arch*".

salt -G 'os:Fedora' test.ping

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:

salt '*' grains.items

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:

salt -C 'G@os:Debian and webser* or E@db.*' test.ping

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.

nodegroups:
group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com'
group2: 'G@os:Debian and foo.domain.com'
group3: 'G@os:Debian and N@group1'

Advanced Targeting Methods
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:
minion id and minion keys

The minion id is used to generate the minion's public/private keys and if it ever
changes the master must then accept the new key as though the minion was a new host.

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:
You must wrap salt calls that use globbing in single-quotes to prevent the shell from
expanding the globs before Salt is invoked.

Match all minions:

salt '*' test.ping

Match all minions in the example.net domain or any of the example domains:

salt '*.example.net' test.ping
salt '*.example.*' test.ping

Match all the webN minions in the example.net domain (web1.example.net, web2.example.net …
webN.example.net):

salt 'web?.example.net' test.ping

Match the web1 through web5 minions:

salt 'web[1-5]' test.ping

Match the web1 and web3 minions:

salt 'web[1,3]' test.ping

Match the web-x, web-y, and web-z minions:

salt 'web-[x-z]' test.ping

NOTE:
For additional targeting methods please review the compound matchers documentation.

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:

salt -E 'web1-(prod|devel)' test.ping

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.

base:
'web1-(prod|devel)':
- match: pcre
- webserver

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

salt -L 'web1,web2,web3' test.ping

Targeting using Grains
Grain data can be used when targeting minions.

For example, the following matches all CentOS minions:

salt -G 'os:CentOS' test.ping

Match all minions with 64-bit CPUs, and return number of CPU cores for each matching
minion:

salt -G 'cpuarch:x86_64' grains.item num_cpus

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:

salt -G 'ec2_tags:environment:*production*'

IMPORTANT:
See Is Targeting using Grain Data Secure? for important security information.

Targeting using Pillar
Pillar data can be used when targeting minions. This allows for ultimate control and
flexibility when targeting minions.

NOTE:
To start using Pillar targeting it is required to make a Pillar data cache on Salt
Master for each Minion via following commands: salt '*' saltutil.refresh_pillar or salt
'*' saltutil.sync_all. Also Pillar data cache will be populated during the highstate
run. Once Pillar data changes, you must refresh the cache by running above commands for
this targeting method to work correctly.

Example:

salt -I 'somekey:specialvalue' test.ping

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:

salt -I 'foo:bar:baz*' test.ping

Subnet/IP Address Matching
Minions can easily be matched based on IP address, or by subnet (using CIDR notation).

salt -S 192.168.40.20 test.ping
salt -S 2001:db8::/64 test.ping

Ipcidr matching can also be used in compound matches

salt -C 'S@10.0.0.0/24 and G@os:Debian' test.ping

It is also possible to use in both pillar and state-matching

'172.16.0.0/12':
- match: ipcidr
- internal

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 │ No │
│ │ │ or bl*.domain.com │ │
├───────┼───────────────────┼──────────────────────────────────────────┼────────────────┤
│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.*:

salt -C 'webserv* and G@os:Debian or E@web-dc1-srv.*' test.ping

That same example expressed in a top file looks like the following:

base:
'webserv* and G@os:Debian or E@web-dc1-srv.*':
- match: compound
- webserver

New in version 2015.8.0.

Excluding a minion based on its ID is also possible:

salt -C 'not web-dc1-srv' test.ping

Versions prior to 2015.8.0 a leading not was not supported in compound matches. Instead,
something like the following was required:

salt -C '* and not G@kernel:Darwin' test.ping

Excluding a minion based on its ID was also possible:

salt -C '* and not web-dc1-srv' test.ping

Precedence Matching
Matchers can be grouped together with parentheses to explicitly declare precedence amongst
groups.

salt -C '( ms-1 or G@id:ms-3 ) and G@id:ms-3' test.ping

NOTE:
Be certain to note that spaces are required between the parentheses and targets.
Failing to obey this rule may result in incorrect targeting!

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.

salt -C 'J|@foo|bar|^foo:bar$ or J!@gitrepo!https://github.com:example/project.git' test.ping

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:
The L within group1 is matching a list of minions, while the G in group2 is matching
specific grains. See the compound matchers documentation for more details.

As of the 2017.7.0 release of Salt, group names can also be prepended with a dash. This
brings the usage in line with many other areas of Salt. For example:

nodegroups:
- group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com'

New in version 2015.8.0.

NOTE:
Nodegroups can reference other nodegroups as seen in group3. Ensure that you do not
have circular references. Circular references will be detected and cause partial
expansion with a logged error message.

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:

salt -N group1 test.ping

NOTE:
The N@ classifier cannot be used in compound matches within the CLI or top file, it is
only recognized in the nodegroups master config file parameter.

To match a nodegroup in your top file, make sure to put - match: nodegroup on the line
directly following the nodegroup name.

base:
group1:
- match: nodegroup
- webserver

NOTE:
When adding or modifying nodegroups to a master configuration file, the master must be
restarted for those changes to be fully recognized.

A limited amount of functionality, such as targeting with -N from the command-line may
be available without a restart.

Defining Nodegroups as Lists of Minion IDs
A simple list of minion IDs would traditionally be defined like this:

nodegroups:
group1: L@host1,host2,host3

They can now also be defined as a YAML list, like this:

nodegroups:
group1:
- host1
- host2
- host3

New in version 2016.11.0.

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.

salt '*' -b 10 test.ping

salt -G 'os:RedHat' --batch-size 25% apache.signal restart

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:

python -c 'import seco.range'

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:

range_server: my.range.server.com:80

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:

$ cat /etc/range/test.yaml
CLUSTER: host1..100.test.com
APPS:
- frontend
- backend
- mysql

One might target host1 through host100 in the test.com domain with Salt as follows:

salt --range %test:CLUSTER test.ping

The following salt command would target three hosts: frontend, backend, and mysql:

salt --range %test:APPS test.ping

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. The list of functions are available in the salt.module. If no arguments
are passed, an empty list must be added like in the test.ping function in the example
below:

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

In the example above salt.modules.network.ip_addrs has additional filters to help narrow
down the results. In the above example IP addresses are only returned if they are on a
eth0 interface and in the 10.0.0.0/8 IP range.

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_functions:
network.ip_addrs: [eth0]
networkplus.internal_ip_addrs: []
internal_ip_addrs:
mine_function: network.ip_addrs
cidr: 192.168.0.0/16
ip_list:
- mine_function: grains.get
- ip_interfaces

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

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:

1. Roster data

2. Pillar

3. Master config

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:

test:
host: 104.237.131.248
user: root
mine_functions:
cmd.run: ['echo "hello!"']
network.ip_addrs:
interface: eth0

NOTE:
Because of the differences in the architecture of salt-ssh, mine.get calls are somewhat
inefficient. Salt must make a new salt-ssh call to each of the Minions in question to
retrieve the requested data, much like a publish call. However, unlike publish, it must
run the requested function as a wrapper function, so we can retrieve the function args
from the pillar of the Minion in question. This results in a non-trivial delay in
retrieving the requested data.

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:
Pillar data needs to be cached on Master for pillar targeting to work with Mine. Read
the note in relevant section.

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:

base:
'G@roles:web':
- web

/srv/pillar/web.sls:

mine_functions:
network.ip_addrs: [eth0]

Then trigger the minions to refresh their pillar data by running:

salt '*' saltutil.refresh_pillar

Verify that the results are showing up in the pillar on the minions by executing the
following and checking for network.ip_addrs in the output:

salt '*' pillar.items

Which should show that the function is present on the minion, but not include the output:

minion1.example.com:
----------
mine_functions:
----------
network.ip_addrs:
- eth0

Mine data is typically only updated on the master every 60 minutes, this can be modified
by setting:

/etc/salt/minion.d/mine.conf:

mine_interval: 5

To force the mine data to update immediately run:

salt '*' mine.update

Setup the salt.states.file.managed state in /srv/salt/haproxy.sls:

haproxy_config:
file.managed:
- name: /etc/haproxy/config
- source: salt://haproxy_config
- template: jinja

Create the Jinja template in /srv/salt/haproxy_config:

<...file contents snipped...>

{% for server, addrs in salt['mine.get']('roles:web', 'network.ip_addrs', tgt_type='grain') | dictsort() %}
server {{ server }} {{ addrs[0] }}:80 check
{% endfor %}

<...file contents snipped...>

In the above example, server will be expanded to the minion_id.

NOTE:
The expr_form argument will be renamed to tgt_type in the 2017.7.0 release of Salt.

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.

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.

          Full list of execution modules
                 Contains: a list of core modules that ship with Salt.

          Writing execution modules
                 Contains: a guide on how to write Salt modules.

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

          Stuck?

                 There  are  many  ways to get help from the Salt community including our mailing
                 list and our IRC channel #salt.

   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:

          salt '<target>' <function> [arguments]

       SEE ALSO:
          salt manpage

   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:

          salt '*' test.ping
          salt '*.example.org' test.ping

       Targets can be based on minion system information using the Grains system:

          salt -G 'os:Ubuntu' test.ping

       SEE ALSO:
          Grains system

       Targets can be filtered by regular expression:

          salt -E 'virtmach[0-9]' test.ping

       Targets can be explicitly specified in a list:

          salt -L 'foo,bar,baz,quo' test.ping

       Or Multiple target types can be combined in one command:

          salt -C 'G@os:Ubuntu and webser* or E@database.*' test.ping

   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:

          salt '*' sys.doc

       Here are some examples:

       Show all currently available minions:

          salt '*' test.ping

       Run an arbitrary shell command:

          salt '*' cmd.run 'uname -a'

       SEE ALSO:
          the full list of modules

   arguments
       Space-delimited arguments to the function:

          salt '*' cmd.exec_code python 'import sys; print sys.version'

       Optional, keyword arguments are also supported:

          salt '*' pip.install salt timeout=5 upgrade=True

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

   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 '*foo.com' sys.doc

       Salt can also define the target minions with regular expressions:

          salt -E '.*' cmd.run 'ls -l | grep foo'

       Or to explicitly list hosts, salt can take a list:

          salt -L foo.bar.baz,quo.qux cmd.run 'ps aux | grep foo'

   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:

          salt '*' cmd.exec_code python 'import sys; print sys.version'

       Optional, keyword arguments are also supported:

          salt '*' pip.install salt timeout=5 upgrade=True

       They are always in the form of kwarg=argument.

       Arguments are formatted as YAML:

          salt '*' cmd.run 'echo "Hello: $FIRST_NAME"' saltenv='{FIRST_NAME: "Joe"}'

       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:

          salt '*' test.arg_repr 'echo "Hello: $FIRST_NAME"' saltenv='{FIRST_NAME: "Joe"}'

   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:

          salt '*' sys.doc

   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:

          salt '*' cmd.run,test.ping,test.echo 'cat /proc/cpuinfo',,foo

       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:

          salt '*' cmd.run,test.ping,test.echo 'echo "1,2,3"' , , foo

       You may change the arguments separator using the --args-separator option:

          salt --args-separator=:: '*' some.fun,test.echo params with , comma :: foo

   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:

       • state.apply

       • saltutil.sync_modules

       • saltutil.sync_all

       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.

          modules $ ls -R lumberjack
          __init__.py     sleep           work

          lumberjack/sleep:
          __init__.py

          lumberjack/work:
          __init__.py

       The  contents  of  lumberjack/__init__.py  show  how  to  import  and  use  these included
       libraries.

          # Libraries included in lumberjack.zip
          from lumberjack import sleep, work

          def is_ok(person):
              ''' Checks whether a person is really a lumberjack '''
              return sleep.all_night(person) and work.all_day(person)

       Then, create the zip:

          modules $ zip -r lumberjack lumberjack
            adding: lumberjack/ (stored 0%)
            adding: lumberjack/__init__.py (deflated 39%)
            adding: lumberjack/sleep/ (stored 0%)
            adding: lumberjack/sleep/__init__.py (deflated 7%)
            adding: lumberjack/work/ (stored 0%)
            adding: lumberjack/work/__init__.py (deflated 7%)
          modules $ unzip -l lumberjack.zip
          Archive:  lumberjack.zip
            Length     Date   Time    Name
           --------    ----   ----    ----
                  0  08-21-15 20:08   lumberjack/
                348  08-21-15 20:08   lumberjack/__init__.py
                  0  08-21-15 19:53   lumberjack/sleep/
                 83  08-21-15 19:53   lumberjack/sleep/__init__.py
                  0  08-21-15 19:53   lumberjack/work/
                 81  08-21-15 19:21   lumberjack/work/__init__.py
           --------                   -------
                512                   6 files

       Once placed in file_roots, Salt users can distribute and use lumberjack.zip like any other
       module.

          $ sudo salt minion1 saltutil.sync_modules
          minion1:
            - modules.lumberjack
          $ sudo salt minion1 lumberjack.is_ok 'Michael Palin'
          minion1:
            True

   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:

          def foo(bar):
              return __salt__['cmd.run'](bar)

       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:

          salt 'hostname' grains.items --output=pprint

       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.

          __outputter__ = {
              'run': 'txt'
          }

       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:
          Modules which return a string from __virtual__ that is already used by  a  module  that
          ships with Salt will _override_ the stock module.

   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.

          '''
          Cheese execution (or returner/beacon/etc.) module
          '''
          try:
              import enzymes
              HAS_ENZYMES = True
          except ImportError:
              HAS_ENZYMES = False

          def __virtual__():
              '''
              only load cheese if enzymes are available
              '''
              if HAS_ENZYMES:
                  return 'cheese'
              else:
                  return False, 'The cheese execution module cannot be loaded: enzymes unavailable.'

          '''
          Cheese state module
          '''

          def __virtual__():
              '''
              only load cheese if enzymes are available
              '''
              # predicate loading of the cheese state on the corresponding execution module
              if 'cheese.slice' in __salt__:
                  return 'cheese'
              else:
                  return False, 'The cheese state module cannot be loaded: enzymes 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):

       • pkg

       • service

       • user

       • shadow

       • group

       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:

          providers:
            service: systemd
            pkg: aptpkg

       The above example will force the minion to use  the  systemd  module  to  provide  service
       management, and the aptpkg module to provide package management.

   Logging Restrictions
       As  a rule, logging should not be done anywhere in a Salt module before it is loaded. This
       rule apples to all code that would run before the __virtual__() function, as well  as  the
       code within the __virtual__() function itself.

       If logging statements are made before the virtual function determines if the module should
       be loaded, then those logging statements will be called repeatedly. This clutters  up  log
       files unnecessarily.

       Exceptions  may be considered for logging statements made at the trace level.  However, it
       is better to provide the necessary information by another means.  One method is to  return
       error information in the __virtual__() function.

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

          # Define the module's virtual name
          __virtualname__ = 'pkg'

          def __virtual__():
              '''
              Confine this module to Mac OS with Homebrew.
              '''

              if salt.utils.which('brew') and __grains__['os'] == 'MacOS':
                  return __virtualname__
              return False

       The __virtual__() function can return a True or False boolean, a tuple, or a string. If it
       returns  a  True  value, this __virtualname__ module-level attribute can be set as seen in
       the above example. This is the string that the module should be referred to as.

       When __virtual__() returns a tuple, the first item should be  a  boolean  and  the  second
       should  be  a  string.  This  is typically done when the module should not load. The first
       value of the tuple is False and the second is the error message to  display  for  why  the
       module did not load.

       For example:

          def __virtual__():
              '''
              Only load if git exists on the system
              '''
              if salt.utils.which('git') is None:
                  return (False,
                          'The git execution module cannot be loaded: git unavailable.')
              else:
                  return True

   Documentation
       Salt   execution   modules   are  documented.  The  sys.doc()  function  will  return  the
       documentation for all available modules:

          salt '*' sys.doc

       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.

          def spam(eggs):
              '''
              A function to make some spam with eggs!

              CLI Example::

                  salt '*' test.spam eggs
              '''
              return eggs

       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:

          :maintainer:    Thomas Hatch <thatch@saltstack.com, Seth House <shouse@saltstack.com>
          :maturity:      new
          :depends:       python-mysqldb
          :platform:      all

       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:

          import logging

          log = logging.getLogger(__name__)

          log.info('Here is Some Information')
          log.warning('You Should Not Do That')
          log.error('It Is Busted')

   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.

          __func_alias__ = {
              'set_': 'set',
              'list_': 'list',
          }

   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
          def foo(bar):
              return bar

   Objects NOT Loaded into the Salt Minion
          def _foobar(baz): # Preceded with an _
              return baz

          cheese = {} # Not a callable Python object

   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

          import logging

          from salt.utils.decorators import depends

          log = logging.getLogger(__name__)

          try:
              import dependency_that_sometimes_exists
          except ImportError as e:
              log.trace('Failed to import dependency_that_sometimes_exists: {0}'.format(e))

          @depends('dependency_that_sometimes_exists')
          def foo():
              '''
              Function with a dependency on the "dependency_that_sometimes_exists" module,
              if the "dependency_that_sometimes_exists" is missing this function will not exist
              '''
              return True

          def _fallback():
              '''
              Fallback function for the depends decorator to replace a function with
              '''
              return '"dependency_that_sometimes_exists" needs to be installed for this function to exist'

          @depends('dependency_that_sometimes_exists', fallback_function=_fallback)
          def foo():
              '''
              Function with a dependency on the "dependency_that_sometimes_exists" module.
              If the "dependency_that_sometimes_exists" is missing this function will be
              replaced with "_fallback"
              '''
              return True

       In addition to global dependencies the depends decorator also supports raw booleans.

          from salt.utils.decorators import depends

          HAS_DEP = False
          try:
              import dependency_that_sometimes_exists
              HAS_DEP = True
          except ImportError:
              pass

          @depends(HAS_DEP)
          def foo():
              return True

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.

States Express the state of a host using small, easy to read, easy to understand
configuration files. No programming required.

Full list of states
Contains: list of install packages, create users, transfer files, start
services, and so on.

Pillar System
Contains: description of Salt's Pillar system.

Highstate data structure
Contains: a dry vocabulary and technical representation of the configuration
format that states represent.

Writing states
Contains: a guide on how to write Salt state modules, easily extending Salt
to directly manage more software.

NOTE:
Salt execution modules are different from state modules and cannot be called as a state
in an SLS file. In other words, this will not work:

moe:
user.rename:
- new_name: larry
- onlyif: id moe

You must use the module states to call execution modules directly. Here's an example:

rename_moe:
module.run:
- m_name: moe
- new_name: larry
- onlyif: id moe

Renderers
Renderers use state configuration files written in a variety of languages,
templating engines, or files. Salt's configuration management system is, under the
hood, language agnostic.

Full list of renderers
Contains: a list of renderers. YAML is one choice, but many systems are
available, from alternative templating engines to the PyDSL language for
rendering sls formulas.

Renderers
Contains: more information about renderers. Salt states are only concerned
with the ultimate highstate data structure, not how the data structure was
created.

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:
This is just the beginning of using states, make sure to read up on pillar Pillar next.

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:
These demos use some generic service and package names, different distributions often
use different names for packages and services. For instance apache should be replaced
with httpd on a Red Hat system. Salt uses the name of the init script, systemd name,
upstart name etc. based on what the underlying service management for the platform. To
get a list of the available service names on a platform execute the service.get_all
salt function.

Information on how to make states work with multiple distributions is later in the
tutorial.

apache:
pkg.installed: []
service.running:
- require:
- pkg: apache

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.

apache:
pkg.installed: []
service.running:
- watch:
- pkg: apache
- file: /etc/httpd/conf/httpd.conf
- user: apache
user.present:
- uid: 87
- gid: 87
- home: /var/www/html
- shell: /bin/nologin
- require:
- group: apache
group.present:
- gid: 87
- require:
- pkg: apache

/etc/httpd/conf/httpd.conf:
file.managed:
- source: salt://apache/httpd.conf
- user: root
- group: root
- mode: 644

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:

apache/init.sls
apache/httpd.conf

So the httpd.conf is just a file in the apache directory, and is referenced directly.

Do not use dots in SLS file names or their directories

The initial implementation of top.sls and include-declaration followed the
python import model where a slash is represented as a period. This means that a
SLS file with a period in the name ( besides the suffix period) can not be
referenced. For example, webserver_1.0.sls is not referenceable because
webserver_1.0 would refer to the directory/file webserver_1/0.sls

The same applies for any subdirectories, this is especially 'tricky' when git
repos are created. Another command that typically can't render it's output is
`state.show_sls` of a file in a path that contains a dot.

But when using more than one single SLS file, more components can be added to the toolkit.
Consider this SSH example:

ssh/init.sls:

openssh-client:
pkg.installed

/etc/ssh/ssh_config:
file.managed:
- user: root
- group: root
- mode: 644
- source: salt://ssh/ssh_config
- require:
- pkg: openssh-client

ssh/server.sls:

include:
- ssh

openssh-server:
pkg.installed

sshd:
service.running:
- require:
- pkg: openssh-client
- pkg: openssh-server
- file: /etc/ssh/banner
- file: /etc/ssh/sshd_config

/etc/ssh/sshd_config:
file.managed:
- user: root
- group: root
- mode: 644
- source: salt://ssh/sshd_config
- require:
- pkg: openssh-server

/etc/ssh/banner:
file:
- managed
- user: root
- group: root
- mode: 644
- source: salt://ssh/banner
- require:
- pkg: openssh-server

NOTE:
Notice that we use two similar ways of denoting that a file is managed by Salt. In the
/etc/ssh/sshd_config state section above, we use the file.managed state declaration
whereas with the /etc/ssh/banner state section, we use the file state declaration and
add a managed attribute to that state declaration. Both ways produce an identical
result; the first way -- using file.managed -- is merely a shortcut.

Now our State Tree looks like this:

apache/init.sls
apache/httpd.conf
ssh/init.sls
ssh/server.sls
ssh/banner
ssh/ssh_config
ssh/sshd_config

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:

include:
- ssh.server

extend:
/etc/ssh/banner:
file:
- source: salt://ssh/custom-banner

python/mod_python.sls:

include:
- apache

extend:
apache:
service:
- watch:
- pkg: mod_python

mod_python:
pkg.installed

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.

Using extend with require or watch

The extend statement works differently for require or watch. It appends to,
rather than replacing the requisite component.

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:
The templating engines described above aren't just available in SLS files. They can
also be used in file.managed states, making file management much more dynamic and
flexible. Some examples for using templates in managed files can be found in the
documentation for the file state, as well as the MooseFS example below.

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:

apache:
pkg.installed:
{% if grains['os'] == 'RedHat'%}
- name: httpd
{% endif %}
service.running:
{% if grains['os'] == 'RedHat'%}
- name: httpd
{% endif %}
- watch:
- pkg: apache
- file: /etc/httpd/conf/httpd.conf
- user: apache
user.present:
- uid: 87
- gid: 87
- home: /var/www/html
- shell: /bin/nologin
- require:
- group: apache
group.present:
- gid: 87
- require:
- pkg: apache

/etc/httpd/conf/httpd.conf:
file.managed:
- source: salt://apache/httpd.conf
- user: root
- group: root
- mode: 644

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:

include:
- moosefs

{% for mnt in salt['cmd.run']('ls /dev/data/moose*').split() %}
/mnt/moose{{ mnt[-1] }}:
mount.mounted:
- device: {{ mnt }}
- fstype: xfs
- mkmnt: True
file.directory:
- user: mfs
- group: mfs
- require:
- user: mfs
- group: mfs
{% endfor %}

/etc/mfshdd.cfg:
file.managed:
- source: salt://moosefs/mfshdd.cfg
- user: root
- group: root
- mode: 644
- template: jinja
- require:
- pkg: mfs-chunkserver

/etc/mfschunkserver.cfg:
file.managed:
- source: salt://moosefs/mfschunkserver.cfg
- user: root
- group: root
- mode: 644
- template: jinja
- require:
- pkg: mfs-chunkserver

mfs-chunkserver:
pkg.installed: []
mfschunkserver:
service.running:
- require:
{% for mnt in salt['cmd.run']('ls /dev/data/moose*') %}
- mount: /mnt/moose{{ mnt[-1] }}
- file: /mnt/moose{{ mnt[-1] }}
{% endfor %}
- file: /etc/mfschunkserver.cfg
- file: /etc/mfshdd.cfg
- file: /var/lib/mfs

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:

#!py

def run():
'''
Install the django package
'''
return {'include': ['python'],
'django': {'pkg': ['installed']}}

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:

#!pydsl

include('python', delayed=True)
state('django').pkg.installed()

The pyobjects renderer provides an "Pythonic" object based approach for building the state
data. The above example could be written as:

#!pyobjects

include('python')
Pkg.installed("django")

These Python examples would look like this if they were written in YAML:

include:
- python

django:
pkg.installed

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:

salt-call state.apply -l debug

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

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.

Stuck?

There are many ways to get help from the Salt community including our mailing
list and our IRC channel #salt.

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:

file_roots:
base:
- /srv/salt

NOTE:
If you are deploying on FreeBSD via ports, the file_roots path defaults to
/usr/local/etc/salt/states.

Restart the Salt master in order to pick up this change:

pkill salt-master
salt-master -d

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:

base:
'*':
- webserver

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

Targeting minions

The expressions can use any of the targeting mechanisms used by Salt — minions
can be matched by glob, PCRE regular expression, or by grains. For example:

base:
'os:Fedora':
- match: grain
- webserver

Create an sls file
In the same directory as the top file, create a file named webserver.sls, containing the
following:

apache: # ID declaration
pkg: # state declaration
- installed # function declaration

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 package name for the Apache httpd web server may differ depending on OS or distro —
for example, on Fedora it is httpd but on Debian/Ubuntu it is apache2.

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.

Renderers

States sls files can be written in many formats. Salt requires only a simple
data structure and is not concerned with how that data structure is built.
Templating languages and DSLs are a dime-a-dozen and everyone has a favorite.

Building the expected data structure is the job of Salt renderers and they are
dead-simple to write.

In this tutorial we will be using YAML in Jinja2 templates, which is the default
format. The default can be changed by editing renderer in the master
configuration file.

Install the package
Next, let's run the state we created. Open a terminal on the master and run:

salt '*' state.apply

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:
This action is referred to as a "highstate", and can be run using the state.highstate
function. However, to make the usage easier to understand ("highstate" is not
necessarily an intuitive name), a state.apply function was added in version 2015.5.0,
which when invoked without any SLS names will trigger a highstate. state.highstate
still exists and can be used, but the documentation (as can be seen above) has been
updated to reference state.apply, so keep the following in mind as you read the
documentation:

• state.apply invoked without any SLS names will run state.highstate

• state.apply invoked with SLS names will run state.sls

Once completed, the minion will report back with a summary of all actions taken and all
changes made.

WARNING:
If you have created custom grain modules, they will not be available in the top file
until after the first highstate. To make custom grains available on a minion's first
highstate, it is recommended to use this example to ensure that the custom grains are
synced when the minion starts.

SLS File Namespace

Note that in the example above, the SLS file webserver.sls was referred to
simply as webserver. The namespace for SLS files when referenced in top.sls or
an include-declaration follows a few simple rules:

1. The .sls is discarded (i.e. webserver.sls becomes webserver).

Subdirectories can be used for better organization.

a. Each subdirectory is represented with a dot (following the Python import
model) in Salt states and on the command line . webserver/dev.sls on the
filesystem is referred to as webserver.dev in Salt

b. Because slashes are represented as dots, SLS files can not contain dots in
the name (other than the dot for the SLS suffix). The SLS file
webserver_1.0.sls can not be matched, and webserver_1.0 would match the
directory/file webserver_1/0.sls

3. A file called init.sls in a subdirectory is referred to by the path of the
directory. So, webserver/init.sls is referred to as webserver.

4. If both webserver.sls and webserver/init.sls happen to exist, webserver/init.sls
will be ignored and webserver.sls will be the file referred to as webserver.

Troubleshooting Salt

If the expected output isn't seen, the following tips can help to narrow down
the problem.

Turn up logging
Salt can be quite chatty when you change the logging setting to debug:

salt-minion -l debug

Run the minion in the foreground
By not starting the minion in daemon mode (-d) one can view any output from the
minion as it works:

salt-minion

Increase the default timeout value when running salt. For example, to change the
default timeout to 60 seconds:

salt -t 60

For best results, combine all three:

salt-minion -l debug # On the minion
salt '*' state.apply -t 60 # On the master

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:
This tutorial builds on topics covered in part 1. It is recommended that you begin
there.

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:

apache:
pkg.installed: []
service.running:
- require:
- pkg: apache

Try stopping Apache before running state.apply once again and observe the output.

NOTE:
For those running RedhatOS derivatives (Centos, AWS), you will want to specify the
service name to be httpd. More on state service here, service state. With the example
above, just add "- name: httpd" above the require line and with the same spacing.

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:

apache:
pkg.installed: []
service.running:
- require:
- pkg: apache

/var/www/index.html: # ID declaration
file: # state declaration
- managed # function
- source: salt://webserver/index.html # function arg
- require: # requisite declaration
- pkg: apache # requisite reference

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:

<!DOCTYPE html>
<html>
<head><title>Salt rocks</title></head>
<body>
<h1>This file brought to you by Salt</h1>
</body>
</html>

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:

salt '*' state.apply

Verify that Apache is now serving your custom HTML.

require vs. watch

There are two requisite-declaration, “require”, and “watch”. Not every state
supports “watch”. The service state does support “watch” and will restart a
service based on the watch condition.

For example, if you use Salt to install an Apache virtual host configuration
file and want to restart Apache whenever that file is changed you could modify
our Apache example from earlier as follows:

/etc/httpd/extra/httpd-vhosts.conf:
file.managed:
- source: salt://webserver/httpd-vhosts.conf

apache:
pkg.installed: []
service.running:
- watch:
- file: /etc/httpd/extra/httpd-vhosts.conf
- require:
- pkg: apache

If the pkg and service names differ on your OS or distro of choice you can specify each
one separately using a name-declaration which explained in Part 3.

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 tutorial builds on topics covered in part 1 and part 2. It is recommended that you
begin there.

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:

{% for usr in ['moe','larry','curly'] %}
{{ usr }}:
user.present
{% endfor %}

This templated sls file once generated will look like this:

moe:
user.present
larry:
user.present
curly:
user.present

Here's a more complex example:

# Comments in yaml start with a hash symbol.
# Since jinja rendering occurs before yaml parsing, if you want to include jinja
# in the comments you may need to escape them using 'jinja' comments to prevent
# jinja from trying to render something which is not well-defined jinja.
# e.g.
# {# iterate over the Three Stooges using a {% for %}..{% endfor %} loop
# with the iterator variable {{ usr }} becoming the state ID. #}
{% for usr in 'moe','larry','curly' %}
{{ usr }}:
group:
- present
user:
- present
- gid_from_name: True
- require:
- group: {{ usr }}
{% endfor %}

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:

apache:
pkg.installed:
{% if grains['os'] == 'RedHat' %}
- name: httpd
{% elif grains['os'] == 'Ubuntu' %}
- name: apache2
{% endif %}

Using Environment Variables in SLS modules
You can use salt['environ.get']('VARNAME') to use an environment variable in a Salt state.

MYENVVAR="world" salt-call state.template test.sls

Create a file with contents from an environment variable:
file.managed:
- name: /tmp/hello
- contents: {{ salt['environ.get']('MYENVVAR') }}

Error checking:

{% set myenvvar = salt['environ.get']('MYENVVAR') %}
{% if myenvvar %}

Create a file with contents from an environment variable:
file.managed:
- name: /tmp/hello
- contents: {{ salt['environ.get']('MYENVVAR') }}

{% else %}

Fail - no environment passed in:
test.fail_without_changes

{% endif %}

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.

moe:
user.present:
- gid: {{ salt['file.group_to_gid']('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:

import salt.modules.file
file.group_to_gid('some_group_that_exists')

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:

salt['network.hw_addr']('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-dateutil:
pkg.installed

python/django.sls:

include:
- python.python-libs

django:
pkg.installed:
- require:
- pkg: python-dateutil

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

apache/mywebsite.sls:

include:
- apache.apache

extend:
apache:
service:
- running
- watch:
- file: /etc/httpd/extra/httpd-vhosts.conf

/etc/httpd/extra/httpd-vhosts.conf:
file.managed:
- source: salt://apache/httpd-vhosts.conf

Using extend with require or watch

The extend statement works differently for require or watch. It appends to,
rather than replacing the requisite component.

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:

include:
- apache.apache

extend:
apache:
service:
- running
- watch:
- file: mywebsite

mywebsite:
file.managed:
- name: /etc/httpd/extra/httpd-vhosts.conf
- source: salt://apache/httpd-vhosts.conf

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:

stooges:
user.present:
- names:
- moe
- larry
- curly

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 tutorial builds on topics covered in part 1, part 2, and part 3. It is
recommended that you begin there.

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:

# In the master config file (/etc/salt/master)
file_roots:
base:
- /srv/salt
- /mnt/salt-nfs/base

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:
When using multiple fileserver backends, the order in which they are listed in the
fileserver_backend parameter also matters. If both roots and git backends contain a
file with the same relative path, and roots appears before git in the
fileserver_backend list, then the file in roots will "win", and the file in gitfs will
be ignored.

A more thorough explanation of how Salt's modular fileserver works can be found here.
We recommend reading this.

Environment configuration
Configure a multiple-environment setup like so:

file_roots:
base:
- /srv/salt/prod
qa:
- /srv/salt/qa
- /srv/salt/prod
dev:
- /srv/salt/dev
- /srv/salt/qa
- /srv/salt/prod

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:

base:
'web*prod*':
- webserver.foobarcom
qa:
'web*qa*':
- webserver.foobarcom
dev:
'web*dev*':
- webserver.foobarcom

Using pillar, roles can be assigned to the hosts:

/srv/pillar/top.sls:

base:
'web*prod*':
- webserver.prod
'web*qa*':
- webserver.qa
'web*dev*':
- webserver.dev

/srv/pillar/webserver/prod.sls:

webserver_role: prod

/srv/pillar/webserver/qa.sls:

webserver_role: qa

/srv/pillar/webserver/dev.sls:

webserver_role: dev

And finally, the SLS to deploy the website:

/srv/salt/prod/webserver/foobarcom.sls:

{% if pillar.get('webserver_role', '') %}
/var/www/foobarcom:
file.recurse:
- source: salt://webserver/src/foobarcom
- env: {{ pillar['webserver_role'] }}
- user: www
- group: www
- dir_mode: 755
- file_mode: 644
{% endif %}

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:

salt --pillar 'webserver_role:dev' 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:

salt --pillar 'webserver_role:dev' state.apply webserver.foobarcom

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:

salt --pillar 'webserver_role:qa' state.apply webserver.foobarcom

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:

salt --pillar 'webserver_role:prod' state.apply webserver.foobarcom

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:
Since this option changes the basic behavior of the state runtime, after it is enabled
states should be executed using test=True to ensure that the desired behavior is
preserved.

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:

state_aggregate: True

Enable for only specific state modules:

state_aggregate:
- pkg

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.

lamp_stack:
pkg.installed:
- pkgs:
- php
- mysql-client
- aggregate: True

memcached:
pkg.installed:
- name: memcached

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:

def mod_aggregate(low, chunks, running):
'''
The mod_aggregate function which looks up all packages in the available
low chunks and merges them into a single pkgs ref in the present low data
'''
pkgs = []
# What functions should we aggregate?
agg_enabled = [
'installed',
'latest',
'removed',
'purged',
]
# The `low` data is just a dict with the state, function (fun) and
# arguments passed in from the sls
if low.get('fun') not in agg_enabled:
return low
# Now look into what other things are set to execute
for chunk in chunks:
# The state runtime uses "tags" to track completed jobs, it may
# look familiar with the _|-
tag = salt.utils.gen_state_tag(chunk)
if tag in running:
# Already ran the pkg state, skip aggregation
continue
if chunk.get('state') == 'pkg':
if '__agg__' in chunk:
continue
# Check for the same function
if chunk.get('fun') != low.get('fun'):
continue
# Pull out the pkg names!
if 'pkgs' in chunk:
pkgs.extend(chunk['pkgs'])
chunk['__agg__'] = True
elif 'name' in chunk:
pkgs.append(chunk['name'])
chunk['__agg__'] = True
if pkgs:
if 'pkgs' in low:
low['pkgs'].extend(pkgs)
else:
low['pkgs'] = pkgs
# The low has been modified and needs to be returned to the state
# runtime for execution
return low

Altering States
NOTE:
This documentation has been moved here.

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:

backup_mode: minion

Or it can be set for each file:

/etc/ssh/sshd_config:
file.managed:
- source: salt://ssh/sshd_config
- backup: minion

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:

# salt foo.bar.com file.list_backups /tmp/foo.txt
foo.bar.com:
----------
0:
----------
Backup Time:
Sat Jul 27 2013 17:48:41.738027
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:41_738027_2013
Size:
13
1:
----------
Backup Time:
Sat Jul 27 2013 17:48:28.369804
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013
Size:
35

Restoring
Restoring is easy using file.restore_backup, just pass the path and the numeric id found
with file.list_backups:

# salt foo.bar.com file.restore_backup /tmp/foo.txt 1
foo.bar.com:
----------
comment:
Successfully restored /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013 to /tmp/foo.txt
result:
True

The existing file will be backed up, just in case, as can be seen if file.list_backups is
run again:

# salt foo.bar.com file.list_backups /tmp/foo.txt
foo.bar.com:
----------
0:
----------
Backup Time:
Sat Jul 27 2013 18:00:19.822550
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_18:00:19_822550_2013
Size:
53
1:
----------
Backup Time:
Sat Jul 27 2013 17:48:41.738027
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:41_738027_2013
Size:
13
2:
----------
Backup Time:
Sat Jul 27 2013 17:48:28.369804
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013
Size:
35

NOTE:
Since no state is being run, restoring a file will not trigger any watches for the
file. So, if you are restoring a config file for a service, it will likely still be
necessary to run a service.restart.

Deleting
Deleting backups can be done using file.delete_backup:

# salt foo.bar.com file.delete_backup /tmp/foo.txt 0
foo.bar.com:
----------
comment:
Successfully removed /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_18:00:19_822550_2013
result:
True

Understanding State Compiler Ordering
NOTE:
This tutorial is an intermediate level tutorial. Some basic understanding of the state
system and writing Salt Formulas is assumed.

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:

salt '*' state.show_highstate

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:

salt '*' state.show_lowstate

NOTE:
The state execution module contains MANY functions for evaluating the state system and
is well worth a read! These routines can be very useful when debugging states or to
help deepen one's understanding of Salt's state system.

As an example, a state written thusly:

apache:
pkg.installed:
- name: httpd
service.running:
- name: httpd
- watch:
- file: apache_conf
- pkg: apache

apache_conf:
file.managed:
- name: /etc/httpd/conf.d/httpd.conf
- source: salt://apache/httpd.conf

Will have High Data which looks like this represented in json:

{
"apache": {
"pkg": [
{
"name": "httpd"
},
"installed",
{
"order": 10000
}
],
"service": [
{
"name": "httpd"
},
{
"watch": [
{
"file": "apache_conf"
},
{
"pkg": "apache"
}
]
},
"running",
{
"order": 10001
}
],
"__sls__": "blah",
"__env__": "base"
},
"apache_conf": {
"file": [
{
"name": "/etc/httpd/conf.d/httpd.conf"
},
{
"source": "salt://apache/httpd.conf"
},
"managed",
{
"order": 10002
}
],
"__sls__": "blah",
"__env__": "base"
}
}

The subsequent Low Data will look like this:

[
{
"name": "httpd",
"state": "pkg",
"__id__": "apache",
"fun": "installed",
"__env__": "base",
"__sls__": "blah",
"order": 10000
},
{
"name": "httpd",
"watch": [
{
"file": "apache_conf"
},
{
"pkg": "apache"
}
],
"state": "service",
"__id__": "apache",
"fun": "running",
"__env__": "base",
"__sls__": "blah",
"order": 10001
},
{
"name": "/etc/httpd/conf.d/httpd.conf",
"source": "salt://apache/httpd.conf",
"state": "file",
"__id__": "apache_conf",
"fun": "managed",
"__env__": "base",
"__sls__": "blah",
"order": 10002
}
]

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 Definition Order system can be disabled by turning the option state_auto_order to
False in the master configuration file.

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

include:
- bar
- baz

bar.sls

include:
- quo

baz.sls

include:
- qux

In the above case if state.apply foo were called then the formulas will be loaded in the
following order:

1. quo

2. bar

3. qux

4. baz

5. foo

The order Flag
The Definition Order happens transparently in the background, but the ordering can be
explicitly overridden using the order flag in states:

apache:
pkg.installed:
- name: httpd
- order: 1

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:
If running with state_auto_order: False the order key is not set automatically, since
the Lexicographical order can be derived from other keys.

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:
If using requisite in statements like require_in and watch_in these will be compiled
down to require and watch statements before runtime evaluation.

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:

1. The pkg.installed is executed ensuring that the apache package is installed, it
contains no requisites and is therefore the first defined state to execute.

2. The service.running state is evaluated but NOT executed, a watch requisite is found,
therefore they are read in order, the runtime first checks for the file, sees that it
has not been executed and calls for the file state to be evaluated.

3. The file state is evaluated AND executed, since it, like the pkg state does not contain
any requisites.

4. The evaluation of the service state continues, it next checks the pkg requisite and
sees that it is met, with all requisites met the service state is now executed.

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:

include:
- http
- ssh

extend:
apache:
file:
- name: /etc/httpd/conf/httpd.conf
- source: salt://http/httpd2.conf
ssh-server:
service:
- watch:
- file: /etc/ssh/banner

/etc/ssh/banner:
file.managed:
- source: salt://ssh/banner

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 it is used twice then only
one of the extend blocks will be read. So this is WRONG:

include:
- http
- ssh

extend:
apache:
file:
- name: /etc/httpd/conf/httpd.conf
- source: salt://http/httpd2.conf
# Second extend will overwrite the first!! Only make one
extend:
ssh-server:
service:
- watch:
- file: /etc/ssh/banner

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:

include:
- ssh

/etc/ssh/banner:
file.managed:
- source: salt://ssh/banner
- watch_in:
- service: ssh-server

Rules to Extend By
There are a few rules to remember when extending states:

1. Always include the SLS being extended with an include declaration

2. Requisites (watch and require) are appended to, everything else is overwritten

3. extend is a top level declaration, like an ID declaration, cannot be declared twice in
a single SLS

4. Many IDs can be extended under the extend declaration

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:

/etc/yum.repos.d/company.repo:
file.managed:
- source: salt://company/yumrepo.conf
- user: root
- group: root
- mode: 644
- order: 1
- failhard: True

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:
This documentation has been moved here.

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:
Directory names or filenames in the state tree cannot contain a period, with the
exception of the period in the .sls file suffix.

Top file
The main state file that instructs minions what environment and modules to use during
state execution.

Configurable via state_top.

SEE ALSO:
A detailed description of the top file

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:

include:
- edit.vim
- http.server

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

In Salt versions earlier than 0.9.7, ID declarations containing dots would result in
unpredictable output.

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.

include:
- apache

extend:
apache:
service:
- watch:
- file: mywebsite

mywebsite:
file.managed:
- name: /var/www/mysite

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

          # -*- coding: utf-8 -*-
          '''
          My utils module
          ---------------

          This module contains common functions for use in my other custom types.
          '''

          def bar():
              return 'baz'

       Once  synced to a minion, this function would be available to other custom Salt types like
       so:

          # -*- coding: utf-8 -*-
          '''
          My awesome execution module
          ---------------------------
          '''

          def observe_the_awesomeness():
              '''
              Prints information from my utility module

              CLI Example:

              .. code-block:: bash

                  salt '*' mymodule.observe_the_awesomeness
              '''
              return __utils__['foo.bar']()

       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.

          # -*- coding: utf-8 -*-
          '''
          My utils module
          ---------------

          This module contains common functions for use in my other custom types.
          '''

          def __virtual__():
              '''
              Load as a different name
              '''
              return 'foo'

          def bar():
              return 'baz'

       Also you could even write your utility modules in object oriented fashion:

          # -*- coding: utf-8 -*-
          '''
          My OOP-style utils module
          -------------------------

          This module contains common functions for use in my other custom types.
          '''

          class Foo(object):

              def __init__(self):
                  pass

              def bar(self):
                  return 'baz'

       And import them into other custom modules:

          # -*- coding: utf-8 -*-
          '''
          My awesome execution module
          ---------------------------
          '''

          import mymodule

          def observe_the_awesomeness():
              '''
              Prints information from my utility module

              CLI Example:

              .. code-block:: bash

                  salt '*' mymodule.observe_the_awesomeness
              '''
              foo = mymodule.Foo()
              return foo.bar()

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

       • state.apply

       • saltutil.sync_utils

       • saltutil.sync_all

       To sync to the Master, use either of the following:

       • saltutil.sync_utils

       • saltutil.sync_all

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:

• The event sockets which publishes events.

• The event library which can listen to events and send events into the salt system.

Event types
Salt Master Events
These events are fired on the Salt Master event bus. This list is not comprehensive.

Authentication events
salt/auth
Fired when a minion performs an authentication check with the master.

Variables

• id -- The minion ID.

• act -- The current status of the minion key: accept, pend, reject.

• pub -- The minion public key.

NOTE:
Minions fire auth events on fairly regular basis for a number of reasons.
Writing reactors to respond to events through the auth cycle can lead to
infinite reactor event loops (minion tries to auth, reactor responds by doing
something that generates another auth event, minion sends auth event, etc.).
Consider reacting to salt/key or salt/minion/<MID>/start or firing a custom
event tag instead.

Start events
salt/minion/<MID>/start
Fired every time a minion connects to the Salt master.

Variables
id -- The minion ID.

Key events
salt/key
Fired when accepting and rejecting minions keys on the Salt master. These happen
as a result of actions undertaken by the salt-key command.

Variables

• id -- The minion ID.

• act -- The new status of the minion key: accept, delete,

WARNING:
If a master is in auto_accept mode, salt/key events will not be fired when the keys are
accepted. In addition, pre-seeding keys (like happens through Salt-Cloud) will not
cause firing of these events.

Job events
salt/job/<JID>/new
Fired as a new job is sent out to minions.

Variables

• jid -- The job ID.

• tgt -- The target of the job: *, a minion ID, G@os_family:RedHat, etc.

• tgt_type -- The type of targeting used: glob, grain, compound, etc.

• fun -- The function to run on minions: test.ping, network.interfaces, etc.

• arg -- A list of arguments to pass to the function that will be called.

• minions -- A list of minion IDs that Salt expects will return data for
this job.

• user -- The name of the user that ran the command as defined in Salt's
Publisher ACL or external auth.

salt/job/<JID>/ret/<MID>
Fired each time a minion returns data for a job.

Variables

• id -- The minion ID.

• jid -- The job ID.

• retcode -- The return code for the job.

• fun -- The function the minion ran. E.g., test.ping.

• return -- The data returned from the execution module.

salt/job/<JID>/prog/<MID>/<RUN NUM>
Fired each time a each function in a state run completes execution. Must be enabled
using the state_events option.

Variables

• data -- The data returned from the state module function.

• id -- The minion ID.

• jid -- The job ID.

Runner Events
salt/run/<JID>/new
Fired as a runner begins execution

Variables

• jid -- The job ID.

• fun -- The name of the runner function, with runner. prepended to it (e.g.
runner.jobs.lookup_jid)

• fun_args -- The arguments passed to the runner function (e.g.
['20160829225914848058'])

• user -- The user who executed the runner (e.g. root)

salt/run/<JID>/ret
Fired when a runner function returns

Variables

• jid -- The job ID.

• fun -- The name of the runner function, with runner. prepended to it (e.g.
runner.jobs.lookup_jid)

• fun_args -- The arguments passed to the runner function (e.g.
['20160829225914848058'])

• return -- The data returned by the runner function

salt/run/<JID>/args
New in version 2016.11.0.

Fired by the state.orchestrate runner

Variables

• name -- The ID declaration for the orchestration job (i.e. the line above
salt.state, salt.function, salt.runner, etc.)

• type -- The type of orchestration job being run (e.g. state)

• tgt -- The target expression (e.g. *). Included for state and function
types only.

• args -- The args passed to the orchestration job. Note: for state and
function types, also includes a tgt_type value which shows what kind of
match (glob, pcre, etc.) was used. This value was named expr_form in the
2016.11 release cycle but has been renamed to tgt_type in 2017.7.0 for
consistency with other events.

Presence Events
salt/presence/present
Events fired on a regular interval about currently connected, newly connected, or
recently disconnected minions. Requires the presence_events setting to be enabled.

Variables
present -- A list of minions that are currently connected to the Salt
master.

salt/presence/change
Fired when the Presence system detects new minions connect or disconnect.

Variables

• new -- A list of minions that have connected since the last presence
event.

• lost -- A list of minions that have disconnected since the last presence
event.

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.

salt/cloud/<VM NAME>/creating
Fired when salt-cloud starts the VM creation process.

Variables

• name -- the name of the VM being created.

• event -- description of the event.

• provider -- the cloud provider of the VM being created.

• profile -- the cloud profile for the VM being created.

salt/cloud/<VM NAME>/deploying
Fired when the VM is available and salt-cloud begins deploying Salt to the new VM.

Variables

• name -- the name of the VM being created.

• event -- description of the event.

• kwargs -- options available as the deploy script is invoked: conf_file,
deploy_command, display_ssh_output, host, keep_tmp, key_filename,
make_minion, minion_conf, name, parallel, preseed_minion_keys, script,
script_args, script_env, sock_dir, start_action, sudo, tmp_dir, tty,
username

salt/cloud/<VM NAME>/requesting
Fired when salt-cloud sends the request to create a new VM.

Variables

• event -- description of the event.

• location -- the location of the VM being requested.

• kwargs -- options available as the VM is being requested: Action, ImageId,
InstanceType, KeyName, MaxCount, MinCount, SecurityGroup.1

salt/cloud/<VM NAME>/querying
Fired when salt-cloud queries data for a new instance.

Variables

• event -- description of the event.

• instance_id -- the ID of the new VM.

salt/cloud/<VM NAME>/tagging
Fired when salt-cloud tags a new instance.

Variables

• event -- description of the event.

• tags -- tags being set on the new instance.

salt/cloud/<VM NAME>/waiting_for_ssh
Fired while the salt-cloud deploy process is waiting for ssh to become available on
the new instance.

Variables

• event -- description of the event.

• ip_address -- IP address of the new instance.

salt/cloud/<VM NAME>/deploy_script
Fired once the deploy script is finished.

Variables
event -- description of the event.

salt/cloud/<VM NAME>/created
Fired once the new instance has been fully created.

Variables

• name -- the name of the VM being created.

• event -- description of the event.

• instance_id -- the ID of the new instance.

• provider -- the cloud provider of the VM being created.

• profile -- the cloud profile for the VM being created.

salt/cloud/<VM NAME>/destroying
Fired when salt-cloud requests the destruction of an instance.

Variables

• name -- the name of the VM being created.

• event -- description of the event.

• instance_id -- the ID of the new instance.

salt/cloud/<VM NAME>/destroyed
Fired when an instance has been destroyed.

Variables

• name -- the name of the VM being created.

• event -- description of the event.

• instance_id -- the ID of the new instance.

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:

salt-run state.event pretty=True

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.

curl -SsNk https://salt-api.example.com:8000/events?token=05A3

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:

import salt.config
import salt.utils.event

opts = salt.config.client_config('/etc/salt/master')

event = salt.utils.event.get_event(
'master',
sock_dir=opts['sock_dir'],
transport=opts['transport'],
opts=opts)

data = event.get_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.

data = event.get_event(wait=10, tag='salt/auth')

To retrieve the tag as well as the event data, pass full=True:

evdata = event.get_event(wait=10, tag='salt/job', full=True)

tag, data = evdata['tag'], evdata['data']

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:

for data in event.iter_events(tag='salt/auth'):
print(data)

And finally event tags can be globbed, such as they can be in the Reactor, using the
fnmatch library.

import fnmatch

import salt.config
import salt.utils.event

opts = salt.config.client_config('/etc/salt/master')

sevent = salt.utils.event.get_event(
'master',
sock_dir=opts['sock_dir'],
transport=opts['transport'],
opts=opts)

while True:
ret = sevent.get_event(full=True)
if ret is None:
continue

if fnmatch.fnmatch(ret['tag'], 'salt/job/*/ret/*'):
do_something_with_job_return(ret['data'])

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:

salt-call event.fire '{"data": "message to be sent in the event"}' 'tag'

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:

salt-call event.send 'myco/mytag/success' '{success: True, message: "It works!"}'

If a process is listening on the minion, it may be useful for a user on the master to fire
an event to it:

# Job on minion
import salt.utils.event

event = salt.utils.event.MinionEvent(**__opts__)

for evdata in event.iter_events(tag='customtag/'):
return evdata # do your processing here...

salt minionname event.fire '{"data": "message for the minion"}' 'customtag/african/unladen'

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:

# /srv/salt/_modules/my_custom_module.py

def do_something():
'''
Do something and fire an event to the master when finished

CLI Example::

salt '*' my_custom_module:do_something
'''
# do something!
__salt__['event.send']('myco/my_custom_module/finished', {
'finished': True,
'message': "The something is finished!",
})

From Custom Python Scripts
Firing events from custom Python code is quite simple and mirrors how it is done at the
CLI:

import salt.client

caller = salt.client.Caller()

caller.sminion.functions['event.send'](
'myco/myevent/success',
{
'success': True,
'message': "It works!",
}
)

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:

• file system changes

• system load

• service status

• shell activity, such as user login

• network and disk usage

See beacon modules for a current list.

NOTE:
Salt beacons are an event generation mechanism. Beacons leverage the Salt reactor
system to make changes when beacon events occur.

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:

beacons:
inotify:
/etc/important_file: {}
/opt: {}

The beacon system, like many others in Salt, can also be configured via the minion pillar,
grains, or local config file.

NOTE:
The inotify beacon only works on OSes that have inotify kernel support. Currently this
excludes FreeBSD, macOS, and Windows.

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:

beacons:
inotify:
/etc/important_file: {}
/opt: {}
interval: 5
disable_during_state_run: True
load:
1m:
- 0.0
- 2.0
5m:
- 0.0
- 1.5
15m:
- 0.1
- 1.0
interval: 10

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.

beacons:
inotify:
/etc/important_file: {}
disable_during_state_run: True

NOTE:
For beacon writers: If you need extra stuff to happen, like closing file handles for
the disable_during_state_run to actually work, you can add a close() function to the
beacon to run those extra things. See the inotify beacon.

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:
The inotify beacon requires Pyinotify on the minion, install it using salt myminion
pkg.install python-inotify.

Create Watched File
Create the file named /etc/important_file and add some simple content:

important_config: True

Add Beacon Configs to Minion
On the Salt minion, add the following configuration to /etc/salt/minion.d/beacons.conf:

beacons:
inotify:
/etc/important_file:
mask:
- modify
disable_during_state_run: True

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:
The disable_during_state_run: True parameter prevents the inotify beacon from
generating reactor events due to salt itself modifying the file.

View Events on the Master
On your Salt master, start the event runner using the following command:

salt-run state.event pretty=true

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:

salt/beacon/larry/inotify//etc/important_file {
"_stamp": "2015-09-09T15:59:37.972753",
"data": {
"change": "IN_IGNORED",
"id": "larry",
"path": "/etc/important_file"
},
"tag": "salt/beacon/larry/inotify//etc/important_file"
}

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:
If the /srv/reactor directory doesn't exist, create it.

mkdir -p /srv/reactor

Add the following to /srv/reactor/revert.sls:

revert-file:
local.state.apply:
- tgt: {{ data['data']['id'] }}
- arg:
- maintain_important_file

NOTE:
In addition to setting disable_during_state_run: True for an inotify beacon whose
reaction is to modify the watched file, it is important to ensure the state applied is
also idempotent.

NOTE:
The expression {{ data['data']['id'] }} is correct as it matches the event structure
shown above.

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.

important_file:
file.managed:
- name: /etc/important_file
- contents: |
important_config: True

Master Config
Configure the master to map the inotify beacon event to the revert reaction in
/etc/salt/master.d/reactor.conf:

reactor:
- salt/beacon/*/inotify//etc/important_file:
- /srv/reactor/revert.sls

NOTE:
You can have only one top level reactor section, so if one already exists, add this
code to the existing section. See here to learn more about reactor SLS syntax.

Start the Salt Master in Debug Mode
To help with troubleshooting, start the Salt master in debug mode:

service salt-master stop
salt-master -l debug

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:

[{'changes': ['/foo/bar'], 'tag': 'foo'},
{'changes': ['/foo/baz'], 'tag': 'bar'}]

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

reactor: # Master config section "reactor"

- 'salt/minion/*/start': # Match tag "salt/minion/*/start"
- /srv/reactor/start.sls # Things to do when a minion starts
- /srv/reactor/monitor.sls # Other things to do

- 'salt/cloud/*/destroyed': # Globs can be used to match tags
- /srv/reactor/destroy/*.sls # Globs can be used to match file names

- 'myco/custom/event/tag': # React to custom event tags
- salt://reactor/mycustom.sls # Reactor files can come from the salt fileserver

NOTE:
In the above example, salt://reactor/mycustom.sls refers to the base environment. To
pull this file from a different environment, use the querystring syntax (e.g.
salt://reactor/mycustom.sls?saltenv=reactor).

Reactor SLS files are similar to State and Pillar SLS files. They are by default YAML +
Jinja templates and are passed familiar context variables. Click here for more detailed
information on the variables availble in Jinja templating.

Here is the SLS for a simple reaction:

{% if data['id'] == 'mysql1' %}
highstate_run:
local.state.apply:
- tgt: mysql1
{% endif %}

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, which performs a highstate. Similarly, a
runner can be called:

{% if data['data']['custom_var'] == 'runit' %}
call_runit_orch:
runner.state.orchestrate:
- args:
- mods: orchestrate.runit
{% endif %}

This example will execute the state.orchestrate runner and intiate an execution of the
runit orchestrator located at /srv/salt/orchestrate/runit.sls.

Types of Reactions
┌───────┬──────────────────────────────────┐
│Name │ Description │
├───────┼──────────────────────────────────┤
│local │ Runs a remote-execution function │
│ │ on targeted minions │
├───────┼──────────────────────────────────┤
│runner │ Executes a runner function │
├───────┼──────────────────────────────────┤
│wheel │ Executes a wheel function on the │
│ │ master │
├───────┼──────────────────────────────────┤
│caller │ Runs a remote-execution function │
│ │ on a masterless minion │
└───────┴──────────────────────────────────┘

NOTE:
The local and caller reaction types will be renamed for the Oxygen release. These
reaction types were named after Salt's internal client interfaces, and are not
intuitively named. Both local and caller will continue to work in Reactor SLS files,
but for the Oxygen release the documentation will be updated to reflect the new
preferred naming.

Where to Put Reactor SLS Files
Reactor SLS files can come both from files local to the master, and from any of backends
enabled via the fileserver_backend config option. Files placed in the Salt fileserver can
be referenced using a salt:// URL, just like they can in State SLS files.

It is recommended to place reactor and orchestrator SLS files in their own uniquely-named
subdirectories such as orch/, orchestrate/, react/, reactor/, etc., to keep them
organized.

Writing Reactor SLS
The different reaction types were developed separately and have historically had different
methods for passing arguments. For the 2017.7.2 release a new, unified configuration
schema has been introduced, which applies to all reaction types.

The old config schema will continue to be supported, and there is no plan to deprecate it
at this time.

Local Reactions
A local reaction runs a remote-execution function on the targeted minions.

The old config schema required the positional and keyword arguments to be manually
separated by the user under arg and kwarg parameters. However, this is not very
user-friendly, as it forces the user to distinguish which type of argument is which, and
make sure that positional arguments are ordered properly. Therefore, the new config schema
is recommended if the master is running a supported release.

The below two examples are equivalent:

┌─────────────────────────────────────┬─────────────────────────────────────┐
│Supported in 2017.7.2 and later │ Supported in all releases │
├─────────────────────────────────────┼─────────────────────────────────────┤
│ │ │
│ install_zsh: │ install_zsh: │
│ local.state.single: │ local.state.single: │
│ - tgt: 'kernel:Linux' │ - tgt: 'kernel:Linux' │
│ - tgt_type: grain │ - tgt_type: grain │
│ - args: │ - arg: │
│ - fun: pkg.installed │ - pkg.installed │
│ - name: zsh │ - zsh │
│ - fromrepo: updates │ - kwarg: │
│ │ fromrepo: updates │
└─────────────────────────────────────┴─────────────────────────────────────┘

This reaction would be equvalent to running the following Salt command:

salt -G 'kernel:Linux' state.single pkg.installed name=zsh fromrepo=updates

NOTE:
Any other parameters in the LocalClient().cmd_async() method can be passed at the same
indentation level as tgt.

NOTE:
tgt_type is only required when the target expression defined in tgt uses a target type
other than a minion ID glob.

The tgt_type argument was named expr_form in releases prior to 2017.7.0.

Runner Reactions
Runner reactions execute runner functions locally on the master.

The old config schema called for passing arguments to the reaction directly under the name
of the runner function. However, this can cause unpredictable interactions with the
Reactor system's internal arguments. It is also possible to pass positional and keyword
arguments under arg and kwarg like above in local reactions, but as noted above this is
not very user-friendly. Therefore, the new config schema is recommended if the master is
running a supported release.

The below two examples are equivalent:

┌────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┐
├────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
└────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────┘

Assuming that the event tag is foo, and the data passed to the event is {'bar': 'baz'},
then this reaction is equvalent to running the following Salt command:

salt-run state.orchestrate mods=orchestrate.deploy_app pillar='{"event_tag": "foo", "event_data": {"bar": "baz"}}'

Wheel Reactions
Wheel reactions run wheel functions locally on the master.

Like runner reactions, the old config schema called for wheel reactions to have arguments
passed directly under the name of the wheel function (or in arg or kwarg parameters).

The below two examples are equivalent:

┌──────────────────────────────────────────┬─────────────────────────────────────────┐
│Supported in 2017.7.2 and later │ Supported in all releases │
├──────────────────────────────────────────┼─────────────────────────────────────────┤
│ │ │
│ remove_key: │ remove_key: │
│ wheel.key.delete: │ wheel.key.delete: │
│ - args: │ - match: {{ data['id'] }} │
│ - match: {{ data['id'] }} │ │
└──────────────────────────────────────────┴─────────────────────────────────────────┘

Caller Reactions
Caller reactions run remote-execution functions on a minion daemon's Reactor system. To
run a Reactor on the minion, it is necessary to configure the Reactor Engine in the minion
config file, and then setup your watched events in a reactor section in the minion config
file as well.

NOTE:
Masterless Minions use this Reactor

This is the only way to run the Reactor if you use masterless minions.

Both the old and new config schemas involve passing arguments under an args parameter.
However, the old config schema only supports positional arguments. Therefore, the new
config schema is recommended if the masterless minion is running a supported release.

The below two examples are equivalent:

┌─────────────────────────────────┬────────────────────────────────┐
│Supported in 2017.7.2 and later │ Supported in all releases │
├─────────────────────────────────┼────────────────────────────────┤
│ │ │
│ touch_file: │ touch_file: │
│ caller.file.touch: │ caller.file.touch: │
│ - args: │ - args: │
│ - name: /tmp/foo │ - /tmp/foo │
└─────────────────────────────────┴────────────────────────────────┘

This reaction is equvalent to running the following Salt command:

salt-call file.touch name=/tmp/foo

Best Practices for Writing Reactor SLS Files
The Reactor works as follows:

1. The Salt Reactor watches Salt's event bus for new events.

2. Each event's tag is matched against the list of event tags configured under the reactor
section in the Salt Master config.

3. The SLS files for any matches are rendered into a data structure that represents one or
more function calls.

4. That data structure is given to a pool of worker threads for execution.

Matching and rendering Reactor SLS files is done sequentially in a single process. For
that reason, reactor SLS files should contain few individual reactions (one, if at all
possible). Also, keep in mind that reactions are fired asynchronously (with the exception
of caller) and do not support requisites.

Complex Jinja templating that calls out to slow remote-execution or runner functions 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 like orchestration
jobs.

Therefore, when complex tasks are in order, orchestration is a natural fit. Orchestration
SLS files can be more complex, and use requisites. Performing a complex task using
orchestration lets the Reactor system fire off the orchestration job and proceed with
processing other reactions.

Jinja Context
Reactor SLS files only have access to a minimal Jinja context. grains and pillar are not
available. The salt object is available for calling remote-execution or runner functions,
but it should be used sparingly and only for quick tasks for the reasons mentioned above.

In addition to the salt object, the following variables are available in the Jinja
context:

• tag - the tag from the event that triggered execution of the Reactor SLS file

• data - the event's data dictionary

The data dict will contain an id key containing the minion ID, if the event was fired from
a minion, and a data key containing the data passed to the event.

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:

# /etc/salt/master.d/reactor.conf
# A custom event containing: {"foo": "Foo!", "bar: "bar*", "baz": "Baz!"}
reactor:
- my/custom/event:
- /srv/reactor/some_event.sls

# /srv/reactor/some_event.sls
invoke_orchestrate_file:
runner.state.orchestrate:
- args:
- mods: orchestrate.do_complex_thing
- pillar:
event_tag: {{ tag }}
event_data: {{ data|json }}

# /srv/salt/orchestrate/do_complex_thing.sls
{% set tag = salt.pillar.get('event_tag') %}
{% set data = salt.pillar.get('event_data') %}

# Pass data from the event to a custom runner function.
# The function expects a 'foo' argument.
do_first_thing:
salt.runner:
- name: custom_runner.custom_function
- foo: {{ data.foo }}

# Wait for the runner to finish then send an execution to minions.
# Forward some data from the event down to the minion's state run.
do_second_thing:
salt.state:
- tgt: {{ data.bar }}
- sls:
- do_thing_on_minion
- kwarg:
pillar:
baz: {{ data.baz }}
- require:
- salt: do_first_thing

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.

Similarly, the data dictionary attached to the event would be located in {{
data['data']['data'] }} instead of {{ data['data'] }}.

See the beacon documentation for examples.

Manually Firing an Event
From the Master
Use the event.send runner:

salt-run event.send foo '{orchestrate: refresh}'

From the Minion
To fire an event to the master from a minion, call event.send:

salt-call event.send foo '{orchestrate: refresh}'

To fire an event to the minion's local event bus, call event.fire:

salt-call event.fire '{orchestrate: refresh}' foo

Referencing Data Passed in Events
Assuming any of the above examples, any reactor SLS files triggered by watching the event
tag foo will execute with {{ data['data']['orchestrate'] }} equal to 'refresh'.

Getting Information About Events
The best way to see exactly what events have been fired and what data is available in each
event is to use the state.event runner.

ORCHESTRATION

Orchestrate Runner
Executing states or highstate on a minion is perfect when you want to ensure that minion
configured and running the way you want. Sometimes however you want to configure a set of
minions all at once.

For example, if you want to set up a load balancer in front of a cluster of web servers
you can ensure the load balancer is set up first, and then the same matching configuration
is applied consistently across the whole cluster.

Orchestration is the way to do this.

The Orchestrate Runner
New in version 0.17.0.

NOTE:
Orchestrate Deprecates OverState

The Orchestrate Runner (originally called the state.sls runner) offers all the
functionality of the OverState, but with some advantages:

• All requisites available in states can be used.

• The states/functions will also work on salt-ssh minions.

The Orchestrate Runner replaced the OverState system in Salt 2015.8.0.

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.

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.

Writing SLS Files
Orchestrate SLS files are stored in the same location as State SLS files. This means that
both file_roots and gitfs_remotes impact what SLS files are available to the reactor and
orchestrator.

It is recommended to keep reactor and orchestrator SLS files in their own uniquely named
subdirectories such as _orch/, orch/, _orchestrate/, react/, _reactor/, etc. This will
avoid duplicate naming and will help prevent confusion.

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.

salt-run state.orchestrate orch.webserver

NOTE:
state.orch is a synonym for state.orchestrate

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.

salt-call --local state.orchestrate orch.webserver

NOTE:
Masterless orchestration supports only the salt.state command in an sls file; it does
not (currently) support the salt.function command.

Examples
Function
To execute a function, use salt.function:

# /srv/salt/orch/cleanfoo.sls
cmd.run:
salt.function:
- tgt: '*'
- arg:
- rm -rf /tmp/foo

salt-run state.orchestrate orch.cleanfoo

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:

copy_some_file:
salt.function:
- name: file.copy
- tgt: '*'
- arg:
- /path/to/file
- /tmp/copy_of_file
- kwarg:
remove_existing: true

State
To execute a state, use salt.state.

# /srv/salt/orch/webserver.sls
install_nginx:
salt.state:
- tgt: 'web*'
- sls:
- nginx

salt-run state.orchestrate orch.webserver

Highstate
To run a highstate, set highstate: True in your state config:

# /srv/salt/orch/web_setup.sls
webserver_setup:
salt.state:
- tgt: 'web*'
- highstate: True

salt-run state.orchestrate orch.web_setup

Runner
To execute another runner, use salt.runner. For example to use the cloud.profile runner
in your orchestration state additional options to replace values in the configured
profile, use this:

# /srv/salt/orch/deploy.sls
create_instance:
salt.runner:
- name: cloud.profile
- prof: cloud-centos
- provider: cloud
- instances:
- server1
- opts:
minion:
master: master1

To get a more dynamic state, use jinja variables together with inline pillar data. Using
the same example but passing on pillar data, the state would be like this.

# /srv/salt/orch/deploy.sls
{% set servers = salt['pillar.get']('servers', 'test') %}
{% set master = salt['pillar.get']('master', 'salt') %}
create_instance:
salt.runner:
- name: cloud.profile
- prof: cloud-centos
- provider: cloud
- instances:
- {{ servers }}
- opts:
minion:
master: {{ master }}

To execute with pillar data.

salt-run state.orch orch.deploy pillar='{"servers": "newsystem1",
"master": "mymaster"}'

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.

bootstrap_servers:
salt.function:
- name: cmd.run
- tgt: 10.0.0.0/24
- tgt_type: ipcidr
- arg:
- bootstrap

storage_setup:
salt.state:
- tgt: 'role:storage'
- tgt_type: grain
- sls: ceph
- require:
- salt: webserver_setup

webserver_setup:
salt.state:
- tgt: 'web*'
- highstate: True

Given the above setup, the orchestration will be carried out as follows:

1. The shell command bootstrap will be executed on all minions in the 10.0.0.0/24 subnet.

2. A Highstate will be run on all minions whose ID starts with "web", since the
storage_setup state requires it.

3. Finally, the ceph SLS target will be executed on all minions which have a grain called
role with a value of storage.

NOTE:
Remember, salt-run is always executed on the master.

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 is considered production ready in version 2014.7.0

• Python is required on the remote system (unless using the -r option to send raw ssh
commands)

• On many systems, the salt-ssh executable will be in its own package, usually named
salt-ssh

• The Salt SSH system does not supersede the standard Salt communication systems, it
simply offers an SSH-based alternative that does not require ZeroMQ and a remote agent.
Be aware that since all communication with Salt SSH is executed via SSH it is
substantially slower than standard Salt with ZeroMQ.

• At the moment fileserver operations must be wrapped to ensure that the relevant files
are delivered with the salt-ssh commands. The state module is an exception, which
compiles the state run on the master, and in the process finds all the references to
salt:// paths and copies those files down in the same tarball as the state run.
However, needed fileserver wrappers are still under development.

Salt SSH Roster
The roster system in Salt allows for remote minions to be easily defined.

NOTE:
See the SSH roster docs for more details.

Simply create the roster file, the default location is /etc/salt/roster:

web1: 192.168.42.1

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:

web1:
host: 192.168.42.1 # The IP addr or DNS hostname
user: fred # Remote executions will be executed as user fred
passwd: foobarbaz # The password to use for login, if omitted, keys are used
sudo: True # Whether to sudo to root, not enabled by default
web2:
host: 192.168.42.2

NOTE:
sudo works only if NOPASSWD is set for user in /etc/sudoers: fred ALL=(ALL) NOPASSWD:
ALL

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. The key generation happens when you run salt-ssh
for the first time.

You can use ssh-copy-id, (the OpenSSH key deployment tool) to deploy keys to your servers.

ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub user@server.demo.com

One could also create a simple shell script, named salt-ssh-copy-id.sh as follows:

#!/bin/bash
if [ -z $1 ]; then
echo $0 user@host.com
exit 0
fi
ssh-copy-id -i /etc/salt/pki/master/ssh/salt-ssh.rsa.pub $1

NOTE:
Be certain to chmod +x salt-ssh-copy-id.sh.

./salt-ssh-copy-id.sh user@server1.host.com
./salt-ssh-copy-id.sh user@server2.host.com

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:
salt-ssh on RHEL/CentOS 5

The salt-ssh command requires at least python 2.6, which is not installed by default on
RHEL/CentOS 5. An easy workaround in this situation is to use the -r option to run a
raw shell command that installs python26:

salt-ssh centos-5-minion -r 'yum -y install epel-release ; yum -y install python26'

NOTE:
salt-ssh on systems with Python 3.x

Salt, before the 2017.7.0 release, does not support Python 3.x which is the default on
for example the popular 16.04 LTS release of Ubuntu. An easy workaround for this
scenario is to use the -r option similar to the example above:

salt-ssh ubuntu-1604-minion -r 'apt update ; apt install -y python-minimal'

The salt-ssh command can be easily executed in the same way as a salt command:

salt-ssh '*' test.ping

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:

salt-ssh '*' -r 'ifconfig'

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:
By default, Grains are settable through salt-ssh. By default, these grains will not be
persisted across reboots.

See the "thin_dir" setting in Roster documentation for more details.

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:

salt-ssh:
config_dir: path/to/config/dir
ssh_max_procs: 30
ssh_wipe: True

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:
The option keys specified must match the destination attributes for the options
specified in the parser salt.utils.parsers.SaltSSHOptionParser. For example, in the
case of the --wipe command line option, its dest is configured to be ssh_wipe and thus
this is what should be configured in the Saltfile. Using the names of flags for this
option, being wipe: True or w: True, will not work.

NOTE:
For the Saltfile to be automatically detected it needs to be named Saltfile with a
capital S and be readable by the user running salt-ssh.

At last you can create ~/.salt/Saltfile and salt-ssh will automatically load it by
default.

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

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:

• /etc/salt/cloud: The main configuration file, contains global settings that apply to all
cloud hosts. See Salt Cloud Configuration.

• /etc/salt/cloud.providers.d/*.conf: Contains settings that configure a specific cloud
host, such as credentials, region settings, and so on. Since configuration varies
significantly between each cloud host, a separate file should be created for each cloud
host. In Salt Cloud, a provider is synonymous with a cloud host (Amazon EC2, Google
Compute Engine, Rackspace, and so on). See Provider Specifics.

• /etc/salt/cloud.profiles.d/*.conf: Contains settings that define a specific VM type. A
profile defines the systems specs and image, and any other settings that are specific to
this VM type. Each specific VM type is called a profile, and multiple profiles can be
defined in a profile file. Each profile references a parent provider that defines the
cloud host in which the VM is created (the provider settings are in the provider
configuration explained above). Based on your needs, you might define different
profiles for web servers, database servers, and so on. See VM Profiles.

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.

Alternatively, the -L option can be passed to the Salt Bootstrap script when installing
Salt. The -L option will install salt-cloud and the required libcloud package.

Using Salt Cloud
salt-cloud
Provision virtual machines in the cloud with Salt

Synopsis
salt-cloud -m /etc/salt/cloud.map

salt-cloud -m /etc/salt/cloud.map NAME

salt-cloud -m /etc/salt/cloud.map NAME1 NAME2

salt-cloud -p PROFILE NAME

salt-cloud -p PROFILE NAME1 NAME2 NAME3 NAME4 NAME5 NAME6

Description
Salt Cloud is the system used to provision virtual machines on various public clouds via a
cleanly controlled profile and mapping system.

Options
--version
Print the version of Salt that is running.

--versions-report
Show program's dependencies and version number, and then exit

-h, --help
Show the help message and exit

-c CONFIG_DIR, --config-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains the
configuration files for Salt master and minions. The default location on most
systems is /etc/salt.

Execution Options
-L LOCATION, --location=LOCATION
Specify which region to connect to.

-a ACTION, --action=ACTION
Perform an action that may be specific to this cloud provider. This argument
requires one or more instance names to be specified.

-f <FUNC-NAME> <PROVIDER>, --function=<FUNC-NAME> <PROVIDER>
Perform an function that may be specific to this cloud provider, that does not
apply to an instance. This argument requires a provider to be specified (i.e.:
nova).

-p PROFILE, --profile=PROFILE
Select a single profile to build the named cloud VMs from. The profile must be
defined in the specified profiles file.

-m MAP, --map=MAP
Specify a map file to use. If used without any other options, this option will
ensure that all of the mapped VMs are created. If the named VM already exists then
it will be skipped.

-H, --hard
When specifying a map file, the default behavior is to ensure that all of the VMs
specified in the map file are created. If the --hard option is set, then any VMs
that exist on configured cloud providers that are not specified in the map file
will be destroyed. Be advised that this can be a destructive operation and should
be used with care.

-d, --destroy
Pass in the name(s) of VMs to destroy, salt-cloud will search the configured cloud
providers for the specified names and destroy the VMs. Be advised that this is a
destructive operation and should be used with care. Can be used in conjunction with
the -m option to specify a map of VMs to be deleted.

-P, --parallel
Normally when building many cloud VMs they are executed serially. The -P option
will run each cloud vm build in a separate process allowing for large groups of VMs
to be build at once.

Be advised that some cloud provider's systems don't seem to be well suited for this
influx of vm creation. When creating large groups of VMs watch the cloud provider
carefully.

-u, --update-bootstrap
Update salt-bootstrap to the latest stable bootstrap release.

-y, --assume-yes
Default yes in answer to all confirmation questions.

-k, --keep-tmp
Do not remove files from /tmp/ after deploy.sh finishes.

--show-deploy-args
Include the options used to deploy the minion in the data returned.

--script-args=SCRIPT_ARGS
Script arguments to be fed to the bootstrap script when deploying the VM.

Query Options
-Q, --query
Execute a query and return some information about the nodes running on configured
cloud providers

-F, --full-query
Execute a query and print out all available information about all cloud VMs. Can
be used in conjunction with -m to display only information about the specified map.

-S, --select-query
Execute a query and print out selected information about all cloud VMs. Can be
used in conjunction with -m to display only information about the specified map.

--list-providers
Display a list of configured providers.

--list-profiles
New in version 2014.7.0.

Display a list of configured profiles. Pass in a cloud provider to view the
provider's associated profiles, such as digital_ocean, or pass in all to list all
the configured profiles.

Cloud Providers Listings
--list-locations=LIST_LOCATIONS
Display a list of locations available in configured cloud providers. Pass the cloud
provider that available locations are desired on, aka "linode", or pass "all" to
list locations for all configured cloud providers

--list-images=LIST_IMAGES
Display a list of images available in configured cloud providers. Pass the cloud
provider that available images are desired on, aka "linode", or pass "all" to list
images for all configured cloud providers

--list-sizes=LIST_SIZES
Display a list of sizes available in configured cloud providers. Pass the cloud
provider that available sizes are desired on, aka "AWS", or pass "all" to list
sizes for all configured cloud providers

Cloud Credentials
--set-password=<USERNAME> <PROVIDER>
Configure password for a cloud provider and save it to the keyring. PROVIDER can
be specified with or without a driver, for example: "--set-password bob rackspace"
or more specific "--set-password bob rackspace:openstack" DEPRECATED!

Output Options
--out Pass in an alternative outputter to display the return of data. This outputter can
be any of the available outputters:
grains, highstate, json, key, overstatestage, pprint, raw, txt, yaml

Some outputters are formatted only for data returned from specific functions; for
instance, the grains outputter will not work for non-grains data.

If an outputter is used that does not support the data passed into it, then Salt
will fall back on the pprint outputter and display the return data using the Python
pprint standard library module.

NOTE:
If using --out=json, you will probably want --static as well. Without the
static option, you will get a separate JSON string per minion which makes JSON
output invalid as a whole. This is due to using an iterative outputter. So if
you want to feed it to a JSON parser, use --static as well.

--out-indent OUTPUT_INDENT, --output-indent OUTPUT_INDENT
Print the output indented by the provided value in spaces. Negative values disable
indentation. Only applicable in outputters that support indentation.

--out-file=OUTPUT_FILE, --output-file=OUTPUT_FILE
Write the output to the specified file.

--out-file-append, --output-file-append
Append the output to the specified file.

--no-color
Disable all colored output

--force-color
Force colored output

NOTE:
When using colored output the color codes are as follows:

green denotes success, red denotes failure, blue denotes changes and success and
yellow denotes a expected future change in configuration.

--state-output=STATE_OUTPUT, --state_output=STATE_OUTPUT
Override the configured state_output value for minion output. One of 'full',
'terse', 'mixed', 'changes' or 'filter'. Default: 'none'.

--state-verbose=STATE_VERBOSE, --state_verbose=STATE_VERBOSE
Override the configured state_verbose value for minion output. Set to True or
False. Default: none.

Examples
To create 4 VMs named web1, web2, db1, and db2 from specified profiles:

salt-cloud -p fedora_rackspace web1 web2 db1 db2

To read in a map file and create all VMs specified therein:

salt-cloud -m /path/to/cloud.map

To read in a map file and create all VMs specified therein in parallel:

salt-cloud -m /path/to/cloud.map -P

To delete any VMs specified in the map file:

salt-cloud -m /path/to/cloud.map -d

To delete any VMs NOT specified in the map file:

salt-cloud -m /path/to/cloud.map -H

To display the status of all VMs specified in the map file:

salt-cloud -m /path/to/cloud.map -Q

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:

salt-cloud -p <profile> name_of_vm

Assuming there is a profile configured as following:

fedora_rackspace:
provider: my-rackspace-config
image: Fedora 17
size: 256 server
script: bootstrap-salt

Then, the command to create new VM named fedora_http_01 is:

salt-cloud -p fedora_rackspace fedora_http_01

Destroying a VM
To destroy a created-by-salt-cloud VM, use command:

salt-cloud -d name_of_vm

For example, to delete the VM created on above example, use:

salt-cloud -d fedora_http_01

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:

fedora_rackspace:
provider: my-rackspace-config
image: Fedora 17
size: 256 server
script: bootstrap-salt

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:

centos_rackspace:
provider: my-rackspace-config
image: CentOS 6.2
size: 1024 server
minion:
master: salt.example.com
append_domain: webs.example.com
grains:
role: webserver

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:

salt-cloud --list-images openstack
salt-cloud --list-sizes openstack

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
rhel_ec2:
provider: my-ec2-config
image: ami-e565ba8c
size: t1.micro
minion:
cheese: edam

ubuntu_ec2:
provider: my-ec2-config
image: ami-7e2da54e
size: t1.micro
minion:
cheese: edam

ubuntu_rackspace:
provider: my-rackspace-config
image: Ubuntu 12.04 LTS
size: 256 server
minion:
cheese: edam

fedora_rackspace:
provider: my-rackspace-config
image: Fedora 17
size: 256 server
minion:
cheese: edam

cent_linode:
provider: my-linode-config
image: CentOS 6.2 64bit
size: Linode 512

cent_gogrid:
provider: my-gogrid-config
image: 12834
size: 512MB

cent_joyent:
provider: my-joyent-config
image: centos-7
size: g4-highram-16G

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:

fedora_small:
- web1
- web2
- web3
fedora_high:
- redis1
- redis2
- redis3
cent_high:
- riak1
- riak2
- riak3

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:

$ salt-cloud -m /path/to/mapfile

Remember, that as with direct profile provisioning the -P option can be passed to create
the virtual machines in parallel:

$ salt-cloud -m /path/to/mapfile -P

NOTE:
Due to limitations in the GoGrid API, instances cannot be provisioned in parallel with
the GoGrid driver. Map files will work with GoGrid, but the -P argument should not be
used on maps referencing GoGrid instances.

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:

$ salt-cloud -m /path/to/mapfile -P -H

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.

enable_hard_maps: True

A map file can include grains and minion configuration options:

fedora_small:
- web1:
minion:
log_level: debug
grains:
cheese: tasty
omelet: du fromage
- web2:
minion:
log_level: warn
grains:
cheese: more tasty
omelet: with peppers

Any top level data element from your profile may be overridden in the map file:

fedora_small:
- web1:
size: t2.micro
- web2:
size: t2.nano

As of Salt 2017.7.0, nested elements are merged, and can can be specified individually
without having to repeat the complete definition for each top level data element. In this
example a separate MAC is assigned to each VMware instance while inheriting device
parameters for for disk and network configuration:

nyc-vm:
- db1:
devices:
network:
Network Adapter 1:
mac: '44:44:44:44:44:41'
- db2:
devices:
network:
Network Adapter 1:
mac: '44:44:44:44:44:42'

A map file may also be used with the various query options:

$ salt-cloud -m /path/to/mapfile -Q
{'ec2': {'web1': {'id': 'i-e6aqfegb',
'image': None,
'private_ips': [],
'public_ips': [],
'size': None,
'state': 0}},
'web2': {'Absent'}}

...or with the delete option:

$ salt-cloud -m /path/to/mapfile -d
The following virtual machines are set to be destroyed:
web1
web2

Proceed? [N/y]

WARNING:
Specifying Nodes with Maps on the Command Line Specifying the name of a node or nodes
with the maps options on the command line is not supported. This is especially
important to remember when using --destroy with maps; salt-cloud will ignore any
arguments passed in which are not directly relevant to the map file. When using
``--destroy`` with a map, every node in the map file will be deleted! Maps don't
provide any useful information for destroying individual nodes, and should not be used
to destroy a subset of a map.

Setting up New Salt Masters
Bootstrapping a new master in the map is as simple as:

fedora_small:
- web1:
make_master: True
- web2
- web3

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:

fedora_small:
- web1:
make_master: True
minion:
master: <the local master ip address>
local_master: True
- web2
- web3

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:

fedora_small:
- web1:
make_master: True
- web2
- web3:
minion:
master: <the local master ip address>
local_master: True

The above example makes the web3 minion answer to the local master, not the newly created
master.

Using Direct Map Data
When using modules that access the CloudClient directly (notably, the cloud execution and
runner modules), it is possible to pass in the contents of a map file, rather than a path
to the location of the map file.

Normally when using these modules, the path to the map file is passed in using:

salt-run cloud.map_run /path/to/cloud.map

To pass in the actual map data, use the map_data argument:

salt-run cloud.map_run map_data='{"centos7": [{"saltmaster": {"minion": \
{"transport": "tcp"}, "make_master": true, "master": {"transport": \
"tcp"}}}, {"minion001": {"minion": {"transport": "tcp"}}}]}'

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:

$ salt-cloud -a reboot vm_name
$ salt-cloud -a reboot vm1 vm2 vm2

Or you may specify a map which includes all VMs to perform the action on:

$ salt-cloud -a reboot -m /path/to/mapfile

The following is an example list of actions currently supported by salt-cloud:

all providers:
- reboot
ec2:
- start
- stop
joyent:
- stop
linode:
- start
- stop

Another useful reference for viewing more salt-cloud actions is the 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.

$ salt-cloud -f show_image ec2 image=ami-fd20ad94

There are three universal salt-cloud functions that are extremely useful for gathering
information about instances on a provider basis:

• list_nodes: Returns some general information about the instances for the given provider.

• list_nodes_full: Returns all information about the instances for the given provider.

• list_nodes_select: Returns select information about the instances for the given
provider.

$ salt-cloud -f list_nodes linode
$ salt-cloud -f list_nodes_full linode
$ salt-cloud -f list_nodes_select linode

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:

sudo add-apt-repository ppa:saltstack/salt
sudo apt-get update
sudo apt-get install salt-cloud

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:

sudo port install curl-ca-bundle

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.

pool_size: 10

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.

minion:
master: saltmaster.example.com

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:

ec2-web:
size: t1.micro
minion:
environment: test
startup_states: sls
sls_list:
- web

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:

# /etc/salt/cloud
providers:
my-aws-migrated-config:
id: HJGRYCILJLKJYG
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
keyname: test
securitygroup: quick-start
private_key: /root/test.pem
driver: ec2

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:

# /etc/salt/cloud.providers
# or could be /etc/salt/cloud.providers.d/*.conf
my-aws-config:
id: HJGRYCILJLKJYG
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
keyname: test
securitygroup: quick-start
private_key: /root/test.pem
driver: ec2

NOTE:
Salt Cloud provider configurations within /etc/cloud.provider.d/ should not specify the
providers starting key.

It is also possible to have multiple cloud configuration blocks within the same alias
block. For example:

production-config:
- id: HJGRYCILJLKJYG
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
keyname: test
securitygroup: quick-start
private_key: /root/test.pem
driver: ec2

- user: example_user
apikey: 123984bjjas87034
driver: rackspace

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:

rhel_aws_dev:
provider: production-config:ec2
image: ami-e565ba8c
size: t1.micro

rhel_aws_prod:
provider: production-config:ec2
image: ami-e565ba8c
size: High-CPU Extra Large Instance

database_prod:
provider: production-config:rackspace
image: Ubuntu 12.04 LTS
size: 256 server

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:
ssh_key_name: saltstack
ssh_key_file: /root/.ssh/id_rsa
update_cachedir: True
diff_cache_events: True
change_password: True

providers:
my-nova:
identity_url: https://identity.api.rackspacecloud.com/v2.0/
compute_region: IAD
user: myuser
api_key: apikey
tenant: 123456
driver: nova

my-openstack:
identity_url: https://identity.api.rackspacecloud.com/v2.0/tokens
user: user2
apikey: apikey2
tenant: 654321
compute_region: DFW
driver: openstack
compute_name: cloudServersOpenStack

profiles:
ubuntu-nova:
provider: my-nova
size: performance1-8
image: bb02b1a3-bc77-4d17-ab5b-421d89850fca
script_args: git develop

ubuntu-openstack:
provider: my-openstack
size: performance1-8
image: bb02b1a3-bc77-4d17-ab5b-421d89850fca
script_args: git develop

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.

my-scaleway-config:
access_key: 15cf404d-4560-41b1-9a0c-21c3d5c4ff1f
token: a7347ec8-5de1-4024-a5e3-24b77d1ba91d
driver: scaleway

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-scaleway-config.

Rackspace
Rackspace cloud requires two configuration options; a user and an apikey:

my-rackspace-config:
user: example_user
apikey: 123984bjjas87034
driver: rackspace

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-rackspace-config.

Amazon AWS
A number of configuration options are required for Amazon AWS including id, key, keyname,
securitygroup, and private_key:

my-aws-quick-start:
id: HJGRYCILJLKJYG
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
keyname: test
securitygroup: quick-start
private_key: /root/test.pem
driver: ec2

my-aws-default:
id: HJGRYCILJLKJYG
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
keyname: test
securitygroup: default
private_key: /root/test.pem
driver: ec2

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be either provider: my-aws-quick-start or provider:
my-aws-default.

Linode
Linode requires a single API key, but the default root password also needs to be set:

my-linode-config:
apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf
password: F00barbaz
ssh_pubkey: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHEOLLbeXgaqRQT9NBAopVz366SdYc0KKX33vAnq+2R user@host
ssh_key_file: ~/.ssh/id_ed25519
driver: linode

The password needs to be 8 characters and contain lowercase, uppercase, and numbers.

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-linode-config

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.

my-joyent-config:
user: fred
password: saltybacon
private_key: /root/joyent.pem
driver: joyent

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-joyent-config

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:

my-gogrid-config:
apikey: asdff7896asdh789
sharedsecret: saltybacon
driver: gogrid

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-gogrid-config.

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.

# For HP
my-openstack-hp-config:
identity_url:
'https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/'
compute_name: Compute
compute_region: 'az-1.region-a.geo-1'
tenant: myuser-tenant1
user: myuser
ssh_key_name: mykey
ssh_key_file: '/etc/salt/hpcloud/mykey.pem'
password: mypass
driver: openstack

# For Rackspace
my-openstack-rackspace-config:
identity_url: 'https://identity.api.rackspacecloud.com/v2.0/tokens'
compute_name: cloudServersOpenStack
protocol: ipv4
compute_region: DFW
user: myuser
tenant: 5555555
password: mypass
driver: openstack

If you have an API key for your provider, it may be specified instead of a password:

my-openstack-hp-config:
apikey: 901d3f579h23c8v73q9

my-openstack-rackspace-config:
apikey: 901d3f579h23c8v73q9

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be either provider: my-openstack-hp-config or provider:
my-openstack-rackspace-config.

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:

my-openstack-config:
ignore_cidr: 192.168.0.0/16

For in-house OpenStack Essex installation, libcloud needs the service_type :

my-openstack-config:
identity_url: 'http://control.openstack.example.org:5000/v2.0/'
compute_name : Compute Service
service_type : compute

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.

my-digitalocean-config:
driver: digital_ocean
personal_access_token: xxx
location: New York 1

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-digital-ocean-config.

Parallels
Using Salt with Parallels requires a user, password and URL. These can be obtained from
your cloud provider.

my-parallels-config:
user: myuser
password: xyzzy
url: https://api.cloud.xmission.com:4465/paci/v1.0/
driver: parallels

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-parallels-config.

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.

my-proxmox-config:
driver: proxmox
user: saltcloud@pve
password: xyzzy
url: your.proxmox.host

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: my-proxmox-config.

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.

devhost10-lxc:
target: devhost10
driver: lxc

And in the map file:

devhost10-lxc:
provider: devhost10-lxc
from_container: ubuntu
backing: lvm
sudo: True
size: 3g
ip: 10.0.3.9
minion:
master: 10.5.0.1
master_port: 4506
lxc_conf:
- lxc.utsname: superlxc

NOTE:
In the cloud profile that uses this provider configuration, the syntax for the provider
required field would be provider: devhost10-lxc.

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 cloud profiles and providers is not recursive. For example, a profile that is
extended by a second profile is possible, but the second profile cannot be extended by
a third profile.

Also, if a profile (or provider) is extending another profile and each contains a list
of values, the lists from the extending profile will override the list from the
original profile. The lists are not merged together.

Extending Profiles
Some example usage on how to use extends with profiles. Consider
/etc/salt/salt/cloud.profiles containing:

development-instances:
provider: my-ec2-config
size: t1.micro
ssh_username: ec2_user
securitygroup:
- default
deploy: False

Amazon-Linux-AMI-2012.09-64bit:
image: ami-54cf5c3d
extends: development-instances

Fedora-17:
image: ami-08d97e61
extends: development-instances

CentOS-5:
provider: my-aws-config
image: ami-09b61d60
extends: development-instances

The above configuration, once parsed would generate the following profiles data:

[{'deploy': False,
'image': 'ami-08d97e61',
'profile': 'Fedora-17',
'provider': 'my-ec2-config',
'securitygroup': ['default'],
'size': 't1.micro',
'ssh_username': 'ec2_user'},
{'deploy': False,
'image': 'ami-09b61d60',
'profile': 'CentOS-5',
'provider': 'my-aws-config',
'securitygroup': ['default'],
'size': 't1.micro',
'ssh_username': 'ec2_user'},
{'deploy': False,
'image': 'ami-54cf5c3d',
'profile': 'Amazon-Linux-AMI-2012.09-64bit',
'provider': 'my-ec2-config',
'securitygroup': ['default'],
'size': 't1.micro',
'ssh_username': 'ec2_user'},
{'deploy': False,
'profile': 'development-instances',
'provider': 'my-ec2-config',
'securitygroup': ['default'],
'size': 't1.micro',
'ssh_username': 'ec2_user'}]

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:

my-develop-envs:
- id: HJGRYCILJLKJYG
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
keyname: test
securitygroup: quick-start
private_key: /root/test.pem
location: ap-southeast-1
availability_zone: ap-southeast-1b
driver: ec2

- user: myuser@mycorp.com
password: mypass
ssh_key_name: mykey
ssh_key_file: '/etc/salt/ibm/mykey.pem'
location: Raleigh
driver: ibmsce

my-productions-envs:
- extends: my-develop-envs:ibmsce
user: my-production-user@mycorp.com
location: us-east-1
availability_zone: us-east-1

The above configuration, once parsed would generate the following providers data:

'providers': {
'my-develop-envs': [
{'availability_zone': 'ap-southeast-1b',
'id': 'HJGRYCILJLKJYG',
'key': 'kdjgfsgm;woormgl/aserigjksjdhasdfgn',
'keyname': 'test',
'location': 'ap-southeast-1',
'private_key': '/root/test.pem',
'driver': 'aws',
'securitygroup': 'quick-start'
},
{'location': 'Raleigh',
'password': 'mypass',
'driver': 'ibmsce',
'ssh_key_file': '/etc/salt/ibm/mykey.pem',
'ssh_key_name': 'mykey',
'user': 'myuser@mycorp.com'
}
],
'my-productions-envs': [
{'availability_zone': 'us-east-1',
'location': 'us-east-1',
'password': 'mypass',
'driver': 'ibmsce',
'ssh_key_file': '/etc/salt/ibm/mykey.pem',
'ssh_key_name': 'mykey',
'user': 'my-production-user@mycorp.com'
}
]
}

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:

• impacket project home

winexe is less commonly available in distribution-specific repositories. However, it is
currently being built for various distributions in 3rd party channels:

• RPMs at pbone.net

• openSUSE Build Service

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:

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

• SaltStack Download Area

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:

<powershell>
New-NetFirewallRule -Name "SMB445" -DisplayName "SMB445" -Protocol TCP -LocalPort 445
Set-Item (dir wsman:\localhost\Listener\*\Port -Recurse).pspath 445 -Force
Restart-Service winrm
</powershell>

For EC2, this script may be saved as a file, and specified in the provider or profile
configuration as userdata_file. For instance:

my-ec2-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/windows-firewall.ps1

NOTE:
From versions 2016.11.0 and 2016.11.3, this file was passed through the master's
renderer to template it. However, this caused issues with non-YAML data, so templating
is no longer performed by default. To template the userdata_file, add a
userdata_template option to the cloud profile:

my-ec2-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/windows-firewall.ps1
userdata_template: jinja

If no userdata_template is set in the cloud profile, then the master configuration will
be checked for a userdata_template value. If this is not set, then no templating will
be performed on the userdata_file.

To disable templating in a cloud profile when a userdata_template has been set in the
master configuration file, simply set userdata_template to False in the cloud profile:

my-ec2-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/windows-firewall.ps1
userdata_template: False

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:

<powershell>
New-NetFirewallRule -Name "SMB445" -DisplayName "SMB445" -Protocol TCP -LocalPort 445
New-NetFirewallRule -Name "WINRM5986" -DisplayName "WINRM5986" -Protocol TCP -LocalPort 5986

winrm quickconfig -q
winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="300"}'
winrm set winrm/config '@{MaxTimeoutms="1800000"}'
winrm set winrm/config/service/auth '@{Basic="true"}'

$SourceStoreScope = 'LocalMachine'
$SourceStorename = 'Remote Desktop'

$SourceStore = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $SourceStorename, $SourceStoreScope
$SourceStore.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadOnly)

$cert = $SourceStore.Certificates | Where-Object -FilterScript {
$_.subject -like '*'
}

$DestStoreScope = 'LocalMachine'
$DestStoreName = 'My'

$DestStore = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $DestStoreName, $DestStoreScope
$DestStore.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadWrite)
$DestStore.Add($cert)

$SourceStore.Close()
$DestStore.Close()

winrm create winrm/config/listener?Address=*+Transport=HTTPS `@`{Hostname=`"($certId)`"`;CertificateThumbprint=`"($cert.Thumbprint)`"`}

Restart-Service winrm
</powershell>

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:

my-softlayer:
driver: softlayer
user: MYUSER1138
apikey: 'e3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9'
minion:
master: saltmaster.example.com
win_installer: /root/Salt-Minion-2014.7.0-AMD64-Setup.exe
win_username: Administrator
win_password: letmein
smb_port: 445

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:

windows-server-2012:
provider: my-ec2-config
image: ami-c49c0dac
size: m1.small
securitygroup: windows
keyname: mykey
private_key: /root/mykey.pem
userdata_file: /etc/salt/windows-firewall.ps1
win_installer: /root/Salt-Minion-2014.7.0-AMD64-Setup.exe
win_username: Administrator
win_password: auto

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: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-aliyun-config:
# aliyun Access Key ID
id: wDGEwGregedg3435gDgxd
# aliyun Access Key Secret
key: GDd45t43RDBTrkkkg43934t34qT43t4dgegerGEgg
location: cn-qingdao
driver: aliyun

NOTE:
Changed in version 2015.8.0.

The provider parameter in cloud provider definitions was renamed to driver. This change
was made to avoid confusion with the provider parameter that is used in cloud profile
definitions. Cloud provider definitions now use driver to refer to the Salt cloud
module that provides the underlying functionality to connect to a cloud host, while
cloud profiles continue to use provider to refer to provider configurations that you
define.

Profiles
Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles or in the
/etc/salt/cloud.profiles.d/ directory:

aliyun_centos:
provider: my-aliyun-config
size: ecs.t1.small
location: cn-qingdao
securitygroup: G1989096784427999
image: centos6u3_64_20G_aliaegis_20130816.vhd

Sizes can be obtained using the --list-sizes option for the salt-cloud command:

# salt-cloud --list-sizes my-aliyun-config
my-aliyun-config:
----------
aliyun:
----------
ecs.c1.large:
----------
CpuCoreCount:
8
InstanceTypeId:
ecs.c1.large
MemorySize:
16.0

...SNIP...

Images can be obtained using the --list-images option for the salt-cloud command:

# salt-cloud --list-images my-aliyun-config
my-aliyun-config:
----------
aliyun:
----------
centos5u8_64_20G_aliaegis_20131231.vhd:
----------
Architecture:
x86_64
Description:

ImageId:
centos5u8_64_20G_aliaegis_20131231.vhd
ImageName:
CentOS 5.8 64位
ImageOwnerAlias:
system
ImageVersion:
1.0
OSName:
CentOS 5.8 64位
Platform:
CENTOS5
Size:
20
Visibility:
public
...SNIP...

Locations can be obtained using the --list-locations option for the salt-cloud command:

my-aliyun-config:
----------
aliyun:
----------
cn-beijing:
----------
LocalName:
北京
RegionId:
cn-beijing
cn-hangzhou:
----------
LocalName:
杭州
RegionId:
cn-hangzhou
cn-hongkong:
----------
LocalName:
香港
RegionId:
cn-hongkong
cn-qingdao:
----------
LocalName:
青岛
RegionId:
cn-qingdao

Security Group can be obtained using the -f list_securitygroup option for the salt-cloud
command:

# salt-cloud --location=cn-qingdao -f list_securitygroup my-aliyun-config
my-aliyun-config:
----------
aliyun:
----------
G1989096784427999:
----------
Description:
G1989096784427999
SecurityGroupId:
G1989096784427999

NOTE:
Aliyun ECS REST API documentation is available from Aliyun ECS API.

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
• Microsoft Azure SDK for Python >= 1.0.2

• The python-requests library, for Python < 2.7.9.

• A Microsoft Azure account

• OpenSSL (to generate the certificates)

• Salt

NOTE:
The Azure driver is currently being updated to work with the new version of the Python
Azure SDK, 1.0.0. However until that process is complete, this driver will not work
with Azure 1.0.0. Please be sure you're running on a minimum version of 0.10.2 and less
than version 1.0.0.

See Issue #27980 for more information.

Configuration
Set up the provider config at /etc/salt/cloud.providers.d/azure.conf:

# Note: This example is for /etc/salt/cloud.providers.d/azure.conf

my-azure-config:
driver: azure
subscription_id: 3287abc8-f98a-c678-3bde-326766fd3617
certificate_path: /etc/salt/azure.pem

# Set up the location of the salt master
#
minion:
master: saltmaster.example.com

# Optional
management_host: management.core.windows.net

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:

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout /etc/salt/azure.pem -out /etc/salt/azure.pem

To create the .cer file, execute the following command:

openssl x509 -inform pem -in /etc/salt/azure.pem -outform der -out /etc/salt/azure.cer

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:
Changed in version 2015.8.0.

Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles:

azure-ubuntu:
provider: my-azure-config
image: 'b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-12_04_3-LTS-amd64-server-20131003-en-us-30GB'
size: Small
location: 'East US'
ssh_username: azureuser
ssh_password: verybadpass
slot: production
media_link: 'http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds'
virtual_network_name: azure-virtual-network
subnet_name: azure-subnet

These options are described in more detail below. Once configured, the profile can be
realized with a salt command:

salt-cloud -p azure-ubuntu newinstance

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:

salt newinstance test.ping

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:

salt-cloud --list-images my-azure-config

size
The name of the size to use to create a VM. Available sizes can be viewed using the
following command:

salt-cloud --list-sizes my-azure-config

location
The name of the location to create a VM in. Available locations can be viewed using the
following command:

salt-cloud --list-locations my-azure-config

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:

http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds

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.

salt-cloud -a show_instance myinstance

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.

salt-cloud -f create_service my-azure name=my-service label=my-service location='West US'

show_service
Return details about a specific hosted service. Can also be called with get_service.

salt-cloud -f show_storage my-azure name=my-service

list_services
List all hosted services associates with the subscription.

salt-cloud -f list_services my-azure-config

delete_service
Delete a specific hosted service.

salt-cloud -f delete_service my-azure name=my-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:

• Standard_LRS

• Standard_ZRS

• Standard_GRS

• Standard_RAGRS

CLI Example
The following example illustrates creating a storage account.

salt-cloud -f create_storage my-azure name=my-storage label=my-storage location='West US'

list_storage
List all storage accounts associates with the subscription.

salt-cloud -f list_storage my-azure-config

show_storage
Return details about a specific storage account. Can also be called with get_storage.

salt-cloud -f show_storage my-azure name=my-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.

salt-cloud -f update_storage my-azure name=my-storage label=my-storage

delete_storage
Delete a specific storage account.

salt-cloud -f delete_storage my-azure name=my-storage

show_storage_keys
Returns the primary and secondary access keys for the specified storage account.

salt-cloud -f show_storage_keys my-azure name=my-storage

regenerate_storage_keys
Regenerate storage account keys. Requires a key_type ("primary" or "secondary") to be
specified.

salt-cloud -f regenerate_storage_keys my-azure name=my-storage key_type=primary

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.

salt-cloud -f show_disk my-azure name=my-disk

list_disks
List all disks associates with the account.

salt-cloud -f list_disks my-azure

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.

salt-cloud -f update_disk my-azure name=my-disk label=my-disk

delete_disk
Delete a specific disk.

salt-cloud -f delete_disk my-azure name=my-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:

• Manage Certificates

The following functions are available.

list_service_certificates
List service certificates associated with the account.

salt-cloud -f list_service_certificates my-azure

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.

salt-cloud -f show_service_certificate my-azure name=my_service_certificate \
thumbalgorithm=sha1 thumbprint=0123456789ABCDEF

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:

• Create a Service Certificate for Azure

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.

salt-cloud -f add_service_certificate my-azure name=my-cert \
data='...CERT_DATA...' certificate_format=pfx password=verybadpass

delete_service_certificate
Delete a service certificate from the account. The name, thumbprint, and thumbalgorithm
can be obtained from list_service_certificates.

salt-cloud -f delete_service_certificate my-azure \
name=my_service_certificate \
thumbalgorithm=sha1 thumbprint=0123456789ABCDEF

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.

• Manage Certificates

The following functions are available.

list_management_certificates
List management certificates associated with the account.

salt-cloud -f list_management_certificates my-azure

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.

salt-cloud -f show_management_certificate my-azure name=my_management_certificate \
thumbalgorithm=sha1 thumbprint=0123456789ABCDEF

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:

• Create and Upload a Management Certificate for Azure

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.

salt-cloud -f add_management_certificate my-azure public_key='...PUBKEY...' \
thumbprint=0123456789ABCDEF data='...CERT_DATA...'

delete_management_certificate
Delete a management certificate from the account. The thumbprint can be obtained from
list_management_certificates.

salt-cloud -f delete_management_certificate my-azure thumbprint=0123456789ABCDEF

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.

salt-cloud -f list_virtual_networks my-azure service=myservice deployment=mydeployment

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:

backend: requests

The following functions are available.

list_input_endpoints
List input endpoints associated with the deployment

salt-cloud -f list_input_endpoints my-azure service=myservice deployment=mydeployment

show_input_endpoint
Show an input endpoint associated with the deployment

salt-cloud -f show_input_endpoint my-azure service=myservice \
deployment=mydeployment name=SSH

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.

• Load Balancing for Azure Infrastructure Services

timeout_for_tcp_idle_connection
Optional. The default value is 4. Please see the following article for an explanation of
this option.

• Configurable Idle Timeout for Azure Load Balancer

CLI Example
The following example illustrates adding an input endpoint.

salt-cloud -f add_input_endpoint my-azure service=myservice \
deployment=mydeployment role=myrole name=HTTP local_port=80 \
port=80 protocol=tcp enable_direct_server_return=False \
timeout_for_tcp_idle_connection=4

update_input_endpoint
Updates the details for a specific input endpoint. All options from add_input_endpoint are
supported.

salt-cloud -f update_input_endpoint my-azure service=myservice \
deployment=mydeployment role=myrole name=HTTP local_port=80 \
port=80 protocol=tcp enable_direct_server_return=False \
timeout_for_tcp_idle_connection=4

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.

salt-cloud -f delete_input_endpoint my-azure service=myservice \
deployment=mydeployment role=myrole name=HTTP

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:

• Create an Affinity Group in the Management Portal

The following functions are available.

list_affinity_groups
List input endpoints associated with the account

salt-cloud -f list_affinity_groups my-azure

show_affinity_group
Show an affinity group associated with the account

salt-cloud -f show_affinity_group my-azure service=myservice \
deployment=mydeployment name=SSH

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.

salt-cloud -f create_affinity_group my-azure name=my_affinity_group \
label=my-affinity-group location='West US'

update_affinity_group
Update an affinity group's properties

salt-cloud -f update_affinity_group my-azure name=my_group label=my_group

delete_affinity_group
Delete a specific affinity group associated with the account

salt-cloud -f delete_affinity_group my-azure name=my_affinity_group

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: mystorage
storage_key: ffhj334fDSGFEGDFGFDewr34fwfsFSDFwe==

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

salt-cloud -f make_blob_url my-azure container=mycontainer blob=myblob

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

salt-cloud -f list_storage_containers my-azure

create_storage_container
Create a storage container

salt-cloud -f create_storage_container my-azure name=mycontainer

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

salt-cloud -f show_storage_container my-azure name=myservice

name
Name of container to show.

show_storage_container_metadata
Show a storage container's metadata

salt-cloud -f show_storage_container_metadata my-azure name=myservice

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

salt-cloud -f set_storage_container my-azure name=mycontainer \
x_ms_meta_name_values='{"my_name": "my_value"}'

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

salt-cloud -f show_storage_container_acl my-azure name=myservice

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

salt-cloud -f set_storage_container my-azure name=mycontainer

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

salt-cloud -f delete_storage_container my-azure name=mycontainer

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

salt-cloud -f lease_storage_container my-azure name=mycontainer

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

salt-cloud -f list_blobs my-azure container=mycontainer

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:

snapshots:
Specifies that snapshots should be included in the
enumeration. Snapshots are listed from oldest to newest in
the response.
metadata:
Specifies that blob metadata be returned in the response.
uncommittedblobs:
Specifies that blobs for which blocks have been uploaded,
but which have not been committed using Put Block List
(REST API), be included in the response.
copy:
Version 2012-02-12 and newer. Specifies that metadata
related to any current or previous Copy Blob operation
should be included in the response.

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

salt-cloud -f show_blob_service_properties my-azure

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.

salt-cloud -f set_blob_service_properties my-azure

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.

salt-cloud -f show_blob_properties my-azure container=mycontainer blob=myblob

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

salt-cloud -f set_blob_properties my-azure

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

salt-cloud -f put_blob my-azure container=base name=top.sls blob_path=/srv/salt/top.sls
salt-cloud -f put_blob my-azure container=base name=content.txt blob_content='Some content'

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

salt-cloud -f get_blob my-azure container=base name=top.sls local_path=/srv/salt/top.sls
salt-cloud -f get_blob my-azure container=base name=content.txt return_content=True

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
• Microsoft Azure SDK for Python >= 2.0rc6

• Microsoft Azure Storage SDK for Python >= 0.32

• The python-requests library, for Python < 2.7.9.

• A Microsoft Azure account

• Salt

Installation Tips
Because the azure library requires the cryptography library, which is compiled on-the-fly
by pip, you may need to install the development tools for your operating system.

Before you install azure with pip, you should make sure that the required libraries are
installed.

Debian
For Debian and Ubuntu, the following command will ensure that the required dependencies
are installed:

sudo apt-get install build-essential libssl-dev libffi-dev python-dev

Red Hat
For Fedora and RHEL-derivatives, the following command will ensure that the required
dependencies are installed:

sudo yum install gcc libffi-devel python-devel openssl-devel

Configuration
Set up the provider config at /etc/salt/cloud.providers.d/azurearm.conf:

# Note: This example is for /etc/salt/cloud.providers.d/azurearm.conf

my-azurearm-config:
driver: azurearm
master: salt.example.com
subscription_id: 01234567-890a-bcde-f012-34567890abdc

# https://apps.dev.microsoft.com/#/appList
username: <username>@<subdomain>.onmicrosoft.com
password: verybadpass
location: westus
resource_group: my_rg

# Optional
network_resource_group: my_net_rg
cleanup_disks: True
cleanup_vhds: True
cleanup_data_disks: True
cleanup_interfaces: True
custom_data: 'This is custom data'
expire_publisher_cache: 604800 # 7 days
expire_offer_cache: 518400 # 6 days
expire_sku_cache: 432000 # 5 days
expire_version_cache: 345600 # 4 days
expire_group_cache: 14400 # 4 hours
expire_interface_cache: 3600 # 1 hour
expire_network_cache: 3600 # 1 hour

Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles:

azure-ubuntu:
provider: my-azure-config
image: Canonical|UbuntuServer|14.04.5-LTS|14.04.201612050
size: Standard_D1_v2
location: eastus
ssh_username: azureuser
ssh_password: verybadpass

azure-win2012:
provider: my-azure-config
image: MicrosoftWindowsServer|WindowsServer|2012-R2-Datacenter|latest
size: Standard_D1_v2
location: westus
win_username: azureuser
win_password: verybadpass

These options are described in more detail below. Once configured, the profile can be
realized with a salt command:

salt-cloud -p azure-ubuntu newinstance

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:

salt newinstance test.ping

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:

salt-cloud --list-images my-azure-config

As you will see in --list-images, image names are comprised of the following fields,
separated by the pipe (|) character:

publisher: For example, Canonical or MicrosoftWindowsServer
offer: For example, UbuntuServer or WindowsServer
sku: Such as 14.04.5-LTS or 2012-R2-Datacenter
version: Such as 14.04.201612050 or latest

It is possible to specify the URL of a custom image that you have access to, such as:

https://<mystorage>.blob.core.windows.net/system/Microsoft.Compute/Images/<mystorage>/template-osDisk.01234567-890a-bcdef0123-4567890abcde.vhd

size
Required. The name of the size to use to create a VM. Available sizes can be viewed using
the following command:

salt-cloud --list-sizes my-azure-config

location
Required. The name of the location to create a VM in. Available locations can be viewed
using the following command:

salt-cloud --list-locations my-azure-config

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.

win_installer
Required for Windows. The path to the Salt installer to be uploaded.

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.

network
Required. The virtual network that the VM will be spun up in.

subnet
Optional. The subnet inside the virtual network that the VM will be spun up in. Default
is default.

iface_name
Optional. The name to apply to the VM's network interface. If not supplied, the value will
be set to <VM name>-iface0.

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.

userdata
Optional. 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. This will be
ignored if the userdata_file is specified.

userdata_file
Optional. The path to a file to be read and submitted to Azure as user data. How this is
used depends on the operating system that is being deployed. If used, any userdata setting
will be ignored.

wait_for_ip_timeout
Optional. Default is 600. When waiting for a VM to be created, Salt Cloud will attempt to
connect to the VM's IP address until it starts responding. This setting specifies the
maximum time to wait for a response.

wait_for_ip_interval
Optional. Default is 10. How long to wait between attempts to connect to the VM's IP.

wait_for_ip_interval_multiplier
Optional. Default is 1. Increase the interval by this multiplier after each request; helps
with throttling.

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 518400. See expire_publisher_cache for details on why this exists.

By default, the offer data will be cached, and only updated every 518400 seconds (6 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 432000. See expire_publisher_cache for details on why this exists.

By default, the sku data will be cached, and only updated every 432000 seconds (5 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 345600. See expire_publisher_cache for details on why this exists.

By default, the version data will be cached, and only updated every 345600 seconds (4
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 14400. See expire_publisher_cache for details on why this exists.

By default, the resource group data will be cached, and only updated every 14400 seconds
(4 hours). 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.

Other Options
Other options relevant to Azure ARM.

storage_account
Required for actions involving an Azure storage account.

storage_key
Required for actions involving an Azure storage account.

salt-cloud -a show_instance myinstance

Getting Started with CloudStack
CloudStack 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 CloudStack instances.

Dependencies
• Libcloud >= 0.13.2

Configuration
Using Salt for CloudStack, requires an API key and a secret key along with the API address
endpoint information.

# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

exoscale:
driver: cloudstack
host: api.exoscale.ch
path: /compute
apikey: EXOAPIKEY
secretkey: EXOSECRETKEYINYOURACCOUNT

NOTE:
Changed in version 2015.8.0.

Profiles
Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles or in the
/etc/salt/cloud.profiles.d/ directory:

exoscale-ubuntu:
provider: exoscale-config
image: Ubuntu 16.04
size: Small
location: ch-gva-2

Locations can be obtained using the --list-locations option for the salt-cloud command:

# salt-cloud --list-locations exoscale-config
exoscale:
----------
cloudstack:
----------
ch-dk-2:
----------
country:
Unknown
driver:
id:
91e5e9e4-c9ed-4b76-bee4-427004b3baf9
name:
ch-dk-2
ch-gva-2:
----------
country:
Unknown
driver:
id:
1128bd56-b4d9-4ac6-a7b9-c715b187ce11
name:
ch-gva-2

Sizes can be obtained using the --list-sizes option for the salt-cloud command:

# salt-cloud --list-sizes exoscale
exoscale:
----------
cloudstack:
----------
Extra-large:
----------
bandwidth:
0
disk:
0
driver:
extra:
----------
cpu:
4
get_uuid:
id:
350dc5ea-fe6d-42ba-b6c0-efb8b75617ad
name:
Extra-large
price:
0
ram:
16384
uuid:
edb4cd4ae14bbf152d451b30c4b417ab095a5bfe
...SNIP...

Images can be obtained using the --list-images option for the salt-cloud command:

# salt-cloud --list-images exoscale
exoscale:
----------
cloudstack:
----------
Linux CentOS 6.6 64-bit:
----------
driver:
extra:
----------
displaytext:
Linux CentOS 6.6 64-bit 10G Disk (2014-12-01-bac8e0)
format:
QCOW2
hypervisor:
KVM
os:
Other PV (64-bit)
size:
10737418240
get_uuid:
id:
aa69ae64-1ea9-40af-8824-c2c3344e8d7c
name:
Linux CentOS 6.6 64-bit
uuid:
f26b4f54ec8591abdb6b5feb3b58f720aa438fee
...SNIP...

CloudStack specific settings
security_group
New in version next-release.

You can specifiy a list of security groups (by name or id) that should be assigned to the
VM.

exoscale:
provider: cloudstack
security_group:
- default
- salt-master

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: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-digitalocean-config:
driver: digital_ocean
personal_access_token: xxx
ssh_key_file: /path/to/ssh/key/file
ssh_key_names: my-key-name,my-key-name-2
location: New York 1

NOTE:
Changed in version 2015.8.0.

Profiles
Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles or in the
/etc/salt/cloud.profiles.d/ directory:

digitalocean-ubuntu:
provider: my-digitalocean-config
image: 14.04 x64
size: 512MB
location: New York 1
private_networking: True
backups_enabled: True
ipv6: True
create_dns_record: True
userdata_file: /etc/salt/cloud.userdata.d/setup

Locations can be obtained using the --list-locations option for the salt-cloud command:

# salt-cloud --list-locations my-digitalocean-config
my-digitalocean-config:
----------
digital_ocean:
----------
Amsterdam 1:
----------
available:
False
features:
[u'backups']
name:
Amsterdam 1
sizes:
[]
slug:
ams1
...SNIP...

Sizes can be obtained using the --list-sizes option for the salt-cloud command:

# salt-cloud --list-sizes my-digitalocean-config
my-digitalocean-config:
----------
digital_ocean:
----------
512MB:
----------
cost_per_hour:
0.00744
cost_per_month:
5.0
cpu:
1
disk:
20
id:
66
memory:
512
name:
512MB
slug:
None
...SNIP...

Images can be obtained using the --list-images option for the salt-cloud command:

# salt-cloud --list-images my-digitalocean-config
my-digitalocean-config:
----------
digital_ocean:
----------
10.1:
----------
created_at:
2015-01-20T20:04:34Z
distribution:
FreeBSD
id:
10144573
min_disk_size:
20
name:
10.1
public:
True
...SNIP...

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.

digitalocean-freebsd:
provider: my-digitalocean-config
image: 10.2
size: 512MB
ssh_username: freebsd

userdata_file
New in version 2016.11.6.

Use userdata_file to specify the userdata file to upload for use with cloud-init if
available.

my-openstack-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/cloud-init/packages.yml

my-do-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/cloud-init/packages.yml
userdata_template: jinja

If no userdata_template is set in the cloud profile, then the master configuration will be
checked for a userdata_template value. If this is not set, then no templating will be
performed on the userdata_file.

To disable templating in a cloud profile when a userdata_template has been set in the
master configuration file, simply set userdata_template to False in the cloud profile:

my-do-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/cloud-init/packages.yml
userdata_template: False

Miscellaneous Information
NOTE:
DigitalOcean's concept of Applications is nothing more than a pre-configured instance
(same as a normal Droplet). You will find examples such Docker 0.7 Ubuntu 13.04 x64 and
Wordpress on Ubuntu 12.10 when using the --list-images option. These names can be used
just like the rest of the standard instances when specifying an image in the cloud
profile configuration.

NOTE:
If your domain's DNS is managed with DigitalOcean, and your minion name matches your
DigitalOcean managed DNS domain, you can automatically create A and AAA records for
newly created droplets. Use create_dns_record: True in your config to enable this.
Adding delete_dns_record: True to also delete records when a droplet is destroyed is
optional. Due to limitations in salt-cloud design, the destroy code does not have
access to the VM config data. WHETHER YOU ADD create_dns_record: True OR NOT,
salt-cloud WILL attempt to delete your DNS records if the minion name matches. This
will prevent advertising any recycled IP addresses for destroyed minions.

NOTE:
If you need to perform the bootstrap using the local interface for droplets, this can
be done by setting ssh_interface: private in your config. By default the salt-cloud
script would run on the public interface however if firewall is preventing the
connection to the Droplet over the public interface you might need to set this option
to connect via private interface. Also, to use this feature private_networking: True
must be set in the config.

NOTE:
Additional documentation is available from DigitalOcean.

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

• user_id - Your Dimension Data Cloud username

• key - Your Dimension Data Cloud password

• region - The region key, one of the possible region keys

Possible regions:

• dd-na : Dimension Data North America (USA)

• dd-eu : Dimension Data Europe

• dd-af : Dimension Data Africa

• dd-au : Dimension Data Australia

• dd-latam : Dimension Data Latin America

• dd-ap : Dimension Data Asia Pacific

• dd-canada : Dimension Data Canada region

# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-dimensiondata-config:
user_id: my_username
key: myPassword!
region: dd-na
driver: dimensiondata

NOTE:
Changed in version 2015.8.0.

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:

# salt-cloud --list-images my-dimensiondata-config
my-dimensiondata-config:
----------
dimensiondata:
----------
CSfM SharePoint 2013 Trial:
----------
driver:
extra:
----------
OS_displayName:
WIN2012R2S/64
OS_type:
None
cpu:
created:
2015-03-19T18:36:06.000Z
description:
Windows 2012 R2 Standard 64-bit installed with SharePoint 2013 and Visual Studio 2013 Pro (Trial Version)
location:
memoryGb:
12
osImageKey:
T-WIN-2012R2-STD-SP2013-VS2013-64-4-12-100
get_uuid:
id:
0df4677e-d380-4e9b-9469-b529ee0214c5
name:
CSfM SharePoint 2013 Trial
uuid:
28c077f1be970ee904541407b377e3ff87a9ac69
CentOS 5 32-bit 2 CPU:
----------
driver:
extra:
----------
OS_displayName:
CENTOS5/32
OS_type:
None
cpu:
created:
2015-10-21T14:52:29.000Z
description:
CentOS Release 5.11 32-bit
location:
memoryGb:
4
osImageKey:
T-CENT-5-32-2-4-10
get_uuid:
id:
a8046bd1-04ea-4668-bf32-bf8d5540faed
name:
CentOS 5 32-bit 2 CPU
uuid:
4d7dd59929fed6f4228db861b609da64997773a7

...SNIP...

Locations can be obtained using the --list-locations option for the salt-cloud command:

my-dimensiondata-config:
----------
dimensiondata:
----------
Australia - Melbourne:
----------
country:
Australia
driver:
id:
AU2
name:
Australia - Melbourne
Australia - Melbourne MCP2:
----------
country:
Australia
driver:
id:
AU10
name:
Australia - Melbourne MCP2
Australia - Sydney:
----------
country:
Australia
driver:
id:
AU1
name:
Australia - Sydney
Australia - Sydney MCP2:
----------
country:
Australia
driver:
id:
AU9
name:
Australia - Sydney MCP2
New Zealand:
----------
country:
New Zealand
driver:
id:
AU8
name:
New Zealand
New_Zealand:
----------
country:
New Zealand
driver:
id:
AU11
name:
New_Zealand

NOTE:
Dimension Data Cloud REST API documentation is available from Dimension Data MCP 2.

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: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-ec2-southeast-public-ips:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com

# Set up grains information, which will be common for all nodes
# using this provider
grains:
node_type: broker
release: 1.0.1

# Specify whether to use public or private IP for deploy script.
#
# Valid options are:
# private_ips - The salt-cloud command is run inside the EC2
# public_ips - The salt-cloud command is run outside of EC2
#
ssh_interface: public_ips

# Optionally configure the Windows credential validation number of
# retries and delay between retries. This defaults to 10 retries
# with a one second delay betwee retries
win_deploy_auth_retries: 10
win_deploy_auth_retry_delay: 1

# Set the EC2 access credentials (see below)
#
id: 'use-instance-role-credentials'
key: 'use-instance-role-credentials'

# Make sure this key is owned by root with permissions 0400.
#
private_key: /etc/salt/my_test_key.pem
keyname: my_test_key
securitygroup: default

# Optionally configure default region
# Use salt-cloud --list-locations <provider> to obtain valid regions
#
location: ap-southeast-1
availability_zone: ap-southeast-1b

# Configure which user to use to run the deploy script. This setting is
# dependent upon the AMI that is used to deploy. It is usually safer to
# configure this individually in a profile, than globally. Typical users
# are:
#
# Amazon Linux -> ec2-user
# RHEL -> ec2-user
# CentOS -> ec2-user
# Ubuntu -> ubuntu
# Debian -> admin
#
ssh_username: ec2-user

# Optionally add an IAM profile
iam_profile: 'arn:aws:iam::123456789012:instance-profile/ExampleInstanceProfile'

driver: ec2

my-ec2-southeast-private-ips:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com

# Specify whether to use public or private IP for deploy script.
#
# Valid options are:
# private_ips - The salt-master is also hosted with EC2
# public_ips - The salt-master is hosted outside of EC2
#
ssh_interface: private_ips

# Set the EC2 access credentials (see below)
#
id: 'use-instance-role-credentials'
key: 'use-instance-role-credentials'

# Make sure this key is owned by root with permissions 0400.
#
private_key: /etc/salt/my_test_key.pem
keyname: my_test_key

# This one should NOT be specified if VPC was not configured in AWS to be
# the default. It might cause an error message which says that network
# interfaces and an instance-level security groups may not be specified
# on the same request.
#
securitygroup: default

# Optionally configure default region
#
location: ap-southeast-1
availability_zone: ap-southeast-1b

# Optionally add an IAM profile
iam_profile: 'my other profile name'

driver: ec2

NOTE:
Changed in version 2015.8.0.

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:

1. Configure an IAM Role from the IAM Management Console.

2. Attach this role to a new profile. It can be done with the AWS CLI:

> aws iam create-instance-profile --instance-profile-name PROFILE_NAME
> aws iam add-role-to-instance-profile --instance-profile-name PROFILE_NAME --role-name ROLE_NAME

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:

base_ec2_private:
provider: my-ec2-southeast-private-ips
image: ami-e565ba8c
size: t2.micro
ssh_username: ec2-user

base_ec2_public:
provider: my-ec2-southeast-public-ips
image: ami-e565ba8c
size: t2.micro
ssh_username: ec2-user

base_ec2_db:
provider: my-ec2-southeast-public-ips
image: ami-e565ba8c
size: m1.xlarge
ssh_username: ec2-user
volumes:
- { size: 10, device: /dev/sdf }
- { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
- { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
- { size: 10, device: /dev/sdi, tags: {"Environment": "production"} }
# optionally add tags to profile:
tag: {'Environment': 'production', 'Role': 'database'}
# force grains to sync after install
sync_after_install: grains

base_ec2_vpc:
provider: my-ec2-southeast-public-ips
image: ami-a73264ce
size: m1.xlarge
ssh_username: ec2-user
script: /etc/salt/cloud.deploy.d/user_data.sh
network_interfaces:
- DeviceIndex: 0
PrivateIpAddresses:
- Primary: True
#auto assign public ip (not EIP)
AssociatePublicIpAddress: True
SubnetId: subnet-813d4bbf
SecurityGroupId:
- sg-750af413
del_root_vol_on_destroy: True
del_all_vol_on_destroy: True
volumes:
- { size: 10, device: /dev/sdf }
- { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
- { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
tag: {'Environment': 'production', 'Role': 'database'}
sync_after_install: grains

The profile can now be realized with a salt command:

# salt-cloud -p base_ec2 ami.example.com
# salt-cloud -p base_ec2_public ami.example.com
# salt-cloud -p base_ec2_private ami.example.com

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:

# salt 'ami.example.com' test.ping

Required Settings
The following settings are always required for EC2:

# Set the EC2 login data
my-ec2-config:
id: HJGRYCILJLKJYG
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
keyname: test
securitygroup: quick-start
private_key: /root/test.pem
driver: 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.

my-ec2-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/my-userdata-file

my-ec2-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/my-userdata-file
userdata_template: jinja

To disable templating in a cloud profile when a userdata_template has been set in the
master configuration file, simply set userdata_template to False in the cloud profile:

my-ec2-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/my-userdata-file
userdata_template: False

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.

my-ec2-config:
# Optionally configure default region
location: ap-southeast-1
availability_zone: ap-southeast-1b

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.

my-ec2-config:
# Specify whether to use public or private IP for deploy script
# private_ips or public_ips
ssh_interface: public_ips

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

my-ec2-config:
# Configure which user to use to run the deploy script
ssh_username: ec2-user

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:

my-ec2-config:
ssh_username:
- ec2-user
- ubuntu
- admin
- bitnami

Multiple security groups can also be specified in the same fashion:

my-ec2-config:
securitygroup:
- default
- extra

EC2 instances can be added to an AWS Placement Group by specifying the placementgroup
option:

my-ec2-config:
placementgroup: my-aws-placement-group

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.

my-ec2-config:
spot_config:
spot_price: 0.10

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:

• wait_for_spot_timeout: seconds to wait before giving up on spot instance launch
(default=600)

• wait_for_spot_interval: seconds to wait in between polling requests to determine if a
spot instance is available (default=30)

• wait_for_spot_interval_multiplier: a multiplier to add to the interval in between
requests, which is useful if AWS is throttling your requests (default=1)

• wait_for_spot_max_failures: maximum number of failures before giving up on launching
your spot instance (default=10)

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.

wait_for_spot_interval: 1
wait_for_spot_interval_multiplier: 2

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.

my-ec2-config:
block_device_mappings:
- DeviceName: /dev/sdb
VirtualName: ephemeral0
- DeviceName: /dev/sdc
VirtualName: ephemeral1

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.

my-ec2-config:
block_device_mappings:
- DeviceName: /dev/sda
Ebs.VolumeSize: 100
Ebs.VolumeType: gp2
Ebs.SnapshotId: dummy0
- DeviceName: /dev/sdb
# required for devices > 2TB
Ebs.VolumeType: gp2
Ebs.VolumeSize: 3001

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.

device: /dev/xvdj
volume_id: vol-12345abcd

Or, to create a volume from an EBS snapshot, use the snapshot parameter.

device: /dev/xvdj
snapshot: snap-abcd12345

Note that volume_id will take precedence over the snapshot parameter.

Tags can be set once an instance has been launched.

my-ec2-config:
tag:
tag0: value
tag1: value

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.

my-ec2-config:
# Optionally install a Salt Master in addition to the Salt Minion
make_master: True

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.

my-ec2-config:
# Optionally set the IP configuration to private_ips
salt_interface: 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:

salt-cloud -a get_tags mymachine
salt-cloud -a set_tags mymachine tag1=somestuff tag2='Other stuff'
salt-cloud -a del_tags mymachine tag1,tag2,tag3

It is possible to manage tags on any resource in EC2 with a Resource ID, not just
instances:

salt-cloud -f get_tags my_ec2 resource_id=af5467ba
salt-cloud -f set_tags my_ec2 resource_id=af5467ba tag1=somestuff
salt-cloud -f del_tags my_ec2 resource_id=af5467ba tag1,tag2,tag3

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.

salt-cloud -a rename mymachine newname=yourmachine

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:

myinstance-DEL20f5b8ad4eb64ed88f2c428df80a1a0c

In order to enable this, add rename_on_destroy line to the main configuration file:

my-ec2-config:
rename_on_destroy: True

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:

salt-cloud --list-images my-ec2-config

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:

owner: aws-marketplace

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:

salt-cloud -f avail_images my-ec2-config owner=aws-marketplace

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.

• Arch Linux

• FreeBSD

• Fedora

• CentOS

• Ubuntu

• Debian

• OmniOS

• All Images on Amazon

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.

$ salt-cloud -f show_image ec2 image=ami-fd20ad94

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.

$ salt-cloud -a show_instance myinstance

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

ebs_optimized: True

This can also be set as a cloud provider setting in the EC2 cloud configuration:

my-ec2-config:
ebs_optimized: True

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

del_root_vol_on_destroy: True

This can also be set as a cloud provider setting in the EC2 cloud configuration:

my-ec2-config:
del_root_vol_on_destroy: True

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

del_all_vols_on_destroy: True

This can also be set as a cloud provider setting in the EC2 cloud configuration:

my-ec2-config:
del_all_vols_on_destroy: True

The setting for this may be changed on all volumes of an existing instance using one of
the following commands:

salt-cloud -a delvol_on_destroy myinstance
salt-cloud -a keepvol_on_destroy myinstance
salt-cloud -a show_delvol_on_destroy myinstance

The setting for this may be changed on a volume on an existing instance using one of the
following commands:

salt-cloud -a delvol_on_destroy myinstance device=/dev/sda1
salt-cloud -a delvol_on_destroy myinstance volume_id=vol-1a2b3c4d
salt-cloud -a keepvol_on_destroy myinstance device=/dev/sda1
salt-cloud -a keepvol_on_destroy myinstance volume_id=vol-1a2b3c4d
salt-cloud -a show_delvol_on_destroy myinstance device=/dev/sda1
salt-cloud -a show_delvol_on_destroy myinstance volume_id=vol-1a2b3c4d

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.

salt-cloud -a show_term_protect mymachine
salt-cloud -a enable_term_protect mymachine
salt-cloud -a disable_term_protect mymachine

Alternate Endpoint
Normally, EC2 endpoints are build using the region and the service_url. The resulting
endpoint would follow this pattern:

ec2.<region>.<service_url>

This results in an endpoint that looks like:

ec2.us-east-1.amazonaws.com

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:

my-ec2-config:
endpoint: myendpoint.example.com:1138/services/Cloud

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

• type: choose between standard (magnetic disk), gp2 (SSD), or io1 (provisioned IOPS).
(default=standard)

• iops: the number of IOPS (only applicable to io1 volumes) (default varies on volume
size)

• encrypted: enable encryption on the volume (default=false)

salt-cloud -f create_volume ec2 zone=us-east-1b
salt-cloud -f create_volume ec2 zone=us-east-1b size=10
salt-cloud -f create_volume ec2 zone=us-east-1b snapshot=snap12345678
salt-cloud -f create_volume ec2 size=10 type=standard
salt-cloud -f create_volume ec2 size=10 type=gp2
salt-cloud -f create_volume ec2 size=10 type=io1 iops=1000

Attaching Volumes
Unattached volumes may be attached to an instance. The following values are required; name
or instance_id, volume_id, and device.

salt-cloud -a attach_volume myinstance volume_id=vol-12345 device=/dev/sdb1

Show a Volume
The details about an existing volume may be retrieved.

salt-cloud -a show_volume myinstance volume_id=vol-12345
salt-cloud -f show_volume ec2 volume_id=vol-12345

Detaching Volumes
An existing volume may be detached from an instance.

salt-cloud -a detach_volume myinstance volume_id=vol-12345

Deleting Volumes
A volume that is not attached to an instance may be deleted.

salt-cloud -f delete_volume ec2 volume_id=vol-12345

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.

salt-cloud -f create_keypair ec2 keyname=mykeypair

Importing a Key Pair
salt-cloud -f import_keypair ec2 keyname=mykeypair file=/path/to/id_rsa.pub

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

salt-cloud -f show_keypair ec2 keyname=mykeypair

Delete a Key Pair
This function removes the key pair from Amazon.

salt-cloud -f delete_keypair ec2 keyname=mykeypair

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

profile-id:
provider: provider-name
subnetid: subnet-XXXXXXXX
image: ami-XXXXXXXX
size: m1.medium
ssh_username: ubuntu
securitygroupid:
- sg-XXXXXXXX
securitygroupname:
- AnotherSecurityGroup
- AndThirdSecurityGroup

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

profile-id:
provider: provider-name
image: ami-XXXXXXXX
size: m1.medium
ssh_username: ubuntu

# Do not include either 'subnetid', 'subnetname', 'securitygroupid' or
# 'securitygroupname' here if you are going to manually specify
# interface configuration
#
network_interfaces:
- DeviceIndex: 0
SubnetId: subnet-XXXXXXXX
SecurityGroupId:
- sg-XXXXXXXX

# Uncomment this line if you would like to set an explicit private
# IP address for the ec2 instance
#
# PrivateIpAddress: 192.168.1.66

# Uncomment this to associate an existing Elastic IP Address with
# this network interface:
#
# associate_eip: eipalloc-XXXXXXXX

# You can allocate more than one IP address to an interface. Use the
# 'ip addr list' command to see them.
#
# SecondaryPrivateIpAddressCount: 2

# Uncomment this to allocate a new Elastic IP Address to this
# interface (will be associated with the primary private ip address
# of the interface
#
# allocate_new_eip: True

# Uncomment this instead to allocate a new Elastic IP Address to
# both the primary private ip address and each of the secondary ones
#
allocate_new_eips: True

# Uncomment this if you're creating NAT instances. Allows an instance
# to accept IP packets with destinations other than itself.
# SourceDestCheck: False

- DeviceIndex: 1
subnetname: XXXXXXXX-Subnet
securitygroupname:
- XXXXXXXX-SecurityGroup
- YYYYYYYY-SecurityGroup

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: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-gogrid-config:
driver: gogrid
apikey: asdff7896asdh789
sharedsecret: saltybacon

NOTE:
A Note about using Map files with GoGrid:

Due to limitations in the GoGrid API, instances cannot be provisioned in parallel with
the GoGrid driver. Map files will work with GoGrid, but the -P argument should not be
used on maps referencing GoGrid instances.

NOTE:
Changed in version 2015.8.0.

Profiles
Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles or in the
/etc/salt/cloud.profiles.d/ directory:

gogrid_512:
provider: my-gogrid-config
size: 512MB
image: CentOS 6.2 (64-bit) w/ None

Sizes can be obtained using the --list-sizes option for the salt-cloud command:

# salt-cloud --list-sizes my-gogrid-config
my-gogrid-config:
----------
gogrid:
----------
512MB:
----------
bandwidth:
None
disk:
30
driver:
get_uuid:
id:
512MB
name:
512MB
price:
0.095
ram:
512
uuid:
bde1e4d7c3a643536e42a35142c7caac34b060e9
...SNIP...

Images can be obtained using the --list-images option for the salt-cloud command:

# salt-cloud --list-images my-gogrid-config
my-gogrid-config:
----------
gogrid:
----------
CentOS 6.4 (64-bit) w/ None:
----------
driver:
extra:
----------
get_uuid:
id:
18094
name:
CentOS 6.4 (64-bit) w/ None
uuid:
bfd4055389919e01aa6261828a96cf54c8dcc2c4
...SNIP...

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.

gogrid_512:
provider: my-gogrid-config
size: 512MB
image: CentOS 6.2 (64-bit) w/ None
assign_public_ip: 11.38.257.42

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
• LibCloud >= 1.0.0

Changed in version 2017.7.0.

• A Google Cloud Platform account with Compute Engine enabled

• A registered Service Account for authorization

• Oh, and obviously you'll need salt

Google Compute Engine Setup
1. Sign up for Google Cloud Platform

Go to https://cloud.google.com and use your Google account to sign up for Google Cloud
Platform and complete the guided instructions.

2. Create a Project

Next, go to the console at https://cloud.google.com/console and create a new Project.
Make sure to select your new Project if you are not automatically directed to the
Project.

Projects are a way of grouping together related users, services, and billing. You may
opt to create multiple Projects and the remaining instructions will need to be
completed for each Project if you wish to use GCE and Salt Cloud to manage your virtual
machines.

3. Enable the Google Compute Engine service

In your Project, either just click Compute Engine to the left, or go to the APIs & auth
section and APIs link and enable the Google Compute Engine service.

4. Create a Service Account

To set up authorization, navigate to APIs & auth section and then the Credentials link
and click the CREATE NEW CLIENT ID button. Select Service Account and click the Create
Client ID button. This will automatically download a .json file, which may or may not
be used in later steps, depending on your version of libcloud.

Look for a new Service Account section in the page and record the generated email
address for the matching key/fingerprint. The email address will be used in the
service_account_email_address of the /etc/salt/cloud.providers or the
/etc/salt/cloud.providers.d/*.conf file.

5. Key Format

NOTE:
If you are using libcloud >= 0.17.0 it is recommended that you use the JSON format
file you downloaded above and skip to the Provider Configuration section below,
using the JSON file in place of 'NEW.pem' in the documentation.

If you are using an older version of libcloud or are unsure of the version you have,
please follow the instructions below to generate and format a new P12 key.

In the new Service Account section, click Generate new P12 key, which will
automatically download a .p12 private key file. The .p12 private key needs to be
converted to a format compatible with libcloud. This new Google-generated private key
was encrypted using notasecret as a passphrase. Use the following command and record
the location of the converted private key and record the location for use in the
service_account_private_key of the /etc/salt/cloud file:

openssl pkcs12 -in ORIG.p12 -passin pass:notasecret \
-nodes -nocerts | openssl rsa -out NEW.pem

Provider Configuration
Set up the provider cloud config at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/*.conf:

gce-config:
# Set up the Project name and Service Account authorization
project: "your-project-id"
service_account_email_address: "123-a5gt@developer.gserviceaccount.com"
service_account_private_key: "/path/to/your/NEW.pem"

# Set up the location of the salt master
minion:
master: saltmaster.example.com

# Set up grains information, which will be common for all nodes
# using this provider
grains:
node_type: broker
release: 1.0.1

driver: gce

NOTE:
The value provided for project must not contain underscores or spaces and is labeled as
"Project ID" on the Google Developers Console.

NOTE:
Changed in version 2015.8.0.

Profile Configuration
Set up an initial profile at /etc/salt/cloud.profiles or
/etc/salt/cloud.profiles.d/*.conf:

my-gce-profile:
image: centos-6
size: n1-standard-1
location: europe-west1-b
network: default
subnetwork: default
tags: '["one", "two", "three"]'
metadata: '{"one": "1", "2": "two"}'
use_persistent_disk: True
delete_boot_pd: False
deploy: True
make_master: False
provider: gce-config

The profile can be realized now with a salt command:

salt-cloud -p my-gce-profile gce-instance

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:

salt gce-instance test.ping

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.

subnetwork
Use this setting to define the subnetwork an instance will be created in. This requires
that the network your instance is created under has a mode of 'custom' or 'auto'.
Additionally, the subnetwork your instance is created under is associated with the
location you provide.

New in version 2017.7.0.

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:

• private_ips: The salt-master is also hosted with GCE

• public_ips: The salt-master is hosted outside of GCE

external_ip
Per instance setting: Used a named fixed IP address to this host.

Valid options are:

• ephemeral: The host will use a GCE ephemeral IP

• None: No external IP will be configured on this host.

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.

my-gce-profile:
image: centos-6
ssh_username: salt
size: f1-micro
location: us-central1-a
network: default
subnetwork: default
tags: '["one", "two", "three"]'
metadata: '{"one": "1", "2": "two",
"sshKeys": ""}'
use_persistent_disk: True
delete_boot_pd: False
deploy: False
make_master: False
provider: gce-config
ex_service_accounts:
- scopes:
- bigquery

Email can also be specified as an (optional) parameter.

my-gce-profile:
...snip
ex_service_accounts:
- scopes:
- bigquery
email: default

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:

my-gce-profile:
...

# SSH to GCE instances as gceuser
ssh_username: gceuser

# Use the local private SSH key file located here
ssh_keyfile: /etc/cloud/google_compute_engine

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:

my-gce-profile:
...

metadata: '{"one": "1", "2": "two",
"sshKeys": "gceuser:ssh-rsa <Your SSH Public Key> gceuser@host"}'

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.

salt-cloud -a show_instance myinstance

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.

salt-cloud --list-locations gce
salt-cloud --list-sizes gce
salt-cloud --list-images gce

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

salt-cloud -f create_disk gce disk_name=pd location=us-central1-b size=200

Delete
Deleting a disk only requires the name of the disk to delete

salt-cloud -f delete_disk gce disk_name=old-backup

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

salt-cloud -a attach_disk myinstance disk_name=pd mode=READ_WRITE boot=yes

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.

salt-cloud -a detach_disk myinstance disk_name=pd

Show disk
It's also possible to look up the details for an existing disk with either a function or
an action.

salt-cloud -a show_disk myinstance disk_name=pd
salt-cloud -f show_disk gce disk_name=pd

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.

salt-cloud -f create_snapshot gce name=backup-20140226 disk_name=pd

Delete snapshot
You can delete a snapshot when it's no longer needed by specifying the name of the
snapshot.

salt-cloud -f delete_snapshot gce name=backup-20140226

Show snapshot
Use this function to look up information about the snapshot.

salt-cloud -f show_snapshot gce name=backup-20140226

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 if they don't have a 'mode'. Optionally,
'mode' can be provided. Supported modes are 'auto', 'custom', 'legacy'. Optionally,
'description' can be provided to add an extra note to your network. 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.

salt-cloud -f create_network gce name=mynet cidr=10.10.10.0/24
salt-cloud -f create_network gce name=mynet mode=auto description=some optional info.

Changed in version 2017.7.0.

Destroy network
Destroy a network by specifying the name. If a resource is currently using the target
network an exception will be raised.

salt-cloud -f delete_network gce name=mynet

Show network
Specify the network name to view information about the network.

salt-cloud -f show_network gce name=mynet

Create subnetwork
New subnetworks require a name, region, and CIDR range. Optionally, 'description' can be
provided to add an extra note to your subnetwork. New instances can be created and added
to this subnetwork by setting the subnetwork name during create. It is not possible to
add/remove existing instances to a subnetwork.

salt-cloud -f create_subnetwork gce name=mynet network=mynet region=us-central1 cidr=10.0.10.0/24
salt-cloud -f create_subnetwork gce name=mynet network=mynet region=us-central1 cidr=10.10.10.0/24 description=some info about my subnet.

New in version 2017.7.0.

Destroy subnetwork
Destroy a subnetwork by specifying the name and region. If a resource is currently using
the target subnetwork an exception will be raised.

salt-cloud -f delete_subnetwork gce name=mynet region=us-central1

New in version 2017.7.0.

Show subnetwork
Specify the subnetwork name to view information about the subnetwork.

salt-cloud -f show_subnetwork gce name=mynet

New in version 2017.7.0.

Create address
Create a new named static IP address in a region.

salt-cloud -f create_address gce name=my-fixed-ip region=us-central1

Delete address
Delete an existing named fixed IP address.

salt-cloud -f delete_address gce name=my-fixed-ip region=us-central1

Show address
View details on a named address.

salt-cloud -f show_address gce name=my-fixed-ip region=us-central1

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

salt-cloud -f create_fwrule gce name=web allow=tcp:80,tcp:443,icmp

Delete firewall
Deleting a firewall rule will prevent any previously allowed traffic for the named
firewall rule.

salt-cloud -f delete_fwrule gce name=web

Show firewall
Use this function to review an existing firewall rule's information.

salt-cloud -f show_fwrule gce name=web

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.

salt-cloud -f create_hc gce name=myhc path=/ port=80
salt-cloud -f delete_hc gce name=myhc
salt-cloud -f show_hc gce name=myhc

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.

salt-cloud -f create_lb gce name=lb region=... ports=80 members=w1,w2,w3
salt-cloud -f delete_lb gce name=lb
salt-cloud -f show_lb gce name=lb

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.

salt-cloud -f create_lb gce name=my-lb region=us-central1 ports=234 members=s1,s2,s3 address=my-lb-ip

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.

salt-cloud -f attach_lb gce name=lb member=w4
salt-cloud -f detach_lb gce name=lb member=oops

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:

hpcloud-config:
# Set the location of the salt-master
#
minion:
master: saltmaster.example.com

# Configure HP Cloud using the OpenStack plugin
#
identity_url: https://region-b.geo-1.identity.hpcloudsvc.com:35357/v2.0/tokens
compute_name: Compute
protocol: ipv4

# Set the compute region:
#
compute_region: region-b.geo-1

# Configure HP Cloud authentication credentials
#
user: myname
tenant: myname-project1
password: xxxxxxxxx

# keys to allow connection to the instance launched
#
ssh_key_name: yourkey
ssh_key_file: /path/to/key/yourkey.priv

driver: openstack

The subsequent example that follows is using the openstack driver.

NOTE:
Changed in version 2015.8.0.

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:

region-a.geo-1 -> US West
region-b.geo-1 -> US East

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:

hp_ae1_ubuntu:
provider: hp_ae1
image: 9302692b-b787-4b52-a3a6-daebb79cb498
ignore_cidr: 10.0.0.1/24
networks:
- floating: Ext-Net
size: standard.small
ssh_key_file: /root/keys/test.key
ssh_key_name: test
ssh_username: ubuntu

Some important things about the example above:

• The image parameter can use either the image name or image ID which you can obtain by
running in the example below (this case US East):

# salt-cloud --list-images hp_ae1

• The parameter ignore_cidr specifies a range of addresses to ignore when trying to
connect to the instance. In this case, it's the range of IP addresses used for an
private IP of the instance.

• The parameter networks is very important to include. In previous versions of Salt Cloud,
this is what made it possible for salt-cloud to be able to attach a floating IP to the
instance in order to connect to the instance and set up the minion. The current version
of salt-cloud doesn't require it, though having it is of no harm either. Newer versions
of salt-cloud will use this, and without it, will attempt to find a list of floating IP
addresses to use regardless.

• The ssh_key_file and ssh_key_name are the keys that will make it possible to connect to
the instance to set up the minion

• The ssh_username parameter, in this case, being that the image used will be ubuntu, will
make it possible to not only log in but install the minion

Launch an instance
To instantiate a machine based on this profile (example):

# salt-cloud -p hp_ae1_ubuntu ubuntu_instance_1

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:

# salt ubuntu_instance_1 ping

SSH to the instance
Additionally, the instance can be accessed via SSH using the floating IP assigned to it

# ssh ubuntu@<floating ip>

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:

hp_ae1_ubuntu:
provider: hp_ae1
image: 9302692b-b787-4b52-a3a6-daebb79cb498
size: standard.small
ssh_key_file: /root/keys/test.key
ssh_key_name: test
ssh_username: ubuntu
ssh_interface: private_ips

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: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-joyent-config:
driver: joyent
user: fred
password: saltybacon
private_key: /root/mykey.pem
keyname: mykey

NOTE:
Changed in version 2015.8.0.

Profiles
Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles or in the
/etc/salt/cloud.profiles.d/ directory:

joyent_512:
provider: my-joyent-config
size: g4-highcpu-512M
image: ubuntu-16.04

Sizes can be obtained using the --list-sizes option for the salt-cloud command:

# salt-cloud --list-sizes my-joyent-config
my-joyent-config:
----------
joyent:
----------
g4-highcpu-512M:
----------
default:
False
description:
Compute Optimized 512M RAM - 1 vCPU - 10 GB Disk
disk:
10240
group:
Compute Optimized
id:
14aea8fc-d0f8-11e5-bfe4-a7458dbc6c99
lwps:
4000
memory:
512
name:
g4-highcpu-512M
swap:
2048
vcpus:
0
version:
1.0.3
...SNIP...

Images can be obtained using the --list-images option for the salt-cloud command:

# salt-cloud --list-images my-joyent-config
my-joyent-config:
----------
joyent:
----------
base:
----------
description:
A 32-bit SmartOS image with just essential packages
installed. Ideal for users who are comfortabl e with
setting up their own environment and tools.
files:
|_
----------
compression:
gzip
sha1:
b00a77408ddd9aeac85085b68b1cd22a07353956
size:
106918297
homepage:
http://wiki.joyent.com/jpc2/Base+Instance
id:
00aec452-6e81-11e4-8474-ebfec9a1a911
name:
base
os:
smartos
owner:
9dce1460-0c4c-4417-ab8b-25ca478c5a78
public:
True
published_at:
2014-11-17T17:41:46Z
requirements:
----------
state:
active
type:
smartmachine
version:
14.3.0

...SNIP...

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:

api_host_suffix: .api.myhostname.com

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 Libvirt
Libvirt is a toolkit to interact with the virtualization capabilities of recent versions
of Linux (and other OSes). This driver Salt cloud provider is currently geared towards
libvirt with qemu-kvm.

http://www.libvirt.org/

Dependencies
• libvirt >= 1.2.18 (older might work)

Provider Configuration
For every KVM host a provider needs to be set up. The provider currently maps to one
libvirt daemon (e.g. one KVM host).

Set up the provider cloud configuration file at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/*.conf.

# Set up a provider with qemu+ssh protocol
kvm-via-ssh:
driver: libvirt
url: qemu+ssh://user@kvm.company.com/system?socket=/var/run/libvirt/libvirt-sock

# Or connect to a local libvirt instance
local-kvm:
driver: libvirt
url: qemu:///system

Cloud Profiles
Virtual machines get cloned from so called Cloud Profiles. Profiles can be set up at
/etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/*.conf:

• Configure a profile to be used:

centos7:
# points back at provider configuration
provider: local-kvm
base_domain: base-centos7-64
ip_source: ip-learning
ssh_username: root
password: my-very-secret-password
# /tmp is mounted noexec.. do workaround
deploy_command: sh /tmp/.saltcloud/deploy.sh
script_args: -F
# grains to add to the minion
grains:
clones-are-awesome: true
# override minion settings
minion:
master: 192.168.16.1
master_port: 5506

The profile can be realized now with a salt command:

# salt-cloud -p centos7 my-centos7-clone

This will create an instance named my-centos7-clone on the cloud host. Also the minion id
will be set to my-centos7-clone.

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:

# salt my-centos7-clone test.ping

Required Settings
The following settings are always required for libvirt:

centos7:
provider: local-kvm
# the domain to clone
base_domain: base-centos7-64
# how to obtain the IP address of the cloned instance
# ip-learning or qemu-agent
ip_source: ip-learning

The ip_source setting controls how the IP address of the cloned instance is determined.
When using ip-learning the IP is requested from libvirt. This needs a recent libvirt
version and may only work for NAT networks. Another option is to use qemu-agent this
requires that the qemu-agent is installed and configured to run at startup in the base
domain.

Optional Settings
# Username and password
ssh_username: root
password: my-secret-password

# Cloning strategy: full or quick
clone_strategy: quick

The clone_strategy controls how the clone is done. In case of full the disks are copied
creating a standalone clone. If quick is used the disks of the base domain are used as
backing disks for the clone. This results in nearly instantaneous clones at the expense of
slower write performance. The quick strategy has a number of requirements:

• The disks must be of type qcow2

• The base domain must be turned off

• The base domain must not change after creating the clone

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.

my-linode-config:
apikey: 'asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf'
password: 'F00barbaz'
driver: linode

NOTE:
Changed in version 2015.8.0.

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:

linode_1024:
provider: my-linode-config
size: Linode 2048
image: CentOS 7
location: London, England, UK

The profile can be realized now with a salt command:

salt-cloud -p linode_1024 linode-instance

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:

salt linode-instance test.ping

Listing Sizes
Sizes can be obtained using the --list-sizes option for the salt-cloud command:

# salt-cloud --list-sizes my-linode-config
my-linode-config:
----------
linode:
----------
Linode 1024:
----------
AVAIL:
----------
10:
500
2:
500
3:
500
4:
500
6:
500
7:
500
8:
500
9:
500
CORES:
1
DISK:
24
HOURLY:
0.015
LABEL:
Linode 1024
...SNIP...

Listing Images
Images can be obtained using the --list-images option for the salt-cloud command:

# salt-cloud --list-images my-linode-config
my-linode-config:
----------
linode:
----------
Arch Linux 2015.02:
----------
CREATE_DT:
2015-02-20 14:17:16.0
DISTRIBUTIONID:
138
IS64BIT:
1
LABEL:
Arch Linux 2015.02
MINIMAGESIZE:
800
REQUIRESPVOPSKERNEL:
1
...SNIP...

Listing Locations
Locations can be obtained using the --list-locations option for the salt-cloud command:

# salt-cloud --list-locations my-linode-config
my-linode-config:
----------
linode:
----------
Atlanta, GA, USA:
----------
ABBR:
atlanta
DATACENTERID:
4
LOCATION:
Atlanta, GA, USA
...SNIP...

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:

• public_ips: The salt-master is hosted outside of Linode. Default.

• private_ips: The salt-master is also hosted within Linode.

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

salt-cloud -a stop machine_to_clone

To create a new machine based on another machine, add an entry to your linode cloud
profile that looks like this:

li-clone:
provider: my-linode-config
clonefrom: machine_to_clone
script_args: -C -F

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:
Pull Request #733 to the salt-bootstrap repo makes the -F argument non-necessary. Once
that change is released into a stable version of the Bootstrap Script, the -C argument
will be sufficient for the script_args setting.

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:

• Provision and configure a container for networking access

• Use those modules to deploy salt and re-attach to master.

• lxc runner

• lxc module

• seed

Limitations
• You can only act on one minion and one provider at a time.

• Listing images must be targeted to a particular LXC provider (nothing will be outputted
with all)

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:

• Create the LXC container on the desired minion (clone or template)

• Change LXC config options (if any need to be changed)

• Start container

• Change base passwords if any

• Change base DNS configuration if necessary

• Wait for LXC container to be up and ready for ssh

• Test SSH connection and bailout in error

• Upload deploy script and seeds, then re-attach the minion.

Provider configuration
Here is a simple provider configuration:

# Note: This example goes in /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
devhost10-lxc:
target: devhost10
driver: lxc

NOTE:
Changed in version 2015.8.0.

Profile configuration
Please read tutorial-lxc before anything else. And specially tutorial-lxc-profiles.

Here are the options to configure your containers:

target Host minion id to install the lxc Container into

lxc_profile
Name of the profile or inline options for the LXC vm creation/cloning, please
see tutorial-lxc-profiles-container.

network_profile
Name of the profile or inline options for the LXC vm network settings, please
see tutorial-lxc-profiles-network.

nic_opts
Totally optional. Per interface new-style configuration options mappings which
will override any profile default option:

eth0: {'mac': '00:16:3e:01:29:40',
'gateway': None, (default)
'link': 'br0', (default)
'gateway': None, (default)
'netmask': '', (default)
'ip': '22.1.4.25'}}

password
password for root and sysadmin users

dnsservers
List of DNS servers to use. This is optional.

minion minion configuration (see Minion Configuration in Salt Cloud)

bootstrap_delay
specify the time to wait (in seconds) between container creation and salt
bootstrap execution. It is useful to ensure that all essential services have
started before the bootstrap script is executed. By default there's no wait time
between container creation and bootstrap unless you are on systemd where we wait
that the system is no more in starting state.

bootstrap_shell
shell for bootstraping script (default: /bin/sh)

script defaults to salt-boostrap

script_args
arguments which are given to the bootstrap script. the {0} placeholder will be
replaced by the path which contains the minion config and key files, eg:

script_args="-c {0}"

Using profiles:

# Note: This example would go in /etc/salt/cloud.profiles or any file in the
# /etc/salt/cloud.profiles.d/ directory.
devhost10-lxc:
provider: devhost10-lxc
lxc_profile: foo
network_profile: bar
minion:
master: 10.5.0.1
master_port: 4506

Using inline profiles (eg to override the network bridge):

devhost11-lxc:
provider: devhost10-lxc
lxc_profile:
clone_from: foo
network_profile:
etho:
link: lxcbr0
minion:
master: 10.5.0.1
master_port: 4506

Using a lxc template instead of a clone:

devhost11-lxc:
provider: devhost10-lxc
lxc_profile:
template: ubuntu
# options:
# release: trusty
network_profile:
etho:
link: lxcbr0
minion:
master: 10.5.0.1
master_port: 4506

Static ip:

# Note: This example would go in /etc/salt/cloud.profiles or any file in the
# /etc/salt/cloud.profiles.d/ directory.
devhost10-lxc:
provider: devhost10-lxc
nic_opts:
eth0:
ipv4: 10.0.3.9
minion:
master: 10.5.0.1
master_port: 4506

DHCP:

# Note: This example would go in /etc/salt/cloud.profiles or any file in the
# /etc/salt/cloud.profiles.d/ directory.
devhost10-lxc:
provider: devhost10-lxc
minion:
master: 10.5.0.1
master_port: 4506

Driver Support
• Container creation

• Image listing (LXC templates)

• Running container information (IP addresses, etc.)

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.

# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-opennebula-provider:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com

# Define xml_rpc setting which Salt-Cloud uses to connect to the OpenNebula API. Required.
#
xml_rpc: http://localhost:2633/RPC2

# Define the OpenNebula access credentials. This can be the main "oneadmin" user that OpenNebula uses as the
# OpenNebula main admin, or it can be a user defined in the OpenNebula instance. Required.
#
user: oneadmin
password: JHGhgsayu32jsa

# Define the private key location that is used by OpenNebula to access new VMs. This setting is required if
# provisioning new VMs or accessing VMs previously created with the associated public key.
#
private_key: /path/to/private/key

driver: opennebula

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:
The key pair must not have a pass-phrase.

Cloud Profiles
Set up an initial profile at either /etc/salt/cloud.profiles or the
/etc/salt/cloud.profiles.d/ directory.

my-opennebula-profile:
provider: my-opennebula-provider
image: Ubuntu-14.04

The profile can now be realized with a salt command:

salt-cloud -p my-opennebula-profile my-new-vm

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:

salt my-new-vm test.ping

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.

Change Disk Size
You can now change the size of a VM on creation by cloning an image and expanding the
size. You can accomplish this by the following cloud profile settings below.

my-opennebula-profile:
provider: my-opennebula-provider
image: Ubuntu-14.04
disk:
disk0:
disk_type: clone
size: 8096
image: centos7-base-image-v2
disk1:
disk_type: volatile
type: swap
size: 4096
disk2:
disk_type: volatile
size: 4096
type: fs
format: ext3

There are currently two different disk_types a user can use: volatile and clone. Clone
which is required when specifying devices will clone an image in open nebula and will
expand it to the size specified in the profile settings. By default this will clone the
image attached to the template specified in the profile but a user can add the image
argument under the disk definition.

For example the profile below will not use Ubuntu-14.04 for the cloned disk image. It will
use the centos7-base-image image:

my-opennebula-profile:
provider: my-opennebula-provider
image: Ubuntu-14.04
disk:
disk0:
disk_type: clone
size: 8096
image: centos7-base-image

If you want to use the image attached to the template set in the profile you can simply
remove the image argument as show below. The profile below will clone the image
Ubuntu-14.04 and expand the disk to 8GB.:

my-opennebula-profile:
provider: my-opennebula-provider
image: Ubuntu-14.04
disk:
disk0:
disk_type: clone
size: 8096

A user can also currently specify swap or fs disks. Below is an example of this profile
setting:

my-opennebula-profile:
provider: my-opennebula-provider
image: Ubuntu-14.04
disk:
disk0:
disk_type: clone
size: 8096
disk1:
disk_type: volatile
type: swap
size: 4096
disk2:
disk_type: volatile
size: 4096
type: fs
format: ext3

The example above will attach both a swap disk and a ext3 filesystem with a size of 4GB.
To note if you define other disks you have to define the image disk to clone because the
template will write over the entire 'DISK=[]' template definition on creation.

Required Settings
The following settings are always required for OpenNebula:

my-opennebula-config:
xml_rpc: http://localhost:26633/RPC2
user: oneadmin
password: JHGhgsayu32jsa
driver: 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:

my-opennebula-config:
private_key: /path/to/private/key

Listing Images
Images can be queried on OpenNebula by passing the --list-images argument to Salt Cloud:

salt-cloud --list-images opennebula

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:

salt-cloud --list-locations opennebula

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:

# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-opennebula-provider:
[...]
fqdn_base: corp.example.com
[...]

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
• Libcloud >= 0.13.2

Configuration
• Using the new format, set up the cloud configuration at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/openstack.conf:

my-openstack-config:
# Set the location of the salt-master
#
minion:
master: saltmaster.example.com

# Configure the OpenStack driver
#
identity_url: http://identity.youopenstack.com/v2.0/tokens
compute_name: nova
protocol: ipv4

compute_region: RegionOne

# Configure Openstack authentication credentials
#
user: myname
password: 123456
# tenant is the project name
tenant: myproject

driver: openstack

# skip SSL certificate validation (default false)
insecure: false

NOTE:
Changed in version 2015.8.0.

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:

source /path/to/your/rcfile
nova credentials
nova endpoints

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:

openstack_512:
provider: my-openstack-config
size: m1.tiny
image: cirros-0.3.1-x86_64-uec
ssh_key_file: /tmp/test.pem
ssh_key_name: test
ssh_interface: private_ips

The following list explains some of the important properties.

size can be one of the options listed in the output of nova flavor-list.

image can be one of the options listed in the output of nova image-list.

ssh_key_file
The SSH private key that the salt-cloud uses to SSH into the VM after its first
booted in order to execute a command or script. This private key's public key must
be the openstack public key inserted into the authorized_key's file of the VM's
root user account.

ssh_key_name
The name of the openstack SSH public key that is inserted into the authorized_keys
file of the VM's root user account. Prior to using this public key, you must use
openstack commands or the horizon web UI to load that key into the tenant's
account. Note that this openstack tenant must be the one you defined in the cloud
provider.

ssh_interface
This option allows you to create a VM without a public IP. If this option is
omitted and the VM does not have a public IP, then the salt-cloud waits for a
certain period of time and then destroys the VM. With the nova drive, private cloud
networks can be defined here.

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.

change_password: True

userdata_file
Use userdata_file to specify the userdata file to upload for use with cloud-init if
available.

my-openstack-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/cloud-init/packages.yml

NOTE:
As of the 2016.11.4 release, this file can be templated. To use templating, simply
specify a userdata_template option in the cloud profile:

my-openstack-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/cloud-init/packages.yml
userdata_template: jinja

To disable templating in a cloud profile when a userdata_template has been set in the
master configuration file, simply set userdata_template to False in the cloud profile:

my-openstack-config:
# Pass userdata to the instance to be created
userdata_file: /etc/salt/cloud-init/packages.yml
userdata_template: False

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/

• Using the old format, set up the cloud configuration at /etc/salt/cloud:

# Set up the location of the salt master
#
minion:
master: saltmaster.example.com

# Set the PARALLELS access credentials (see below)
#
PARALLELS.user: myuser
PARALLELS.password: badpass

# Set the access URL for your PARALLELS host
#
PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/

• Using the new format, set up the cloud configuration at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/parallels.conf:

my-parallels-config:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com

# Set the PARALLELS access credentials (see below)
#
user: myuser
password: badpass

# Set the access URL for your PARALLELS provider
#
url: https://api.cloud.xmission.com:4465/paci/v1.0/
driver: parallels

NOTE:
Changed in version 2015.8.0.

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:

parallels-ubuntu:
provider: my-parallels-config
image: ubuntu-12.04-x86_64

The profile can be realized now with a salt command:

# salt-cloud -p parallels-ubuntu myubuntu

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:

# salt myubuntu test.ping

Required Settings
The following settings are always required for PARALLELS:

• Using the old cloud configuration format:

PARALLELS.user: myuser
PARALLELS.password: badpass
PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/

• Using the new cloud configuration format:

my-parallels-config:
user: myuser
password: badpass
url: https://api.cloud.xmission.com:4465/paci/v1.0/
driver: 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.

# Description of the instance. Defaults to the instance name.
desc: <instance_name>

# How many CPU cores, and how fast they are (in MHz)
cpu_number: 1
cpu_power: 1000

# How many megabytes of RAM
ram: 256

# Bandwidth available, in kbps
bandwidth: 100

# How many public IPs will be assigned to this instance
ip_num: 1

# Size of the instance disk (in GiB)
disk_size: 10

# Username and password
ssh_username: root
password: <value from PARALLELS.password>

# The name of the image, from ``salt-cloud --list-images parallels``
image: ubuntu-12.04-x86_64

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
• profitbricks >= 3.0.0

Configuration
• Using the new format, set up the cloud configuration at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/profitbricks.conf:

my-profitbricks-config:
driver: profitbricks

# Set the location of the salt-master
#
minion:
master: saltmaster.example.com

# Configure ProfitBricks authentication credentials
#
username: user@domain.com
password: 123456
# datacenter is the UUID of a pre-existing virtual data center.
datacenter: 9e6709a0-6bf9-4bd6-8692-60349c70ce0e
# Connect to public LAN ID 1.
public_lan: 1
ssh_public_key: /path/to/id_rsa.pub
ssh_private_key: /path/to/id_rsa

NOTE:
Changed in version 2015.8.0.

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:

salt-cloud -f list_datacenters my-profitbricks-config

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:

profitbricks_staging
provider: my-profitbricks-config
size: Micro Instance
image: 2f98b678-6e7e-11e5-b680-52540066fee9
cores: 2
ram: 4096
public_lan: 1
private_lan: 2
ssh_public_key: /path/to/id_rsa.pub
ssh_private_key: /path/to/id_rsa
ssh_interface: private_lan

profitbricks_production:
provider: my-profitbricks-config
image: Ubuntu-15.10-server-2016-05-01
disk_type: SSD
disk_size: 40
cores: 8
cpu_family: INTEL_XEON
ram: 32768
public_lan: 1
private_lan: 2
public_firewall_rules:
Allow SSH:
protocol: TCP
source_ip: 1.2.3.4
port_range_start: 22
port_range_end: 22
Allow Ping:
protocol: ICMP
icmp_type: 8
ssh_public_key: /path/to/id_rsa.pub
ssh_private_key: /path/to/id_rsa
ssh_interface: private_lan
volumes:
db_data:
disk_size: 500
db_log:
disk_size: 50
disk_type: HDD
disk_availability_zone: ZONE_3

The following list explains some of the important properties.

size Can be one of the options listed in the output of the following command:

salt-cloud --list-sizes my-profitbricks

image Can be one of the options listed in the output of the following command:

salt-cloud --list-images my-profitbricks

disk_size
This option allows you to override the size of the disk as defined by the size. The
disk size is set in gigabytes (GB).

disk_type
This option allow the disk type to be set to HDD or SSD. The default is HDD.

disk_availability_zone
This option will provision the volume in the specified availability_zone.

cores This option allows you to override the number of CPU cores as defined by the size.

ram This option allows you to override the amount of RAM defined by the size. The
value must be a multiple of 256, e.g. 256, 512, 768, 1024, and so forth.

availability_zone
This options specifies in which availability zone the server should be built. Zones
include ZONE_1 and ZONE_2. The default is AUTO.

public_lan
This option will connect the server to the specified public LAN. If no LAN exists,
then a new public LAN will be created. The value accepts a LAN ID (integer).

public_firewall_rules
This option allows for a list of firewall rules assigned to the public network
interface.

Firewall Rule Name:
protocol: <protocol> (TCP, UDP, ICMP) source_mac: <source-mac> source_ip:
<source-ip> target_ip: <target-ip> port_range_start: <port-range-start>
port_range_end: <port-range-end> icmp_type: <icmp-type> icmp_code:
<icmp-code>

nat This option will enable NAT on the private NIC.

private_lan
This option will connect the server to the specified private LAN. If no LAN exists,
then a new private LAN will be created. The value accepts a LAN ID (integer).

private_firewall_rules
This option allows for a list of firewall rules assigned to the private network
interface.

ssh_private_key
Full path to the SSH private key file.

ssh_public_key
Full path to the SSH public key file.

ssh_interface
This option will use the private LAN IP for node connections (such as bootstrapping
the node) instead of the public LAN IP. The value accepts 'private_lan'.

cpu_family
This option allow the CPU family to be set to AMD_OPTERON or INTEL_XEON. The
default is AMD_OPTERON.

volumes:
This option allows a list of additional volumes by name that will be created and
attached to the server. Each volume requires 'disk_size' and, optionally,
'disk_type'. The default is HDD.

deploy Set to False if Salt should not be installed on the node.

wait_for_timeout
The timeout to wait in seconds for provisioning resources such as servers. The
default wait_for_timeout is 15 minutes.

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
• IPy >= 0.81

• requests >= 2.2.1

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.

• Set up the cloud configuration at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/proxmox.conf:

my-proxmox-config:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com

# Set the PROXMOX access credentials (see below)
#
user: myuser@pve
password: badpass

# Set the access URL for your PROXMOX host
#
url: your.proxmox.host
driver: proxmox

NOTE:
Changed in version 2015.8.0.

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:

• Configure a profile to be used:

proxmox-ubuntu:
provider: my-proxmox-config
image: local:vztmpl/ubuntu-12.04-standard_12.04-1_amd64.tar.gz
technology: lxc

# host needs to be set to the configured name of the proxmox host
# and not the ip address or FQDN of the server
host: myvmhost
ip_address: 192.168.100.155
password: topsecret

The profile can be realized now with a salt command:

# salt-cloud -p proxmox-ubuntu myubuntu

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:

# salt myubuntu test.ping

Required Settings
The following settings are always required for PROXMOX:

• Using the new cloud configuration format:

my-proxmox-config:
driver: proxmox
user: saltcloud@pve
password: xyzzy
url: your.proxmox.host

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.

# Description of the instance.
desc: <instance_name>

# How many CPU cores, and how fast they are (in MHz)
cpus: 1
cpuunits: 1000

# How many megabytes of RAM
memory: 256

# How much swap space in MB
swap: 256

# Whether to auto boot the vm after the host reboots
onboot: 1

# Size of the instance disk (in GiB)
disk: 10

# Host to create this vm on
host: myvmhost

# Nameservers. Defaults to host
nameserver: 8.8.8.8 8.8.4.4

# Username and password
ssh_username: root
password: <value from PROXMOX.password>

# The name of the image, from ``salt-cloud --list-images proxmox``
image: local:vztmpl/ubuntu-12.04-standard_12.04-1_amd64.tar.gz

# Whether or not to verify the SSL cert on the Proxmox host
verify_ssl: False

# Network interfaces, netX
net0: name=eth0,bridge=vmbr0,ip=dhcp

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

proxmox-win7:
# Image of the new VM
image: image.iso # You can get all your available images using 'salt-cloud --list-images provider_name' (Ex: 'salt-cloud --list-images my-proxmox-config')

# Technology used to create the VM ('qemu', 'openvz'(on Proxmox <4.x) or 'lxc'(on Proxmox 4.x+))
technology: qemu

# Proxmox node name
host: node_name

# Proxmox password
password: your_password

# Workaround https://github.com/saltstack/salt/issues/27821
size: ''

# RAM size (MB)
memory: 2048

# OS Type enum (other / wxp / w2k / w2k3 / w2k8 / wvista / win7 / win8 / l24 / l26 / solaris)
ostype: win7

# Hard disk location
sata0: <location>:<size>, format=<qcow2/vmdk/raw>, size=<size>GB #Example: local:120,format=qcow2,size=120GB

#CD/DVD Drive
ide2: <content_location>,media=cdrom #Example: local:iso/name.iso,media=cdrom

# Network Device
net0:<model>,bridge=<bridge> #Example: e1000,bridge=vmbr0

# Enable QEMU Guest Agent (0 / 1)
agent: 1

# VM name
name: Test

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

proxmox-win7:
# Enable Clone
clone: True

# New VM description
clone_description: 'description'

# New VM name
clone_name: 'name'

# New VM format (qcow2 / raw / vmdk)
clone_format: qcow2

# Full clone (1) or Link clone (0)
clone_full: 0

# VMID of Template to clone
clone_from: ID

# Technology used to create the VM ('qemu' or 'lxc')
technology: qemu

# Proxmox node name
host: node_name

# Proxmox password
password: your_password

# Workaround https://github.com/saltstack/salt/issues/27821
size: ''

More information can be found on Proxmox API under the 'POST' method of
/nodes/{node}/qemu/{vmid}/clone

NOTE:
The Proxmox API offers a lot more options and parameters, which are not yet supported
by this salt-cloud 'overlay'. Feel free to add your contribution by forking the github
repository and modifying the following file: salt/salt/cloud/clouds/proxmox.py An easy
way to support more parameters for VM creation would be to add the names of the
optional parameters in the 'create_nodes(
vm_
)' function, under the 'qemu' technology. But it requires you to dig into the code ...

Getting Started With Rackspace
Rackspace is a major public cloud platform which may be configured using either the
openstack driver.

Dependencies
• Libcloud >= 0.13.2

Configuration
To use the openstack driver (recommended), set up the cloud configuration at
/etc/salt/cloud.providers or /etc/salt/cloud.providers.d/rackspace.conf:

my-rackspace-config:
# Set the location of the salt-master
#
minion:
master: saltmaster.example.com

# Configure Rackspace using the OpenStack plugin
#
identity_url: 'https://identity.api.rackspacecloud.com/v2.0/tokens'
compute_name: cloudServersOpenStack
protocol: ipv4

# Set the compute region:
#
compute_region: DFW

# Configure Rackspace authentication credentials
#
user: myname
tenant: 123456
apikey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

driver: openstack

NOTE:
Changed in version 2015.8.0.

Compute Region
Rackspace currently has six compute regions which may be used:

DFW -> Dallas/Forth Worth
ORD -> Chicago
SYD -> Sydney
LON -> London
IAD -> Northern Virginia
HKG -> Hong Kong

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:

openstack_512:
provider: my-rackspace-config
size: 512 MB Standard
image: Ubuntu 12.04 LTS (Precise Pangolin)

To instantiate a machine based on this profile:

# salt-cloud -p openstack_512 myinstance

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:

# salt myinstance test.ping

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:

openstack_512:
provider: my-openstack-config
size: 512 MB Standard
image: Ubuntu 12.04 LTS (Precise Pangolin)
rackconnect: True

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.

openstack_512:
provider: my-rackspace-config
size: 512 MB Standard
image: Ubuntu 12.04 LTS (Precise Pangolin)
managedcloud: True

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:

FreeBSD-9.0-512:
provider: my-rackspace-config
size: 512 MB Standard
image: FreeBSD 9.0
force_first_gen: True

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)

networks:
- fixed:
# This is the private network
- private-network-id
# This is Rackspace's "PublicNet"
- 00000000-0000-0000-0000-000000000000
# This is Rackspace's "ServiceNet"
- 11111111-1111-1111-1111-111111111111

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: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.

my-scaleway-config:
access_key: 15cf404d-4560-41b1-9a0c-21c3d5c4ff1f
token: a7347ec8-5de1-4024-a5e3-24b77d1ba91d
driver: scaleway

NOTE:
Changed in version 2015.8.0.

Profiles
Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles or in the
/etc/salt/cloud.profiles.d/ directory:

scaleway-ubuntu:
provider: my-scaleway-config
image: Ubuntu Trusty (14.04 LTS)

Images can be obtained using the --list-images option for the salt-cloud command:

#salt-cloud --list-images my-scaleway-config
my-scaleway-config:
----------
scaleway:
----------
069fd876-eb04-44ab-a9cd-47e2fa3e5309:
----------
arch:
arm
creation_date:
2015-03-12T09:35:45.764477+00:00
default_bootscript:
{u'kernel': {u'dtb': u'', u'title': u'Pimouss 3.2.34-30-std', u'id': u'cfda4308-cd6f-4e51-9744-905fc0da370f', u'path': u'kernel/pimouss-uImage-3.2.34-30-std'}, u'title': u'3.2.34-std #30 (stable)', u'id': u'c5af0215-2516-4316-befc-5da1cfad609c', u'initrd': {u'path': u'initrd/c1-uInitrd', u'id': u'1be14b1b-e24c-48e5-b0b6-7ba452e42b92', u'title': u'C1 initrd'}, u'bootcmdargs': {u'id': u'd22c4dde-e5a4-47ad-abb9-d23b54d542ff', u'value': u'ip=dhcp boot=local root=/dev/nbd0 USE_XNBD=1 nbd.max_parts=8'}, u'organization': u'11111111-1111-4111-8111-111111111111', u'public': True}
extra_volumes:
[]
id:
069fd876-eb04-44ab-a9cd-47e2fa3e5309
modification_date:
2015-04-24T12:02:16.820256+00:00
name:
Ubuntu Vivid (15.04)
organization:
a283af0b-d13e-42e1-a43f-855ffbf281ab
public:
True
root_volume:
{u'name': u'distrib-ubuntu-vivid-2015-03-12_10:32-snapshot', u'id': u'a6d02e63-8dee-4bce-b627-b21730f35a05', u'volume_type': u'l_ssd', u'size': 50000000000L}
...

Execute a query and return all information about the nodes running on configured cloud
providers using the -Q option for the salt-cloud command:

# salt-cloud -F
[INFO ] salt-cloud starting
[INFO ] Starting new HTTPS connection (1): api.scaleway.com
my-scaleway-config:
----------
scaleway:
----------
salt-manager:
----------
creation_date:
2015-06-03T08:17:38.818068+00:00
hostname:
salt-manager
...

NOTE:
Additional documentation about Scaleway can be found at https://www.scaleway.com/docs.

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:

# Note: This example is for /etc/salt/cloud.providers file or any file in
# the /etc/salt/cloud.providers.d/ directory.

my-saltify-config:
minion:
master: 111.222.333.444
provider: saltify

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:

# /etc/salt/cloud.profiles.d/saltify.conf

salt-this-machine:
ssh_host: 12.34.56.78
ssh_username: root
key_filename: '/etc/salt/mysshkey.pem'
provider: my-saltify-config

The machine can now be "Salted" with the following command:

salt-cloud -p salt-this-machine my-machine

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:

salt my-machine test.ping

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:

# /etc/salt/saltify-map

make_salty:
- my-instance-0:
ssh_host: 12.34.56.78
ssh_username: root
password: very-bad-password
- my-instance-1:
ssh_host: 44.33.22.11
ssh_username: root
password: another-bad-pass

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:

# /etc/salt/cloud.profiles.d/saltify.conf

make_salty:
provider: my-saltify-config

The machines listed in the map file can now be "Salted" by applying the following salt map
command:

salt-cloud -m /etc/salt/saltify-map

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:

salt 'my-instance-*' test.ping

Credential Verification
Because the Saltify driver does not actually create VM's, unlike other salt-cloud drivers,
it has special behaviour when the deploy option is set to False. When the cloud
configuration specifies deploy: False, the Saltify driver will attept to authenticate to
the target node(s) and return True for each one that succeeds. This can be useful to
verify ports, protocols, services and credentials are correctly configured before a live
deployment.

Return values:

• True: Credential verification succeeded

• False: Credential verification succeeded

• None: Credential verification was not attempted.

NOTE:
This feature is not available for Windows targets.

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:

# pip install softlayer
# easy_install softlayer

Configuration
Set up the cloud config at /etc/salt/cloud.providers:

# Note: These examples are for /etc/salt/cloud.providers

my-softlayer:
# Set up the location of the salt master
minion:
master: saltmaster.example.com

# Set the SoftLayer access credentials (see below)
user: MYUSER1138
apikey: 'e3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9'

driver: softlayer

my-softlayer-hw:
# Set up the location of the salt master
minion:
master: saltmaster.example.com

# Set the SoftLayer access credentials (see below)
user: MYUSER1138
apikey: 'e3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9'

driver: softlayer_hw

NOTE:
Changed in version 2015.8.0.

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:

• Hover over the Account menu item.

• Click the Users link.

• Find the API Key column and click View.

Profiles
Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles:

base_softlayer_ubuntu:
provider: my-softlayer
image: UBUNTU_LATEST
cpu_number: 1
ram: 1024
disk_size: 100
local_disk: True
hourly_billing: True
domain: example.com
location: sjc01
# Optional
max_net_speed: 1000
private_vlan: 396
private_network: True
private_ssh: True
# May be used _instead_of_ image
global_identifier: 320d8be5-46c0-dead-cafe-13e3c51

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:

# salt-cloud --list-images my-softlayer

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:

Red Hat Enterprise Linux 6 - Minimal Install (64 bit) (1 - 4 Core):
----------
name:
Red Hat Enterprise Linux 6 - Minimal Install (64 bit) (1 - 4 Core)
template:
REDHAT_6_64
Red Hat Enterprise Linux 6 - Minimal Install (64 bit) (5 - 100 Core):
----------
name:
Red Hat Enterprise Linux 6 - Minimal Install (64 bit) (5 - 100 Core)
template:
REDHAT_6_64

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.

base_softlayer_ubuntu:
disk_size: 100

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:

base_softlayer_ubuntu:
disk_size: ['100', '20', '20']

String Example:

base_softlayer_ubuntu:
disk_size: '100, 20, 20'

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:
When enabling the use_fqdn setting, the Minion ID will be the FQDN and will interact
with salt commands with the FQDN instead of the short hostname. However, due to the way
the SoftLayer API is constructed, some Salt Cloud functions such as listing nodes or
destroying VMs will only list the short hostname of the VM instead of the FQDN.

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

# salt-key -L
Accepted Keys:
my-vm.example.com
Denied Keys:
Unaccepted Keys:
Rejected Keys:
#
#
# salt my-vm.example.com test.ping
my-vm.example.com:
True
#
#
# salt-cloud -d my-vm.example.com
[INFO ] salt-cloud starting
[INFO ] POST https://api.softlayer.com/xmlrpc/v3.1/SoftLayer_Account
The following virtual machines are set to be destroyed:
softlayer-config:
softlayer:
my-vm

Proceed? [N/y] y
... proceeding
[INFO ] Destroying in non-parallel mode.
[INFO ] POST https://api.softlayer.com/xmlrpc/v3.1/SoftLayer_Account
[INFO ] POST https://api.softlayer.com/xmlrpc/v3.1/SoftLayer_Virtual_Guest
softlayer-config:
----------
softlayer:
----------
my-vm:
True

location
Images to build an instance can be found using the --list-locations option:

# salt-cloud --list-location my-softlayer

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:

base_softlayer_ubuntu:
post_uri: 'https://SOMESERVERIP:8000/myscript.sh'

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.

If this setting is set to None, salt-cloud will connect to the private ip of the server.

NOTE:
If this setting is not provided and the server is not built with a public vlan,
private_ssh or private_wds will need to be set to make sure that salt-cloud attempts to
connect to the private ip.

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 or private_wds
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 or WinRM 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:

# salt-cloud -p base_softlayer_ubuntu myserver

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:

# salt 'myserver.example.com' test.ping

Cloud Profiles
Set up an initial profile at /etc/salt/cloud.profiles:

base_softlayer_hw_centos:
provider: my-softlayer-hw
# CentOS 6.0 - Minimal Install (64 bit)
image: 13963
# 2 x 2.0 GHz Core Bare Metal Instance - 2 GB Ram
size: 1921
# 500GB SATA II
hdd: 1267
# San Jose 01
location: 168642
domain: example.com
# Optional
vlan: 396
port_speed: 273
banwidth: 248

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:

# salt-cloud --list-images my-softlayer-hw

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:

# salt-cloud --list-sizes my-softlayer-hw

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:

1267: 500GB SATA II

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:

# salt-cloud --list-locations my-softlayer-hw

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:

• 273: 100 Mbps Public & Private Networks

• 274: 1 Gbps Public & Private Networks

• 21509: 10 Mbps Dual Public & Private Networks (up to 20 Mbps)

• 21513: 100 Mbps Dual Public & Private Networks (up to 200 Mbps)

• 2314: 1 Gbps Dual Public & Private Networks (up to 2 Gbps)

• 272: 10 Mbps Public & Private Networks

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:

• 248: 5000 GB Bandwidth

• 129: 6000 GB Bandwidth

• 130: 8000 GB Bandwidth

• 131: 10000 GB Bandwidth

• 36: Unlimited Bandwidth (10 Mbps Uplink)

• 125: Unlimited Bandwidth (100 Mbps Uplink)

Actions
The following actions are currently supported by the SoftLayer Salt Cloud driver.

$ salt-cloud -a show_instance myinstance

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.

$ salt-cloud -f list_vlans my-softlayer
$ salt-cloud -f list_vlans my-softlayer-hw

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.

$ salt-cloud -f list_custom_images my-softlayer

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:

softlayer_hw_test:
provider: my-softlayer-hw
# CentOS 6.0 - Minimal Install (64 bit)
image: 13963
# 2 x 2.0 GHz Core Bare Metal Instance - 2 GB Ram
size: 1921
# 500GB SATA II
hdd: 1267
# San Jose 01
location: 168642
domain: example.com
optional_products:
# MySQL for Linux
- id: 28
# Business Continuance Insurance
- id: 104

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
• 22: 4 Public IP Addresses

• 23: 8 Public IP Addresses

Primary IPv6 Addresses
• 17129: 1 IPv6 Address

Public Static IPv6 Addresses
• 1481: /64 Block Static Public IPv6 Addresses

OS-Specific Addon
• 17139: XenServer Advanced for XenServer 6.x

• 17141: XenServer Enterprise for XenServer 6.x

• 2334: XenServer Advanced for XenServer 5.6

• 2335: XenServer Enterprise for XenServer 5.6

• 13915: Microsoft WebMatrix

• 21276: VMware vCenter 5.1 Standard

Control Panel Software
• 121: cPanel/WHM with Fantastico and RVskin

• 20778: Parallels Plesk Panel 11 (Linux) 100 Domain w/ Power Pack

• 20786: Parallels Plesk Panel 11 (Windows) 100 Domain w/ Power Pack

• 20787: Parallels Plesk Panel 11 (Linux) Unlimited Domain w/ Power Pack

• 20792: Parallels Plesk Panel 11 (Windows) Unlimited Domain w/ Power Pack

• 2340: Parallels Plesk Panel 10 (Linux) 100 Domain w/ Power Pack

• 2339: Parallels Plesk Panel 10 (Linux) Unlimited Domain w/ Power Pack

• 13704: Parallels Plesk Panel 10 (Windows) Unlimited Domain w/ Power Pack

Database Software
• 29: MySQL 5.0 for Windows

• 28: MySQL for Linux

• 21501: Riak 1.x

• 20893: MongoDB

• 30: Microsoft SQL Server 2005 Express

• 92: Microsoft SQL Server 2005 Workgroup

• 90: Microsoft SQL Server 2005 Standard

• 94: Microsoft SQL Server 2005 Enterprise

• 1330: Microsoft SQL Server 2008 Express

• 1340: Microsoft SQL Server 2008 Web

• 1337: Microsoft SQL Server 2008 Workgroup

• 1334: Microsoft SQL Server 2008 Standard

• 1331: Microsoft SQL Server 2008 Enterprise

• 2179: Microsoft SQL Server 2008 Express R2

• 2173: Microsoft SQL Server 2008 Web R2

• 2183: Microsoft SQL Server 2008 Workgroup R2

• 2180: Microsoft SQL Server 2008 Standard R2

• 2176: Microsoft SQL Server 2008 Enterprise R2

Anti-Virus & Spyware Protection
• 594: McAfee VirusScan Anti-Virus - Windows

• 414: McAfee Total Protection - Windows

Insurance
• 104: Business Continuance Insurance

Monitoring
• 55: Host Ping

• 56: Host Ping and TCP Service Monitoring

Notification
• 57: Email and Ticket

Advanced Monitoring
• 2302: Monitoring Package - Basic

• 2303: Monitoring Package - Advanced

• 2304: Monitoring Package - Premium Application

Response
• 58: Automated Notification

• 59: Automated Reboot from Monitoring

• 60: 24x7x365 NOC Monitoring, Notification, and Response

Intrusion Detection & Protection
• 413: McAfee Host Intrusion Protection w/Reporting

Hardware & Software Firewalls
• 411: APF Software Firewall for Linux

• 894: Microsoft Windows Firewall

• 410: 10Mbps Hardware Firewall

• 409: 100Mbps Hardware Firewall

• 408: 1000Mbps Hardware Firewall

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.

my-vexxhost-config:
# Set the location of the salt-master
#
minion:
master: saltmaster.example.com

# Configure VEXXHOST using the OpenStack plugin
#
identity_url: http://auth.api.thenebulacloud.com:5000/v2.0/tokens
compute_name: nova

# Set the compute region:
#
compute_region: na-yul-nhs1

# Configure VEXXHOST authentication credentials
#
user: your-tenant-id
password: your-api-key
tenant: your-tenant-name

# keys to allow connection to the instance launched
#
ssh_key_name: yourkey
ssh_key_file: /path/to/key/yourkey.priv

driver: openstack

NOTE:
Changed in version 2015.8.0.

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:

# salt-cloud --list-images=vexxhost-config
# salt-cloud --list-sizes=vexxhost-config

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:

vh_ubuntu1204_2G:
provider: my-vexxhost-config
image: 4051139f-750d-4d72-8ef0-074f2ccc7e5a
size: nb.2G

Provision an instance
To create an instance based on the sample profile that we created above, you can run the
following salt-cloud command.

# salt-cloud -p vh_ubuntu1204_2G vh_instance1

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:

# salt vh_instance1 test.ping

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:

virtualbox-config:
driver: virtualbox

Profiles
Set up an initial profile at /etc/salt/cloud.profiles or
/etc/salt/cloud.profiles.d/virtualbox.conf:

virtualbox-test:
provider: virtualbox-config
clonefrom: VM_to_clone_from
# Optional
power_on: True
deploy: True
ssh_username: a_username
password: a_password
sudo: a_username
sudo_password: a_password
# Example minion config
minion:
master: localhost
make_master: True

clonefrom Mandatory
Enter the name of the VM/template to clone from.

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
start Attempt to boot a VM by name. VMs should have unique names in order to boot the
correct one.

stop Attempt to stop a VM. This is akin to a force shutdown or 5 second press.

Functions
show_image
Show all available information about a VM given by the image parameter

$ salt-cloud -f show_image virtualbox image=my_vm_name

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:

pip install pyvmomi
easy_install pyvmomi

NOTE:
Version 6.0 of pyVmomi has some problems with SSL error handling on certain versions of
Python. If using version 6.0 of pyVmomi, the machine that you are running the proxy
minion process from must have either Python 2.7.9 or newer This is due to an upstream
dependency in pyVmomi 6.0 that is not supported in Python version 2.6 to 2.7.8. If the
version of Python running the salt-cloud command is not in the supported range, you
will need to install an earlier version of pyVmomi. See Issue #29537 for more
information.

NOTE:
pyVmomi doesn't expose the ability to specify the locale when connecting to VMware.
This causes parsing issues when connecting to an instance of VMware running under a
non-English locale. Until this feature is added upstream Issue #38402 contains a
workaround.

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:

my-vmware-config:
driver: vmware
user: 'DOMAIN\user'
password: 'verybadpass'
url: '10.20.30.40'

vcenter01:
driver: vmware
user: 'DOMAIN\user'
password: 'verybadpass'
url: 'vcenter01.domain.com'
protocol: 'https'
port: 443

vcenter02:
driver: vmware
user: 'DOMAIN\user'
password: 'verybadpass'
url: 'vcenter02.domain.com'
protocol: 'http'
port: 80

esx01:
driver: vmware
user: 'admin'
password: 'verybadpass'
url: 'esx01.domain.com'

NOTE:
Optionally, protocol and port can be specified if the vCenter server is not using the
defaults. Default is protocol: https and port: 443.

NOTE:
Changed in version 2015.8.0.

The provider parameter in cloud provider configuration was renamed to driver. This
change was made to avoid confusion with the provider parameter that is used in cloud
profile configuration. Cloud provider configuration now uses driver to refer to the
salt-cloud driver that provides the underlying functionality to connect to a cloud
provider, while cloud profile configuration continues to use provider to refer to the
cloud provider configuration that you define.

Profiles
Set up an initial profile at /etc/salt/cloud.profiles or
/etc/salt/cloud.profiles.d/vmware.conf:

vmware-centos6.5:
provider: vcenter01
clonefrom: test-vm

## Optional arguments
num_cpus: 4
memory: 8GB
devices:
cd:
CD/DVD drive 1:
device_type: datastore_iso_file
iso_path: "[nap004-1] vmimages/tools-isoimages/linux.iso"
CD/DVD drive 2:
device_type: client_device
mode: atapi
controller: IDE 2
CD/DVD drive 3:
device_type: client_device
mode: passthrough
controller: IDE 3
disk:
Hard disk 1:
size: 30
Hard disk 2:
size: 20
controller: SCSI controller 2
Hard disk 3:
size: 5
controller: SCSI controller 3
datastore: smalldiskdatastore
network:
Network adapter 1:
name: 10.20.30-400-Test
switch_type: standard
ip: 10.20.30.123
gateway: [10.20.30.110]
subnet_mask: 255.255.255.128
domain: example.com
Network adapter 2:
name: 10.30.40-500-Dev-DHCP
adapter_type: e1000
switch_type: distributed
mac: '00:16:3e:e8:19:0f'
Network adapter 3:
name: 10.40.50-600-Prod
adapter_type: vmxnet3
switch_type: distributed
ip: 10.40.50.123
gateway: [10.40.50.110]
subnet_mask: 255.255.255.128
domain: example.com
scsi:
SCSI controller 1:
type: lsilogic
SCSI controller 2:
type: lsilogic_sas
bus_sharing: virtual
SCSI controller 3:
type: paravirtual
bus_sharing: physical
ide:
IDE 2
IDE 3

domain: example.com
dns_servers:
- 123.127.255.240
- 123.127.255.241
- 123.127.255.242

resourcepool: Resources
cluster: Prod

datastore: HUGE-DATASTORE-Cluster
folder: Development
datacenter: DC1
host: c4212n-002.domain.com
template: False
power_on: True
extra_config:
mem.hotadd: 'yes'
guestinfo.foo: bar
guestinfo.domain: foobar.com
guestinfo.customVariable: customValue

deploy: True
customization: True
private_key: /root/.ssh/mykey.pem
ssh_username: cloud-user
password: veryVeryBadPassword
minion:
master: 123.127.193.105

file_map:
/path/to/local/custom/script: /path/to/remote/script
/path/to/local/file: /path/to/remote/file
/srv/salt/yum/epel.repo: /etc/yum.repos.d/epel.repo

hardware_version: 10
image: centos64Guest

#For Windows VM
win_username: Administrator
win_password: administrator
win_organization_name: ABC-Corp
plain_text: True
win_installer: /root/Salt-Minion-2015.8.4-AMD64-Setup.exe
win_user_fullname: Windows User

provider
Enter the name that was specified when the cloud provider config was created.

clonefrom
Enter the name of the VM/template to clone from. If not specified, the VM will be
created without cloning.

num_cpus
Enter the number of vCPUS that you want the VM/template to have. If not specified,
the current VM/template's vCPU count is used.

cores_per_socket
New in version 2016.11.0.

Enter the number of cores per vCPU that you want the VM/template to have. If not
specified, this will default to 1.

NOTE:
Cores per socket should be less than or equal to the total number of vCPUs
assigned to the VM/template.

memory Enter the memory size (in MB or GB) that you want the VM/template to have. If not
specified, the current VM/template's memory size is used. Example memory: 8GB or
memory: 8192MB.

devices
Enter the device specifications here. Currently, the following devices can be
created or reconfigured:

cd Enter the CD/DVD drive specification here. If the CD/DVD drive doesn't
exist, it will be created with the specified configuration. If the CD/DVD
drive already exists, it will be reconfigured with the specifications. The
following options can be specified per CD/DVD drive:

device_type
Specify how the CD/DVD drive should be used. Currently supported
types are client_device and datastore_iso_file. Default is
device_type: client_device

iso_path
Enter the path to the iso file present on the datastore only if
device_type: datastore_iso_file. The syntax to specify this is
iso_path: "[datastoreName] vmimages/tools-isoimages/linux.iso". This
field is ignored if device_type: client_device

mode Enter the mode of connection only if device_type: client_device.
Currently supported modes are passthrough and atapi. This field is
ignored if device_type: datastore_iso_file. Default is mode:
passthrough

controller
Specify the IDE controller label to which this drive should be
attached. This should be specified only when creating both the
specified IDE controller as well as the CD/DVD drive at the same
time.

disk Enter the disk specification here. If the hard disk doesn't exist, it will
be created with the provided size. If the hard disk already exists, it will
be expanded if the provided size is greater than the current size of the
disk.

size Enter the size of disk in GB

thin_provision
Specifies whether the disk should be thin provisioned or not. Default
is thin_provision: False.

controller
Specify the SCSI controller label to which this disk should be
attached. This should be specified only when creating both the
specified SCSI controller as well as the hard disk at the same time.

datastore
The name of a valid datastore should you wish the new disk to be in a
datastore other than the default for the VM.

network
Enter the network adapter specification here. If the network adapter doesn't
exist, a new network adapter will be created with the specified network
name, type and other configuration. If the network adapter already exists,
it will be reconfigured with the specifications. The following additional
options can be specified per network adapter (See example above):

name Enter the network name you want the network adapter to be mapped to.

adapter_type
Enter the network adapter type you want to create. Currently
supported types are vmxnet, vmxnet2, vmxnet3, e1000 and e1000e. If
no type is specified, by default vmxnet3 will be used.

switch_type
Enter the type of switch to use. This decides whether to use a
standard switch network or a distributed virtual portgroup. Currently
supported types are standard for standard portgroups and distributed
for distributed virtual portgroups.

ip Enter the static IP you want the network adapter to be mapped to. If
the network specified is DHCP enabled, you do not have to specify
this.

gateway
Enter the gateway for the network as a list. If the network specified
is DHCP enabled, you do not have to specify this.

subnet_mask
Enter the subnet mask for the network. If the network specified is
DHCP enabled, you do not have to specify this.

domain Enter the domain to be used with the network adapter. If the network
specified is DHCP enabled, you do not have to specify this.

mac Enter the MAC for this network adapter. If not specified an address
will be selected automatically.

scsi Enter the SCSI controller specification here. If the SCSI controller doesn't
exist, a new SCSI controller will be created of the specified type. If the
SCSI controller already exists, it will be reconfigured with the
specifications. The following additional options can be specified per SCSI
controller:

type Enter the SCSI controller type you want to create. Currently
supported types are lsilogic, lsilogic_sas and paravirtual. Type must
be specified when creating a new SCSI controller.

bus_sharing
Specify this if sharing of virtual disks between virtual machines is
desired. The following can be specified:

virtual
Virtual disks can be shared between virtual machines on the
same server.

physical
Virtual disks can be shared between virtual machines on any
server.

no Virtual disks cannot be shared between virtual machines.

ide Enter the IDE controller specification here. If the IDE controller doesn't
exist, a new IDE controller will be created. If the IDE controller already
exists, no further changes to it will me made.

domain Enter the global domain name to be used for DNS. If not specified and if the VM
name is a FQDN, domain is set to the domain from the VM name. Default is local.

dns_servers
Enter the list of DNS servers to use in order of priority.

resourcepool
Enter the name of the resourcepool to which the new virtual machine should be
attached. This determines what compute resources will be available to the clone.

NOTE:

• For a clone operation from a virtual machine, it will use the same
resourcepool as the original virtual machine unless specified.

• For a clone operation from a template to a virtual machine, specifying either
this or cluster is required. If both are specified, the resourcepool value
will be used.

• For a clone operation to a template, this argument is ignored.

cluster
Enter the name of the cluster whose resource pool the new virtual machine should be
attached to.

NOTE:

• For a clone operation from a virtual machine, it will use the same cluster's
resourcepool as the original virtual machine unless specified.

• For a clone operation from a template to a virtual machine, specifying either
this or resourcepool is required. If both are specified, the resourcepool
value will be used.

• For a clone operation to a template, this argument is ignored.

datastore
Enter the name of the datastore or the datastore cluster where the virtual machine
should be located on physical storage. If not specified, the current datastore is
used.

NOTE:

• If you specify a datastore cluster name, DRS Storage recommendation is
automatically applied.

• If you specify a datastore name, DRS Storage recommendation is disabled.

folder Enter the name of the folder that will contain the new virtual machine.

NOTE:

• For a clone operation from a VM/template, the new VM/template will be added to
the same folder that the original VM/template belongs to unless specified.

• If both folder and datacenter are specified, the folder value will be used.

datacenter
Enter the name of the datacenter that will contain the new virtual machine.

NOTE:

• For a clone operation from a VM/template, the new VM/template will be added to
the same folder that the original VM/template belongs to unless specified.

• If both folder and datacenter are specified, the folder value will be used.

host Enter the name of the target host where the virtual machine should be registered.

If not specified:

NOTE:

• If resource pool is not specified, current host is used.

• If resource pool is specified, and the target pool represents a stand-alone
host, the host is used.

• If resource pool is specified, and the target pool represents a DRS-enabled
cluster, a host selected by DRS is used.

• If resource pool is specified and the target pool represents a cluster without
DRS enabled, an InvalidArgument exception be thrown.

template
Specifies whether the new virtual machine should be marked as a template or not.
Default is template: False.

power_on
Specifies whether the new virtual machine should be powered on or not. If template:
True is set, this field is ignored. Default is power_on: True.

extra_config
Specifies the additional configuration information for the virtual machine. This
describes a set of modifications to the additional options. If the key is already
present, it will be reset with the new value provided. Otherwise, a new option is
added. Keys with empty values will be removed.

deploy Specifies if salt should be installed on the newly created VM. Default is True so
salt will be installed using the bootstrap script. If template: True or power_on:
False is set, this field is ignored and salt will not be installed.

wait_for_ip_timeout
When deploy: True, this timeout determines the maximum time to wait for VMware
tools to be installed on the virtual machine. If this timeout is reached, an
attempt to determine the client's IP will be made by resolving the VM's name. By
lowering this value a salt bootstrap can be fully automated for systems that are
not built with VMware tools. Default is wait_for_ip_timeout: 1200.

customization
Specify whether the new virtual machine should be customized or not. If
customization: False is set, the new virtual machine will not be customized.
Default is customization: True.

private_key
Specify the path to the private key to use to be able to ssh to the VM.

ssh_username
Specify the username to use in order to ssh to the VM. Default is root

password
Specify a password to use in order to ssh to the VM. If private_key is specified,
you do not need to specify this.

minion Specify custom minion configuration you want the salt minion to have. A good
example would be to specify the master as the IP/DNS name of the master.

file_map
Specify file/files you want to copy to the VM before the bootstrap script is run
and salt is installed. A good example of using this would be if you need to put
custom repo files on the server in case your server will be in a private network
and cannot reach external networks.

hardware_version
Specify the virtual hardware version for the vm/template that is supported by the
host.

image Specify the guest id of the VM. For a full list of supported values see the VMware
vSphere documentation:

http://pubs.vmware.com/vsphere-60/topic/com.vmware.wssdk.apiref.doc/vim.vm.GuestOsDescriptor.GuestOsIdentifier.html

NOTE:
For a clone operation, this argument is ignored.

win_username
Specify windows vm administrator account.

NOTE:
Windows template should have "administrator" account.

win_password
Specify windows vm administrator account password.

NOTE:
During network configuration (if network specified), it is used to specify new
administrator password for the machine.

win_organization_name

Specify windows vm user's organization. Default organization name is Organization
VMware vSphere documentation:

https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/vim.vm.customization.UserData.html

win_user_fullname

Specify windows vm user's fullname. Default fullname is Windows User
VMware vSphere documentation:

https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/vim.vm.customization.UserData.html

plain_text
Flag to specify whether or not the password is in plain text, rather than
encrypted. VMware vSphere documentation:

https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/vim.vm.customization.Password.html

win_installer
Specify windows minion client installer path

Cloning a VM
Cloning VMs/templates is the easiest and the preferred way to work with VMs using the
VMware driver.

NOTE:
Cloning operations are unsupported on standalone ESXi hosts, a vCenter server will be
required.

Example of a minimal profile:

my-minimal-clone:
provider: vcenter01
clonefrom: 'test-vm'

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:

my-disk-example:
provider: vcenter01
clonefrom: 'test-vm'

devices:
disk:
Hard disk 1:
size: 30

Depending on the configuration of the VM that is getting cloned, the disk in the resulting
clone will differ.

NOTE:

• If the VM has no disk named 'Hard disk 1' an empty disk with the specified size will
be added to the clone.

• If the VM has a disk named 'Hard disk 1' and the size specified is larger than the
original disk, an empty disk with the specified size will be added to the clone.

• If the VM has a disk named 'Hard disk 1' and the size specified is smaller than the
original disk, an empty disk with the original size will be added to the clone.

Example to reconfigure the memory and number of vCPUs:

my-disk-example:
provider: vcenter01
clonefrom: 'test-vm'

memory: 16GB
num_cpus: 8

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:

my-template-clone:
provider: vcenter01
clonefrom: 'test-template'
cluster: 'Prod'

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:

my-template-clone:
provider: vcenter01
clonefrom: 'salt_vm'
snapshot:
disk_move_type: createNewChildDiskBacking
# these types are also supported
# disk_move_type: moveChildMostDiskBacking
# disk_move_type: moveAllDiskBackingsAndAllowSharing
# disk_move_type: moveAllDiskBackingsAndDisallowSharing

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:
Unlike most cloud drivers that use prepared images, creating VMs using VMware cloud
driver needs an installation method that requires no human interaction. For Example:
preseeded ISO, kickstart URL or network PXE boot.

Example of a minimal profile:

my-minimal-profile:
provider: esx01
datastore: esx01-datastore
resourcepool: Resources
folder: vm

NOTE:
The example above contains the minimum required configuration needed to create a VM
from scratch. The resulting VM will only have 1 VCPU, 32MB of RAM and will not have any
storage or networking.

Example of a complete profile:

my-complete-example:
provider: esx01
datastore: esx01-datastore
resourcepool: Resources
folder: vm

num_cpus: 2
memory: 8GB

image: debian7_64Guest

devices:
scsi:
SCSI controller 0:
type: lsilogic_sas
ide:
IDE 0: {}
IDE 1: {}
disk:
Hard disk 0:
controller: 'SCSI controller 0'
size: 20
mode: 'independent_nonpersistent'
cd:
CD/DVD drive 0:
controller: 'IDE 0'
device_type: datastore_iso_file
iso_path: '[esx01-datastore] debian-8-with-preseed.iso'
network:
Network adapter 0:
name: 'VM Network'
swith_type: standard

NOTE:
Depending on VMware ESX/ESXi version, an exact match for image might not be available.
In such cases, the closest match to another image should be used. In the example above,
a Debian 8 VM is created using the image debian7_64Guest which is for a Debian 7 guest.

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:

my-vm:
provider: esx01
datastore: esx01-datastore
resourcepool: Resources
folder: vm

devices:
disk:
Hard disk 1:
mode: 'independent_nonpersistent'
size: 42
Hard disk 2:
mode: 'independent_nonpersistent'

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:

ec2-amazon:
provider: my-ec2-config
image: ami-1624987f
size: t1.micro
ssh_username: ec2-user
script: bootstrap-salt
script_args: -c /tmp/

This has also been tested to work with pipes, if needed:

script_args: | head

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.

file_transport: sftp
file_transport: scp

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:

sync_after_install: all

The available options for this setting are:

modules
grains
states
all

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.

make_master: True

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:

master:
user: root
interface: 0.0.0.0

Setting Up a Salt Syndic with Salt Cloud
In addition to setting up new Salt Masters, syndics 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:

make_master: True

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:

master:
syndic_master: 123.456.789 # may be either an IP address or a hostname

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

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.

ssh_port: 2222

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:

delete_sshkeys: True

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:

salt-cloud -p myprofile mymachine --keep-tmp

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:

display_ssh_output: False

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.

Note

All settings should be provided in lowercase All values should be provided in
seconds

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.

cache_event_strip_fields:
- password
- priv_key

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:

known_hosts_file: /path/to/.ssh/known_hosts

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.

ssh_agent: True

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:

ubuntu14:
provider: ec2-config
image: ami-98aa1cf0
size: t1.micro
ssh_username: root
securitygroup: default
file_map:
/local/path/to/custom/script: /remote/path/to/use/custom/script
/local/path/to/package: /remote/path/to/store/package

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:

salt-cloud -p myprofile myinstance -l debug

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:

salt-cloud -u

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:

salt-cloud -p myprofile myinstance --keep-tmp

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:

• A deploy.sh script. This script should have permissions of 0755.

• A .pem and .pub key named after the minion. The .pem file should have permissions of
0600. Ensure that the .pem and .pub files have been properly copied to the
/etc/salt/pki/minion/ directory.

• A file called minion. This file should have been copied to the /etc/salt/ directory.

• Optionally, a file called grains. This file, if present, should have been copied to the
/etc/salt/ directory.

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:

sudo_password: mypassword

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

mount | grep tmp

The if the output of this command includes a line that looks like this, then the /tmp/
directory is mounted as noexec:

tmpfs on /tmp type tmpfs (rw,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:

deploy_command: sh /tmp/.saltcloud/deploy.sh

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:

tmp_dir: /tmp/.saltcloud/

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:

cd /tmp/.saltcloud/
./deploy.sh

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:

• Send a request to the cloud host to create a virtual machine.

• Wait for the virtual machine to become available.

• Generate kwargs to be used to deploy Salt.

• Log into the virtual machine and deploy Salt.

• Return a data structure that describes the newly-created virtual machine.

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

from salt.cloud.libcloudfuncs import * # pylint: disable=W0614,W0401
from salt.utils import namespaced_function

And then a series of declarations will make the necessary functions available within the
cloud module.

get_size = namespaced_function(get_size, globals())
get_image = namespaced_function(get_image, globals())
avail_locations = namespaced_function(avail_locations, globals())
avail_images = namespaced_function(avail_images, globals())
avail_sizes = namespaced_function(avail_sizes, globals())
script = namespaced_function(script, globals())
destroy = namespaced_function(destroy, globals())
list_nodes = namespaced_function(list_nodes, globals())
list_nodes_full = namespaced_function(list_nodes_full, globals())
list_nodes_select = namespaced_function(list_nodes_select, globals())
show_instance = namespaced_function(show_instance, globals())

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.

salt-cloud --list-locations my-cloud-provider

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.

salt-cloud --list-images my-cloud-provider

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.

salt-cloud --list-sizes my-cloud-provider

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:

salt-cloud -d myinstance

The list_nodes() Function
This function returns a list of nodes available on this cloud provider, using the
following fields:

• id (str)

• image (str)

• size (str)

• state (str)

• private_ips (list)

• public_ips (list)

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:

salt-cloud -Q

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:

salt-cloud -F

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:

def list_nodes_select(call=None):
'''
Return a list of the VMs that are on the provider, with select fields
'''
return salt.utils.cloud.list_nodes_select(
list_nodes_full('function'), __opts__['query.selection'], call,
)

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:

def list_nodes_select(conn=None, call=None):
'''
Return a list of the VMs that are on the provider, with select fields
'''
if not conn:
conn = get_conn() # pylint: disable=E0602

return salt.utils.cloud.list_nodes_select(
list_nodes_full(conn, 'function'),
__opts__['query.selection'],
call,
)

This function is normally called with the -S option:

salt-cloud -S

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:

salt-cloud -a show_instance myinstance

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:

salt-cloud -a show_instance myinstance

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:

def show_instance(name, call=None):
'''
Show the details from EC2 concerning an AMI
'''
if call != 'action':
raise SaltCloudSystemExit(
'The show_instance action must be called with -a or --action.'
)

return _get_node(name)

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:

salt-cloud -f show_image my-cloud-provider image='Ubuntu 13.10 64-bit'

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:

def show_image(kwargs, call=None):
'''
Show the details from EC2 concerning an AMI
'''
if call != 'function':
raise SaltCloudSystemExit(
'The show_image action must be called with -f or --function.'
)

params = {'ImageId.1': kwargs['image'],
'Action': 'DescribeImages'}
result = query(params)
log.info(result)

return result

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

script: bootstrap-salt

Or in a provider:

my-provider:
# snip...
script: bootstrap-salt

Or in a profile:

my-profile:
provider: my-provider
# snip...
script: bootstrap-salt

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:

curl-bootstrap
curl-bootstrap-git
python-bootstrap
wget-bootstrap
wget-bootstrap-git

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:

1. Install the salt minion. If this can be done via system packages this method is HIGHLY
preferred.

2. Add the salt minion keys before the minion is started for the first time. The minion
keys are available as strings that can be copied into place in the Jinja template under
the dict named "vm".

3. Start the salt-minion daemon and enable it at startup time.

4. Set up the minion configuration file from the "minion" data available in the Jinja
template.

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:

my-profile:
provider: my-provider
# snip...
script: my_deploy

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:

start_action: state.apply

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:

salt-cloud --no-deploy -p micro_aws my_instance

Or it can be set from the main cloud config file:

deploy: False

Or it can be set from the provider's configuration:

RACKSPACE.user: example_user
RACKSPACE.apikey: 123984bjjas87034
RACKSPACE.deploy: False

Or even on the VM's profile settings:

ubuntu_aws:
provider: my-ec2-config
image: ami-7e2da54e
size: t1.micro
deploy: False

The default for deploy is True.

In the profile, you may also set the script option to None:

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

salt-cloud -u
salt-cloud --update-bootstrap

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:

salt-call config.gather_bootstrap_script 'https://bootstrap.saltstack.com/develop/bootstrap-salt.sh'

Or just download the file manually:

curl -L 'https://bootstrap.saltstack.com/develop' > /etc/salt/cloud.deploy.d/bootstrap-salt.sh

salt-cloud -p myprofile mymachine --keep-tmp

aws-amazon:
provider: my-ec2-config
image: ami-1624987f
size: t1.micro
ssh_username: ec2-user
script: bootstrap-salt
script_args: -c /tmp/

This has also been tested to work with pipes, if needed:

script_args: | head

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:

/etc/salt/cloud.providers.d/
/etc/salt/cloud.profiles.d/

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:

salt myminion cloud.list_images my-cloud-provider

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:

salt myminion cloud.list_sizes my-cloud-provider

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:

salt myminion cloud.list_locations my-cloud-provider

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:

id The name or ID of the instance, as used by the cloud provider.

image The disk image that was used to create this instance.

private_ips
Any public IP addresses currently assigned to this instance.

public_ips
Any private IP addresses currently assigned to this instance.

size The size of the instance; can refer to RAM, CPU(s), disk space, etc., depending on
the cloud provider.

state The running state of the instance; for example, running, stopped, pending, etc.
This state is dependent upon the provider.

This command may also be used to perform a full query or a select query, as described
below. The following usages are available:

salt myminion cloud.query
salt myminion cloud.query list_nodes
salt myminion cloud.query list_nodes_full

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.

salt myminion cloud.full_query

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:

query.selection:
- id
- key_name

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:

salt myminion cloud.select_query

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.

salt myminion cloud.profile ec2-centos64-x64 my-new-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.

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:

salt myminion cloud.create my-ec2-config my-new-instance \
image=ami-1624987f size='t1.micro' ssh_username=ec2-user \
securitygroup=default delvol_on_destroy=True

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.

salt myminion cloud.destroy myinstance
salt myminion cloud.destroy myinstance1,myinstance2

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.

salt myminion cloud.action start instance=myinstance
salt myminion cloud.action show_image provider=my-ec2-config \
image=ami-1624987f

The actions available are largely dependent upon the module for the specific cloud
provider. The following actions are available for all cloud providers:

list_nodes
This is a direct call to the query function as described above, but is only
performed against a single cloud provider. A provider configuration must be
included.

list_nodes_select
This is a direct call to the full_query function as described above, but is only
performed against a single cloud provider. A provider configuration must be
included.

list_nodes_select
This is a direct call to the select_query function as described above, but is only
performed against a single cloud provider. A provider configuration must be
included.

show_instance
This is a thin wrapper around list_nodes, which returns the full information about
a single instance. An instance name must be provided.

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.

my-instance-name:
cloud.present:
- provider: my-ec2-config
- image: ami-1624987f
- size: 't1.micro'
- ssh_username: ec2-user
- securitygroup: default
- delvol_on_destroy: True

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.

my-instance-name:
cloud.profile:
- profile: ec2-centos64-x64

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.

my-instance-name:
cloud.absent

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:

• list_images

• list_sizes

• list_locations

• query

• full_query

• select_query

• profile

• destroy

• action

Outside of the standard usage of salt-run itself, commands are executed as usual:

salt-run cloud.profile ec2-centos64-x86_64 my-instance-name

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:

import salt.cloud
import pprint
client = salt.cloud.CloudClient('/etc/salt/cloud')
nodes = client.query()
pprint.pprint(nodes)

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.

┌──────────┬──────────┬────────────┬─────────┬─────┬────────┬────────┬────────┬───────────┬───────────┬───────────┬─────────┬───────────┬───────────┬────────┐
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
└──────────┴──────────┴────────────┴─────────┴─────┴────────┴────────┴────────┴───────────┴───────────┴───────────┴─────────┴───────────┴───────────┴────────┘

Actions
These are features that are performed on a specific instance, and require an instance name
to be passed in. For example:

# salt-cloud -a attach_volume ami.example.com

┌───────────────────────┬──────────┬────────────┬─────────┬─────┬────────┬────────┬────────┬───────────┬───────────┬───────────┬─────────┬───────────┬───────────┬────────┐
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
└───────────────────────┴──────────┴────────────┴─────────┴─────┴────────┴────────┴────────┴───────────┴───────────┴───────────┴─────────┴───────────┴───────────┴────────┘

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:

# salt-cloud -f list_images my_digitalocean

┌────────────────────────┬──────────┬────────────┬─────────┬─────┬────────┬────────┬────────┬───────────┬───────────┬───────────┬─────────┬───────────┬───────────┬────────┐
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
└────────────────────────┴──────────┴────────────┴─────────┴─────┴────────┴────────┴────────┴───────────┴───────────┴───────────┴─────────┴───────────┴───────────┴────────┘
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼───────────┼───────────┼────────┤
└────────────────────────┴──────────┴────────────┴─────────┴─────┴────────┴────────┴────────┴───────────┴───────────┴───────────┴─────────┴───────────┴───────────┴────────┘

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.

Alternatively, the -L option can be passed to the Salt Bootstrap script when installing
Salt. The -L option will install salt-cloud and the required libcloud package.

This quickstart walks you through the basic steps of setting up a cloud host and defining
some virtual machines to create.

NOTE:
Salt Cloud has its own process and does not rely on the Salt Master, so it can be
installed on a standalone minion instead of your Salt Master.

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:

my-ec2:
driver: ec2
# Set the EC2 access credentials (see below)
#
id: 'HJGRYCILJLKJYG'
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
# Make sure this key is owned by root with permissions 0400.
#
private_key: /etc/salt/my_test_key.pem
keyname: my_test_key
securitygroup: default
# Optional: Set up the location of the Salt Master
#
minion:
master: saltmaster.example.com

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.

salt-cloud --list-locations <provider_name> # my-ec2 in the previous example
salt-cloud --list-images <provider_name>
salt-cloud --list-sizes <provider_name>

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:

micro_ec2:
provider: my-ec2
image: ami-d514f291
size: t1.micro

medium_ec2:
provider: my-ec2
image: ami-d514f291
size: m3.medium

large_ec2:
provider: my-ec2
image: ami-d514f291
size: m3.large

Notice that the provider in our profile matches the provider name that we defined? That is
how Salt Cloud knows how to connect to a cloud host to create a VM with these attributes.

Create VMs
VMs are created by calling salt-cloud with the following options:

salt-cloud -p <profile> <name1> <name2> ...

For example:

salt-cloud -p micro_ec2 minion1 minion2

Destroy VMs
Add a -d and the minion name you provided to destroy:

salt-cloud -d minion1 minion2

Query VMs
You can view details about the VMs you've created using --query:

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

salt/cloud/<minion_id>/<task>

For instance, the first event fired when creating an instance named web1 would look like:

salt/cloud/web1/creating

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:

{'name': 'web1',
'profile': 'ec2-centos',
'provider': 'ec2-config:ec2'}

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.

Filtering Events
When creating a VM, it is possible with certain tags to filter how much information is
sent to the event bus. The tags that can be filtered on any provider are:

• salt/cloud/<minion_id>/creating

• salt/cloud/<minion_id>/requesting

• salt/cloud/<minion_id>/created

Other providers may allow other tags to be filtered; when that is the case, the
documentation for that provider will contain more details.

To filter information, create a section in your /etc/salt/cloud file called filter_events.
Create a section for each tag that you want to filter, using the last segment of the tag.
For instance, use creating to represent salt/cloud/<minion_id>/creating:

filter_events:
creating:
keys:
- name
- profile
- provider

Any keys listed here will be added to the default keys that are already set to be
displayed for that provider. If you wish to start with a clean slate and only show the
keys specified, add another option called use_defaults and set it to False.

filter_events:
creating:
keys:
- name
- profile
- provider
use_defaults: False

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:

reactor:
- 'salt/minion/*/start':
- '/srv/reactor/custom-reactor.sls'
- 'salt/cloud/*/created':
- '/srv/reactor/cloud-alert.sls'
- 'salt/cloud/*/destroyed':
- '/srv/reactor/cloud-destroy-alert.sls'

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:

# /srv/reactor/cloud-alert.sls
new_instance_alert:
cmd.pagerduty.create_event:
- tgt: alertserver
- kwarg:
description: "New instance: {{ data['name'] }}"
details: "New cloud instance created on {{ data['provider'] }}"
service_key: 1626dead5ecafe46231e968eb1be29c4
profile: my-pagerduty-account

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:

reactor:
- 'salt/cloud/*/created':
- '/srv/reactor/startup_highstate.sls'

And the following sls file will start a highstate run on the target minion:

# /srv/reactor/startup_highstate.sls
reactor_highstate:
cmd.state.apply:
- tgt: {{ data['name'] }}

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 2017.7.0
       The proxy_merge_grains_in_module configuration variable introduced  in  2016.3,  has  been
       changed, defaulting to True.

       The connection with the remote device is kept alive by default, when the module implements
       the alive function and proxy_keep_alive is set to True. The polling interval is set  using
       the proxy_keep_alive_interval option which defaults to 1 minute.

       The  developers are also able to use the proxy_always_alive, when designing a proxy module
       flexible enough to open the connection with the remote device only when required.

   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:

          def __virtual__():
              '''
              Only work on proxy
              '''
              try:
                  if salt.utils.is_proxy() and \
                     __opts__['proxy']['proxytype'] == 'ssh_sample':
                      return __virtualname__
              except KeyError:
                  pass

              return False

       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

          def get_ip(proxy):
              '''
              Ask the remote device what IP it has
              '''
              return {'ip':proxy['proxymodulename.get_ip']()}

       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 True in the 2017.7.0 release.

   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:

       1. The proxy_connection_module (located in salt/proxy).

       2. The grains support code (located in salt/grains).

       3. Salt modules specific to the controlled device.

       4. Salt states specific to the controlled device.

   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

          base:
            dumbdevice1:
              - dumbdevice1
            dumbdevice2:
              - dumbdevice2
            dumbdevice3:
              - dumbdevice3
            dumbdevice4:
              - dumbdevice4
            dumbdevice5:
              - dumbdevice5
            dumbdevice6:
              - dumbdevice6
            dumbdevice7:
              - dumbdevice7

       /srv/pillar/dumbdevice1.sls

          proxy:
            proxytype: networkswitch
            host: 172.23.23.5
            username: root
            passwd: letmein

       /srv/pillar/dumbdevice2.sls

          proxy:
            proxytype: networkswitch
            host: 172.23.23.6
            username: root
            passwd: letmein

       /srv/pillar/dumbdevice3.sls

          proxy:
            proxytype: networkswitch
            host: 172.23.23.7
            username: root
            passwd: letmein

       /srv/pillar/dumbdevice4.sls

          proxy:
            proxytype: i2c_lightshow
            i2c_address: 1

       /srv/pillar/dumbdevice5.sls

          proxy:
            proxytype: i2c_lightshow
            i2c_address: 2

       /srv/pillar/dumbdevice6.sls

          proxy:
            proxytype: 433mhz_wireless

       /srv/pillar/dumbdevice7.sls

          proxy:
            proxytype: sms_serial
            deventry: /dev/tty04

       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

       • dumbdevices  1, 2, and 3 are network switches that have a management interface available
         at a particular IP address.

       • dumbdevices 4 and 5 are very low-level devices controlled over an i2c bus.  In this case
         the devices are physically connected to machine 'minioncontroller2', and are addressable
         on the i2c bus at their respective i2c addresses.

       • dumbdevice6  is  a  433  MHz  wireless  transmitter,  also   physically   connected   to
         minioncontroller2

       • dumbdevice7 is an SMS gateway connected to machine minioncontroller3 via a serial port.

       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.

       alive(opts): Another optional function, it is  used  together  with  the  proxy_keep_alive
       option  (default:  True). This function should return a boolean value corresponding to the
       state of the connection.  If the  connection  is  down,  will  try  to  restart  (shutdown
       followed by init). The polling frequency is controlled using the proxy_keep_alive_interval
       option, in minutes.

       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 True in the release code-named 2017.7.0.

       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.

          # -*- coding: utf-8 -*-
          '''
          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
          '''
          from __future__ import absolute_import

          # Import python libs
          import logging
          import salt.utils.http

          HAS_REST_EXAMPLE = True

          # This must be present or the Salt loader won't load this module
          __proxyenabled__ = ['rest_sample']

          # Variables are scoped to this module so we can have persistent data
          # across calls to fns in here.
          GRAINS_CACHE = {}
          DETAILS = {}

          # Want logging!
          log = logging.getLogger(__file__)

          # This does nothing, it's here just as an example and to provide a log
          # entry when the module is loaded.
          def __virtual__():
              '''
              Only return if all the modules are available
              '''
              log.debug('rest_sample proxy __virtual__() called...')
              return True

          def _complicated_function_that_determines_if_alive():
              return True

          # Every proxy module needs an 'init', though you can
          # just put DETAILS['initialized'] = True here if nothing
          # else needs to be done.

          def init(opts):
              log.debug('rest_sample proxy init() called...')
              DETAILS['initialized'] = True

              # Save the REST URL
              DETAILS['url'] = opts['proxy']['url']

              # Make sure the REST URL ends with a '/'
              if not DETAILS['url'].endswith('/'):
                  DETAILS['url'] += '/'

          def alive(opts):
              '''
              This function returns a flag with the connection state.
              It is very useful when the proxy minion establishes the communication
              via a channel that requires a more elaborated keep-alive mechanism, e.g.
              NETCONF over SSH.
              '''
              log.debug('rest_sample proxy alive() called...')
              return _complicated_function_that_determines_if_alive()

          def initialized():
              '''
              Since grains are loaded in many different places and some of those
              places occur before the proxy can be initialized, return whether
              our init() function has been called
              '''
              return DETAILS.get('initialized', False)

          def grains():
              '''
              Get the grains from the proxied device
              '''
              if not DETAILS.get('grains_cache', {}):
                  r = salt.utils.http.query(DETAILS['url']+'info', decode_type='json', decode=True)
                  DETAILS['grains_cache'] = r['dict']
              return DETAILS['grains_cache']

          def grains_refresh():
              '''
              Refresh the grains from the proxied device
              '''
              DETAILS['grains_cache'] = None
              return grains()

          def fns():
              return {'details': 'This key is here because a function in '
                                'grains/rest_sample.py called fns() here in the proxymodule.'}

          def service_start(name):
              '''
              Start a "service" on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'service/start/'+name, decode_type='json', decode=True)
              return r['dict']

          def service_stop(name):
              '''
              Stop a "service" on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'service/stop/'+name, decode_type='json', decode=True)
              return r['dict']

          def service_restart(name):
              '''
              Restart a "service" on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'service/restart/'+name, decode_type='json', decode=True)
              return r['dict']

          def service_list():
              '''
              List "services" on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'service/list', decode_type='json', decode=True)
              return r['dict']

          def service_status(name):
              '''
              Check if a service is running on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'service/status/'+name, decode_type='json', decode=True)
              return r['dict']

          def package_list():
              '''
              List "packages" installed on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'package/list', decode_type='json', decode=True)
              return r['dict']

          def package_install(name, **kwargs):
              '''
              Install a "package" on the REST server
              '''
              cmd = DETAILS['url']+'package/install/'+name
              if kwargs.get('version', False):
                  cmd += '/'+kwargs['version']
              else:
                  cmd += '/1.0'
              r = salt.utils.http.query(cmd, decode_type='json', decode=True)
              return r['dict']

          def fix_outage():
              r = salt.utils.http.query(DETAILS['url']+'fix_outage')
              return r

          def uptodate(name):

              '''
              Call the REST endpoint to see if the packages on the "server" are up to date.
              '''
              r = salt.utils.http.query(DETAILS['url']+'package/remove/'+name, decode_type='json', decode=True)
              return r['dict']

          def package_remove(name):

              '''
              Remove a "package" on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'package/remove/'+name, decode_type='json', decode=True)
              return r['dict']

          def package_status(name):
              '''
              Check the installation status of a package on the REST server
              '''
              r = salt.utils.http.query(DETAILS['url']+'package/status/'+name, decode_type='json', decode=True)
              return r['dict']

          def ping():
              '''
              Is the REST server up?
              '''
              r = salt.utils.http.query(DETAILS['url']+'ping', decode_type='json', decode=True)
              try:
                  return r['dict'].get('ret', False)
              except Exception:
                  return False

          def shutdown(opts):
              '''
              For this proxy shutdown is a no-op
              '''
              log.debug('rest_sample proxy shutdown() called...')

       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 defaults to True in the release code-named 2017.7.0.

   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:

          # -*- coding: utf-8 -*-
          '''
          Generate baseline proxy minion grains
          '''
          from __future__ import absolute_import
          import salt.utils

          __proxyenabled__ = ['rest_sample']

          __virtualname__ = 'rest_sample'

          def __virtual__():
              try:
                  if salt.utils.is_proxy() and __opts__['proxy']['proxytype'] == 'rest_sample':
                      return __virtualname__
              except KeyError:
                  pass

              return False

   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.

       1. Ideally, create a Python virtualenv in which to run the  REST  service.   This  is  not
          strictly  required,  but  without  a virtualenv you will need to install bottle via pip
          globally on your system

       2. Clone https://github.com/saltstack/salt-contrib and copy the contents of the  directory
          proxyminion_rest_example  somewhere  on a machine that is reachable from the machine on
          which you want to run the salt-proxy.  This machine needs Python 2.7 or later.

       3. Install bottle version 0.12.8 via pip or easy_install

          pip install bottle==0.12.8

       4. Run python rest.py --help for usage

       5. Start the REST API on an appropriate port and IP.

       6. Load the REST service's status page in your browser by going to the IP/port combination
          (e.g. http://127.0.0.1:8000)

       7. You  should  see  a  page  entitled  "Salt  Proxy  Minion"  with  two sections, one for
          "services" and one for "packages" and you should see a log entry in the terminal  where
          you started the REST process indicating that the index page was retrieved.
       [image]

       Now, configure your salt-proxy.

       1. Edit /etc/salt/proxy and add an entry for your master's location

          master: localhost

       2. On  your salt-master, ensure that pillar is configured properly.  Select an ID for your
          proxy (in this example we will name the proxy with the letter 'p' followed by the  port
          the proxy is answering on).  In your pillar topfile, place an entry for your proxy:

          base:
            'p8000':
              - p8000

       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)

       3. In the pillar root for your base environment, create this file:

          p8000.sls
          ---------

          proxy:
            proxytype: rest_sample
            url: http://<IP your REST listens on>:port

       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

       4. Make sure your salt-master is running.

       5. Start the salt-proxy in debug mode

          salt-proxy --proxyid=p8000 -l debug

       6. Accept your proxy's key on your salt-master

          salt-key -y -a p8000
          The following keys are going to be accepted:
          Unaccepted Keys:
          p8000
          Key for minion p8000 accepted.

       7. Now  you  should be able to ping your proxy.  When you ping, you should see a log entry
          in the terminal where the REST service is running.

          salt p8000 test.ping

       8. The REST service implements a degenerately simple pkg and service provider as well as a
          small  set of grains.  To "install" a package, use a standard pkg.install.  If you pass
          '==' and a verrsion number after the package name then the service will parse that  and
          accept that as the package's version.

       9. Try  running  salt p8000 grains.items to see what grains are available.  You can target
          proxies via grains if you like.

       10.
          You can also start and stop the available services  (apache,  redbull,  and  postgresql
          with service.start, etc.

       11.
          States can be written to target the proxy.  Feel free to experiment with them.

   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.

          # -*- coding: utf-8 -*-
          '''
          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.
          '''
          from __future__ import absolute_import

          # Import python libs
          import json
          import logging

          # Import Salt's libs
          from salt.utils.vt_helper import SSHConnection
          from salt.utils.vt import TerminalException

          # This must be present or the Salt loader won't load this module
          __proxyenabled__ = ['ssh_sample']

          DETAILS = {}

          # Want logging!
          log = logging.getLogger(__file__)

          # This does nothing, it's here just as an example and to provide a log
          # entry when the module is loaded.
          def __virtual__():
              '''
              Only return if all the modules are available
              '''
              log.info('ssh_sample proxy __virtual__() called...')

              return True

          def init(opts):
              '''
              Required.
              Can be used to initialize the server connection.
              '''
              try:
                  DETAILS['server'] = SSHConnection(host=__opts__['proxy']['host'],
                                                    username=__opts__['proxy']['username'],
                                                    password=__opts__['proxy']['password'])
                  # connected to the SSH server
                  out, err = DETAILS['server'].sendline('help')

              except TerminalException as e:
                  log.error(e)
                  return False

          def shutdown(opts):
              '''
              Disconnect
              '''
              DETAILS['server'].close_connection()

          def parse(out):
              '''
              Extract json from out.

              Parameter
                  out: Type string. The data returned by the
                  ssh command.
              '''
              jsonret = []
              in_json = False
              for ln_ in out.split('\n'):
                  if '{' in ln_:
                      in_json = True
                  if in_json:
                      jsonret.append(ln_)
                  if '}' in ln_:
                      in_json = False
              return json.loads('\n'.join(jsonret))

          def package_list():
              '''
              List "packages" by executing a command via ssh
              This function is called in response to the salt command

              ..code-block::bash
                  salt target_minion pkg.list_pkgs

              '''
              # Send the command to execute
              out, err = DETAILS['server'].sendline('pkg_list')

              # "scrape" the output and return the right fields as a dict
              return parse(out)

          def package_install(name, **kwargs):
              '''
              Install a "package" on the REST server
              '''
              cmd = 'pkg_install ' + name
              if 'version' in kwargs:
                  cmd += '/'+kwargs['version']
              else:
                  cmd += '/1.0'

              # Send the command to execute
              out, err = DETAILS['server'].sendline(cmd)

              # "scrape" the output and return the right fields as a dict
              return parse(out)

          def package_remove(name):
              '''
              Remove a "package" on the REST server
              '''
              cmd = 'pkg_remove ' + name

              # Send the command to execute
              out, err = DETAILS['server'].sendline(cmd)

              # "scrape" the output and return the right fields as a dict
              return parse(out)

   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.

       1. This walkthrough uses a custom SSH shell to provide an end to end example.   Any  other
          shells can be used too.

       2. Setup          the         proxy         command         shell         as         shown
          https://github.com/saltstack/salt-contrib/tree/master/proxyminion_ssh_example

       Now, configure your salt-proxy.

       1. Edit /etc/salt/proxy and add an entry for your master's location

          master: localhost
          multiprocessing: False

       2. On your salt-master, ensure that pillar is configured properly.  Select an ID for  your
          proxy  (in this example we will name the proxy with the letter 'p' followed by the port
          the proxy is answering on).  In your pillar topfile, place an entry for your proxy:

          base:
            'p8000':
              - p8000

       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)

       3. In the pillar root for your base environment, create this file:

          p8000.sls
          ---------

          proxy:
            proxytype: ssh_sample
            host: saltyVM
            username: salt
            password: badpass

       4. Make sure your salt-master is running.

       5. Start the salt-proxy in debug mode

          salt-proxy --proxyid=p8000 -l debug

       6. Accept your proxy's key on your salt-master

          salt-key -y -a p8000
          The following keys are going to be accepted:
          Unaccepted Keys:
          p8000
          Key for minion p8000 accepted.

       7. Now you should be able to run commands on your proxy.

          salt p8000 pkg.list_pkgs

       8. The  SSH  shell  implements  a  degenerately simple pkg.  To "install" a package, use a
          standard pkg.install.  If you pass '==' and a verrsion number after  the  package  name
          then the service will parse that and accept that as the package's version.
       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.

       1. On your salt-master, ensure that pillar is configured properly.  Select an ID for  your
          proxy  (in this example we will name the proxy 'p8000').  In your pillar topfile, place
          an entry for your proxy:

          base:
            'p8000':
              - p8000

       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)

       2. In the pillar root for your base environment, create this file:

          p8000.sls
          ---------

          proxy:
            # set proxytype for your proxymodule
            proxytype: ssh_sample
            host: saltyVM
            username: salt
            password: badpass

       This should complete the proxy setup for p8000

       3. Configure the salt_proxy beacon

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

       4. Accept your proxy's key on your salt-master

          salt-key -y -a p8000
          The following keys are going to be accepted:
          Unaccepted Keys:
          p8000
          Key for minion p8000 accepted.

       5. Now you should be able to run commands on your proxy.

          salt p8000 pkg.list_pkgs
       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.

       1. On your salt-master, ensure that pillar is configured properly.  Select an ID for  your
          proxy  (in this example we will name the proxy 'p8000').  In your pillar topfile, place
          an entry for your proxy:

          base:
            'p8000':
              - p8000

       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)

       2. In the pillar root for your base environment, create this file:

          p8000.sls
          ---------

          proxy:
            # set proxytype for your proxymodule
            proxytype: ssh_sample
            host: saltyVM
            username: salt
            password: badpass

       3. Create the following state in your state tree (let's name it salt_proxy.sls)

          salt-proxy-configure:
            salt_proxy.configure_proxy:
              - proxyname: p8000
              - start: True # start the process if it isn't running

       4. Make sure your salt-master and salt-minion are running.

       5. Run the state salt_proxy on the minion where you want to run salt-proxy

       Example using state.sls to configure and run salt-proxy

          # salt device_minion state.sls salt_proxy

       This starts salt-proxy on device_minion

       6. Accept your proxy's key on your salt-master

          salt-key -y -a p8000
          The following keys are going to be accepted:
          Unaccepted Keys:
          p8000
          Key for minion p8000 accepted.

       7. Now you should be able to run commands on your proxy.

          salt p8000 pkg.list_pkgs

   ESXi Proxy Minion
       New in version 2015.8.4.

       NOTE:
          This  tutorial  assumes basic knowledge of Salt. To get up to speed, check out the Salt
          Walkthrough.

          This tutorial also assumes a basic understanding  of  Salt  Proxy  Minions.  If  you're
          unfamiliar  with  Salt's  Proxy  Minion  system,  please  read  the  Salt  Proxy Minion
          documentation and the Salt Proxy Minion End-to-End Example tutorial.

          The third  assumption  that  this  tutorial  makes  is  that  you  also  have  a  basic
          understanding  of  ESXi  hosts. You can learn more about ESXi hosts on VMware's various
          resources.

       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:
          Be aware that some functionality for the ESXi Proxy Minion may depend on  the  type  of
          license attached the ESXi host(s).

          For  example,  certain  services  are  only  available  to  manipulate service state or
          policies with a VMware vSphere Enterprise or Enterprise Plus license, while others  are
          available with a Standard license. The ntpd service is restricted to an Enterprise Plus
          license, while ssh is available via the Standard license.

          Please see the vSphere Comparison page for more information.

   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:

          pip install pyVmomi

       NOTE:
          Version 6.0 of pyVmomi has some problems with SSL error handling on certain versions of
          Python. If using version 6.0 of pyVmomi, the machine that you  are  running  the  proxy
          minion process from must have either Python 2.6, Python 2.7.9, or newer. This is due to
          an upstream dependency in pyVmomi 6.0 that is not supported in Python  version  2.7  to
          2.7.8.  If  the  version  of  Python  running the proxy process is not in the supported
          range, you will need to install an earlier version of pyVmomi.  See  Issue  #29537  for
          more information.

       Based  on  the  note  above,  to  install  an  earlier version of pyVmomi than the version
       currently listed in PyPi, run the following:

          pip install pyVmomi==5.5.0.2014.1.1

       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:

          esxcli -s <host-location> -u <username> -p <password> system syslog config get

       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:

          # /etc/salt/proxy

          master: <salt-master-location>

   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:

          proxy:
            proxytype: esxi
            host: <ip or dns name of esxi host>
            username: <ESXi username>
            passwords:
              - first_password
              - second_password
              - third_password

       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 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:
          When a password is changed on the host to one in the list of  possible  passwords,  the
          further  down  on the list the password is, the longer individual commands will take to
          return. This is due to the nature of pyVmomi's login system. We have to  wait  for  the
          first attempt to fail before trying the next password on the list.

          This  scenario is especially true, and even slower, when the proxy minion first starts.
          If the correct password is not the first password on the list, it  may  take  up  to  a
          minute  for  test.ping to respond with a True result. Once the initial authorization is
          complete, the responses for commands will be a little faster.

          To avoid these longer waiting periods, SaltStack recommends moving the correct password
          to the top of the list and restarting the proxy minion at your earliest convenience.

   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:

          # /etc/salt/proxy

          master: <salt-master-location>

       Pillar Top File:

          # /srv/pillar/top.sls

          base:
            'esxi-1':
              - esxi-1
            'esxi-2':
              - esxi-2

       Pillar Config File for the first ESXi host, esxi-1:

          # /srv/pillar/esxi-1.sls

          proxy:
            proxytype: esxi
            host: esxi-1.example.com
            username: 'root'
            passwords:
              - bad-password-1
              - backup-bad-password-1

       Pillar Config File for the second ESXi host, esxi-2:

          # /srv/pillar/esxi-2.sls

          proxy:
            proxytype: esxi
            host: esxi-2.example.com
            username: 'root'
            passwords:
              - bad-password-2
              - backup-bad-password-2

   Starting the Proxy Minion
       Once all of the correct configuration files are in place, it is time to  start  the  proxy
       processes!

       1. First, make sure your Salt Master is running.

       2. Start  the  first  Salt Proxy, in debug mode, by giving the Proxy Minion process and ID
          that matches the config file name created in the Configuration section.

          salt-proxy --proxyid='esxi-1' -l debug

       1. Accept the esxi-1 Proxy Minion's key on the Salt Master:

          # salt-key -L
          Accepted Keys:
          Denied Keys:
          Unaccepted Keys:
          esxi-1
          Rejected Keys:
          #
          # salt-key -a esxi-1
          The following keys are going to be accepted:
          Unaccepted Keys:
          esxi-1
          Proceed? [n/Y] y
          Key for minion esxi-1 accepted.

       1. Repeat for the second Salt Proxy, this time we'll run the proxy process as a daemon, as
          an example.

          salt-proxy --proxyid='esxi-2' -d

       1. Accept the esxi-2 Proxy Minion's key on the Salt Master:

          # salt-key -L
          Accepted Keys:
          esxi-1
          Denied Keys:
          Unaccepted Keys:
          esxi-2
          Rejected Keys:
          #
          # salt-key -a esxi-1
          The following keys are going to be accepted:
          Unaccepted Keys:
          esxi-2
          Proceed? [n/Y] y
          Key for minion esxi-1 accepted.

       1. Check and see if your Proxy Minions are responding:

          # salt 'esxi-*' test.ping
          esxi-1:
              True
          esxi-3:
              True

   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:

          salt 'esxi-*' esxi.cmd system_info
          salt 'exsi-*' esxi.cmd get_service_running service_name='ssh'

   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.

          # /srv/salt/configure-esxi.sls

          configure-host-ssh:
            esxi.ssh_configured:
              - service_running: True
              - ssh_key_file: /etc/salt/ssh_keys/my_key.pub
              - service_policy: 'automatic'
              - service_restart: True
              - certificate_verify: True

          configure-host-coredump:
            esxi.coredump_configured:
              - enabled: True
              - dump_ip: 'my-coredump-ip.example.com'

          configure-host-syslog:
            esxi.syslog_configured:
              - syslog_configs:
                  loghost: ssl://localhost:5432,tcp://10.1.0.1:1514
                  default-timeout: 120
              - firewall: True
              - reset_service: True
              - reset_syslog_config: True
              - reset_configs: loghost,default-timeout

          configure-host-ntp:
            esxi.ntp_configured:
              - service_running: True
              - ntp_servers:
                - 192.174.1.100
                - 192.174.1.200
              - service_policy: 'automatic'
              - service_restart: True

          configure-vmotion:
            esxi.vmotion_configured:
              - enabled: True

          configure-host-vsan:
            esxi.vsan_configured:
              - enabled: True
              - add_disks_to_vsan: True

          configure-host-password:
            esxi.password_present:
              - password: 'new-bad-password'

       States  are  called via the ESXi Proxy Minion just as they would on a regular minion.  For
       example:

          salt 'esxi-*' state.sls configure-esxi test=true
          salt 'esxi-*' state.sls configure-esxi

   Relevant Salt Files and Resources
       • ESXi Proxy Minion

       • ESXi Execution Module

       • ESXi State Module

       • Salt Proxy Minion Docs

       • Salt Proxy Minion End-to-End Example

       • vSphere Execution Module

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:

       • Virtual machine deployment

       • Inspection of deployed VMs

       • Virtual machine migration

       • Network profiling

       • Automatic VM integration with all aspects of Salt

       • Image Pre-seeding

       Many features are currently under development to enhance the capabilities of the Salt Virt
       systems.

       NOTE:
          It is noteworthy that Salt was originally developed with the intent of using  the  Salt
          communication  system  as the backbone to a cloud controller.  This means that the Salt
          Virt system is not an afterthought, simply a system that took the back  seat  to  other
          development.  The  original  attempt to develop the cloud control aspects of Salt was a
          project called butter.  This project never took off, but was functional and proves  the
          early viability of Salt to be a cloud controller.

       WARNING:
          Salt  Virt  does  not work with KVM that is running in a VM. KVM must be running on the
          base hardware.

   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:

          virt.disk:
            default:
              - system:
                size: 8192
                format: qcow2
                model: virtio

       NOTE:
          The format and model does not need to be defined, Salt  will  default  to  the  optimal
          format  used  by  the  underlying  hypervisor,  in the case of kvm this it is qcow2 and
          virtio.

       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:

          virt.disk:
            default:
              - system:
                  size: 8192
            database:
              - system:
                  size: 8192
              - data:
                  size: 30720
            web:
              - system:
                  size: 1024
              - logs:
                  size: 5120

       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:

          virt.nic:
            default:
              eth0:
                bridge: br0
                model: virtio

       NOTE:
          The  model  does not need to be defined, Salt will default to the optimal model used by
          the underlying hypervisor, in the case of kvm this model is virtio

       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:

          virt.nic:
            dual:
              eth0:
                bridge: service_br
              eth1:
                bridge: storage_br
            single:
              eth0:
                bridge: service_br
            triple:
              eth0:
                bridge: service_br
              eth1:
                bridge: storage_br
              eth2:
                bridge: dmz_br
            all:
              eth0:
                bridge: service_br
              eth1:
                bridge: storage_br
              eth2:
                bridge: dmz_br
              eth3:
                bridge: database_br
            dmz:
              eth0:
                bridge: service_br
              eth1:
                bridge: dmz_br
            database:
              eth0:
                bridge: service_br
              eth1:
                bridge: database_br

       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 libvirt python module and the certtool binary are required.

       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:
          Libguestfs and qemu-nbd allow for virtual machine images to be mounted  before  startup
          and get pre-seeded with configurations and a salt minion

       This  sls will set up the needed software for a hypervisor, and run the routines to set up
       the libvirt pki keys.

       NOTE:
          Package names and setup used is Red Hat  specific,  different  package  names  will  be
          required for different platforms

          libvirt:
            pkg.installed: []
            file.managed:
              - name: /etc/sysconfig/libvirtd
              - contents: 'LIBVIRTD_ARGS="--listen"'
              - require:
                - pkg: libvirt
            virt.keys:
              - require:
                - pkg: libvirt
            service.running:
              - name: libvirtd
              - require:
                - pkg: libvirt
                - network: br0
                - libvirt: libvirt
              - watch:
                - file: libvirt

          libvirt-python:
            pkg.installed: []

          libguestfs:
            pkg.installed:
              - pkgs:
                - libguestfs
                - libguestfs-tools

   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:

          eth0:
            network.managed:
              - enabled: True
              - type: eth
              - bridge: br0

          br0:
            network.managed:
              - enabled: True
              - type: bridge
              - proto: dhcp
              - require:
                - network: 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:
          To use more advanced networking in Salt Virt, read the Salt Virt Networking document:

          Salt Virt Networking

   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:
          The above formula includes the calls needed to set up libvirt keys.

          libvirt_keys:
            virt.keys

   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:

       kiwi: (openSUSE, SLES, RHEL, CentOS)
              https://suse.github.io/kiwi/

       vm-builder:
              https://wiki.debian.org/VMBuilder

              SEE ALSO:
                 vmbuilder-formula

       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 using the virt runner.

       Start by running a Salt Virt hypervisor info command:

          salt-run virt.host_info

       This will query the running hypervisor(s) for stats and display useful information such as
       the number of cpus and amount of memory.

       You can also list all VMs and their current states on all hypervisor nodes:

          salt-run virt.list

       Now that hypervisors are available a virtual machine can be  provisioned.   The  virt.init
       routine will create a new virtual machine:

          salt-run virt.init centos1 2 512 salt://centos.img

       The  Salt Virt runner will now automatically select a hypervisor to deploy the new virtual
       machine on. Using salt:// assumes that the CentOS virtual machine image is located in  the
       root of the file-server on the master.  When images are cloned (i.e. copied locatlly after
       retrieval from the file server) the destination directory  on  the  hypervisor  minion  is
       determined by the virt.images config option; by default this is /srv/salt/salt-images/.

       When  a  VM  is  initialized  using  virt.init the image is copied to the hypervisor using
       cp.cache_file and will be mounted and seeded  with  a  minion.  Seeding  includes  setting
       pre-authenticated  keys on the new machine. A minion will only be installed if one can not
       be found on the image using the default arguments to seed.apply.

       NOTE:
          The biggest bottleneck in starting VMs is when the Salt Minion needs to  be  installed.
          Making sure that the source VM images already have Salt installed will GREATLY speed up
          virtual machine deployment.

       You can also deploy an image on a particular minion by directly calling the virt execution
       module with an absolute image path. This can be quite handy for testing:

          salt 'hypervisor*' virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.img

       Now that the new VM has been prepared, it can be seen via the virt.query command:

          salt-run virt.query

       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.

   QEMU copy on write support
       For  fast image cloning you can use the qcow disk image format.  Pass the enable_qcow flag
       and a .qcow2 image path to virt.init:

          salt 'hypervisor*' virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.qcow2 enable_qcow=True start=False

       NOTE:
          Beware that attempting to boot a qcow image too quickly after cloning can result  in  a
          race  condition  where  libvirt  may  try  to boot the machine before image seeding has
          completed. For that reason it is recommended to also pass start=False to virt.init.

          Also know that you must not modify the original base image without first making a  copy
          and then rebasing all overlay images onto it.  See the qemu-img rebase usage docs.

   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:

          iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 16514 -j ACCEPT

       NOTE:
          More  in-depth  information  regarding distribution specific firewall settings can read
          in:

          Opening the Firewall up for Salt

       Salt also needs the virt.tunnel option 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:

          virt.tunnel: True

       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:

          salt \* saltutil.refresh_modules

       Now,  migration  routines  can  be  run! To migrate a VM, simply run the Salt Virt migrate
       routine:

          salt-run virt.migrate centos <new hypervisor>

   VNC Consoles
       Although not enabled by default, Salt Virt can also  set  up  VNC  consoles  allowing  for
       remote  visual  consoles  to be opened up. When creating a new VM using virt.init pass the
       enable_vnc=True parameter to have a console configured for the new VM.

       The information from a virt.query routine will  display  the  vnc  console  port  for  the
       specific vms:

          centos
            CPU: 2
            Memory: 524288
            State: running
            Graphics: vnc - hyper6:5900
            Disk - vda:
              Size: 2.0G
              File: /srv/salt-images/ubuntu2/system.qcow2
              File Format: qcow2
            Nic - ac:de:48:98:08:77:
              Source: br0
              Type: bridge

       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:

          vncviewer hyper6:5900

       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
salt-call [options]

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:
salt-call commands execute from the current user's shell context, while salt commands
execute from the system's default context.

Options
--version
Print the version of Salt that is running.

--versions-report
Show program's dependencies and version number, and then exit

-h, --help
Show the help message and exit

--hard-crash
Raise any original exception rather than exiting gracefully Default: False

-g, --grains
Return the information generated by the Salt grains

-m MODULE_DIRS, --module-dirs=MODULE_DIRS
Specify an additional directory to pull modules from. Multiple directories can be
provided by passing -m /--module-dirs multiple times.

-d, --doc, --documentation
Return the documentation for the specified module or for all modules if none are
specified

--master=MASTER
Specify the master to use. The minion must be authenticated with the master. If
this option is omitted, the master options from the minion config will be used. If
multi masters are set up the first listed master that responds will be used.

--return RETURNER
Set salt-call to pass the return data to one or many returner interfaces. To use
many returner interfaces specify a comma delimited list of returners.

--local
Run salt-call locally, as if there was no master running.

--file-root=FILE_ROOT
Set this directory as the base file root.

--pillar-root=PILLAR_ROOT
Set this directory as the base pillar root.

--retcode-passthrough
Exit with the salt call retcode and not the salt binary retcode

--metadata
Print out the execution metadata as well as the return. This will print out the
outputter data, the return code, etc.

--id=ID
Specify the minion id to use. If this option is omitted, the id option from the
minion config will be used.

--skip-grains
Do not load grains.

--refresh-grains-cache
Force a refresh of the grains cache

Logging Options
Logging options which override any settings defined on the configuration files.

-l LOG_LEVEL, --log-level=LOG_LEVEL
Console logging log level. One of all, garbage, trace, debug, info, warning, error,
quiet. Default: warning.

--log-file=LOG_FILE
Log file path. Default: /var/log/salt/minion.

--log-file-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of all, garbage, trace, debug, info, warning, error,
quiet. Default: warning.

Some outputters are formatted only for data returned from specific functions; for
instance, the grains outputter will not work for non-grains data.

If an outputter is used that does not support the data passed into it, then Salt
will fall back on the pprint outputter and display the return data using the Python
pprint standard library module.

--out-file=OUTPUT_FILE, --output-file=OUTPUT_FILE
Write the output to the specified file.

--out-file-append, --output-file-append
Append the output to the specified file.

--no-color
Disable all colored output

--force-color
Force colored output

NOTE:
When using colored output the color codes are as follows:

green denotes success, red denotes failure, blue denotes changes and success and
yellow denotes a expected future change in configuration.

--state-output=STATE_OUTPUT, --state_output=STATE_OUTPUT
Override the configured state_output value for minion output. One of 'full',
'terse', 'mixed', 'changes' or 'filter'. Default: 'none'.

--state-verbose=STATE_VERBOSE, --state_verbose=STATE_VERBOSE
Override the configured state_verbose value for minion output. Set to True or
False. Default: none.

See also
salt(1) salt-master(1) salt-minion(1)

salt
salt
Synopsis
salt '*' [ options ] sys.doc

salt -E '.*' [ options ] sys.doc cmd

salt -G 'os:Arch.*' [ options ] test.ping

salt -C 'G@os:Arch.* and webserv* or G@kernel:FreeBSD' [ options ] test.ping

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
--version
Print the version of Salt that is running.

--versions-report
Show program's dependencies and version number, and then exit

-h, --help
Show the help message and exit

-t TIMEOUT, --timeout=TIMEOUT
The timeout in seconds to wait for replies from the Salt minions. The timeout
number specifies how long the command line client will wait to query the minions
and check on running jobs. Default: 5

-s, --static
By default as of version 0.9.8 the salt command returns data to the console as it
is received from minions, but previous releases would return data only after all
data was received. Use the static option to only return the data with a hard
timeout and after all minions have returned. Without the static option, you will
get a separate JSON string per minion which makes JSON output invalid as a whole.

--async
Instead of waiting for the job to run on minions only print the job id of the
started execution and complete.

--state-output=STATE_OUTPUT
New in version 0.17.

Override the configured state_output value for minion output. One of full, terse,
mixed, changes or filter. Default: full.

--subset=SUBSET
Execute the routine on a random subset of the targeted minions. The minions will
be verified that they have the named function before executing. The SUBSET argument
is the count of the minions to target.

-v VERBOSE, --verbose
Turn on verbosity for the salt call, this will cause the salt command to print out
extra data like the job id.

--hide-timeout
Instead of showing the return data for all minions. This option prints only the
online minions which could be reached.

-b BATCH, --batch-size=BATCH
Instead of executing on all targeted minions at once, execute on a progressive set
of minions. This option takes an argument in the form of an explicit number of
minions to execute at once, or a percentage of minions to execute on.

-a EAUTH, --auth=EAUTH
Pass in an external authentication medium to validate against. The credentials will
be prompted for. The options are auto, keystone, ldap, pam, and stormpath. Can be
used with the -T option.

-T, --make-token
Used in conjunction with the -a option. This creates a token that allows for the
authenticated user to send commands without needing to re-authenticate.

--return=RETURNER
Choose an alternative returner to call on the minion, if an alternative returner is
used then the return will not come back to the command line but will be sent to the
specified return system. The options are carbon, cassandra, couchbase, couchdb,
elasticsearch, etcd, hipchat, local, local_cache, memcache, mongo, mysql, odbc,
postgres, redis, sentry, slack, sms, smtp, sqlite3, syslog, and xmpp.

-d, --doc, --documentation
Return the documentation for the module functions available on the minions

--args-separator=ARGS_SEPARATOR
Set the special argument used as a delimiter between command arguments of compound
commands. This is useful when one wants to pass commas as arguments to some of the
commands in a compound command.

Logging Options
Logging options which override any settings defined on the configuration files.

-l LOG_LEVEL, --log-level=LOG_LEVEL
Console logging log level. One of all, garbage, trace, debug, info, warning, error,
quiet. Default: warning.

--log-file=LOG_FILE
Log file path. Default: /var/log/salt/master.

--log-file-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of all, garbage, trace, debug, info, warning, error,
quiet. Default: warning.

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.

-E, --pcre
The target expression will be interpreted as a PCRE regular expression rather than
a shell glob.

-L, --list
The target expression will be interpreted as a comma-delimited list; example:
server1.foo.bar,server2.foo.bar,example7.quo.qux

-G, --grain
The target expression matches values returned by the Salt grains system on the
minions. The target expression is in the format of '<grain value>:<glob
expression>'; example: 'os:Arch*'

This was changed in version 0.9.8 to accept glob expressions instead of regular
expression. To use regular expression matching with grains, use the --grain-pcre
option.

--grain-pcre
The target expression matches values returned by the Salt grains system on the
minions. The target expression is in the format of '<grain value>:< regular
expression>'; example: 'os:Arch.*'

-N, --nodegroup
Use a predefined compound target defined in the Salt master configuration file.

-R, --range
Instead of using shell globs to evaluate the target, use a range expression to
identify targets. Range expressions look like %cluster.

Using the Range option requires that a range server is set up and the location of
the range server is referenced in the master configuration file.

-C, --compound
Utilize many target definitions to make the call very granular. This option takes a
group of targets separated by and or or. The default matcher is a glob as usual. If
something other than a glob is used, preface it with the letter denoting the type;
example: 'webserv* and G@os:Debian or E@db*' Make sure that the compound target is
encapsulated in quotes.

-I, --pillar
Instead of using shell globs to evaluate the target, use a pillar value to identify
targets. The syntax for the target is the pillar key followed by a glob expression:
"role:production*"

-S, --ipcidr
Match based on Subnet (CIDR notation) or IPv4 address.

Some outputters are formatted only for data returned from specific functions; for
instance, the grains outputter will not work for non-grains data.

If an outputter is used that does not support the data passed into it, then Salt
will fall back on the pprint outputter and display the return data using the Python
pprint standard library module.

--out-file=OUTPUT_FILE, --output-file=OUTPUT_FILE
Write the output to the specified file.

--out-file-append, --output-file-append
Append the output to the specified file.

--no-color
Disable all colored output

--force-color
Force colored output

NOTE:
When using colored output the color codes are as follows:

green denotes success, red denotes failure, blue denotes changes and success and
yellow denotes a expected future change in configuration.

--state-output=STATE_OUTPUT, --state_output=STATE_OUTPUT
Override the configured state_output value for minion output. One of 'full',
'terse', 'mixed', 'changes' or 'filter'. Default: 'none'.

--state-verbose=STATE_VERBOSE, --state_verbose=STATE_VERBOSE
Override the configured state_verbose value for minion output. Set to True or
False. Default: none.

See also
salt(7) salt-master(1) salt-minion(1)

salt-cloud
salt-cp
salt-cp
Copy a file or files to one or more minions

Synopsis
salt-cp '*' [ options ] SOURCE [SOURCE2 SOURCE3 ...] DEST

salt-cp -E '.*' [ options ] SOURCE [SOURCE2 SOURCE3 ...] DEST

salt-cp -G 'os:Arch.*' [ options ] SOURCE [SOURCE2 SOURCE3 ...] DEST

Description
salt-cp copies files from the master to all of the Salt minions matched by the specified
target expression.

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
master or minion is running with debug logging, the contents of the file will be logged
to disk.

In addition, this tool is less efficient than the Salt fileserver when copying larger
files. It is recommended to instead use cp.get_file to copy larger files to minions.
However, this requires the file to be located within one of the fileserver directories.

Changed in version 2016.3.7,2016.11.6,2017.7.0: Compression support added, disable with
-n. Also, if the destination path ends in a path separator (i.e. /, or \ on Windows, the
desitination will be assumed to be a directory. Finally, recursion is now supported,
allowing for entire directories to be copied.

Changed in version 2016.11.7,2017.7.2: Reverted back to the old copy mode to preserve
backward compatibility. The new functionality added in 2016.6.6 and 2017.7.0 is now
available using the -C or --chunked CLI arguments. Note that compression, recursive
copying, and support for copying large files is only available in chunked mode.