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

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: /var/run/salt-master.pid │ pidfile: │
│ │ 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
file_roots
┌───────────────┬──────────────────────┐
│ Linux Paths │ Windows Paths │
├───────────────┼──────────────────────┤
│ /srv/salt │ c:\salt\srv\salt │
├───────────────┼──────────────────────┤
│ /srv/spm/salt │ c:\salt\srv\spm\salt │
└───────────────┴──────────────────────┘

pillar_roots
┌─────────────────┬────────────────────────┐
│ Linux Paths │ Windows Paths │
├─────────────────┼────────────────────────┤
│ /srv/pillar │ c:\salt\srv\pillar │
├─────────────────┼────────────────────────┤
│ /srv/spm/pillar │ c:\salt\srv\spm\pillar │
└─────────────────┴────────────────────────┘

Win Repo Settings
┌───────────────────────────────────────┬──────────────────────────────┐
│ Linux Paths │ Windows Paths │
├───────────────────────────────────────┼──────────────────────────────┤
│ winrepo_dir: /srv/salt/win/repo │ winrepo_dir: │
│ │ c:\salt\srv\salt\win\repo │
├───────────────────────────────────────┼──────────────────────────────┤
│ winrepo_dir_ng: /srv/salt/win/repo-ng │ winrepo_dir_ng: │
│ │ c:\salt\srv\salt\win\repo-ng │
└───────────────────────────────────────┴──────────────────────────────┘

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

SEE ALSO:
example minion configuration file

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

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

Minion Primary Configuration
master
Default: salt

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

Default: salt

master: salt

master:port Syntax
New in version 2015.8.0.

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

master: localhost:1234

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

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

NOTE:
If a port is specified in the master as well as master_port, the master_port setting will be
overridden by the master configuration.

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

master:
- address1
- address2

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

master: module.function
master_type: func

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

master:
- address1
- address2
master_type: failover

ipv6
Default: None

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

ipv6: True

master_uri_format
New in version 2015.8.0.

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

master_uri_format: ip_only

master_type
New in version 2014.7.0.

Default: str

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

master_type: failover

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

master_type: func

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

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

master_type: disable

max_event_size
New in version 2014.7.0.

Default: 1048576

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

max_event_size: 1048576

master_failback
New in version 2016.3.0.

Default: False

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

master_failback: False

master_failback_interval
New in version 2016.3.0.

Default: 0

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

master_failback_interval: 0

master_alive_interval
Default: 0

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

master_alive_interval: 30

master_shuffle
New in version 2014.7.0.

Default: False

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

master_shuffle: True

random_master
Default: False

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

random_master: True

retry_dns
Default: 30

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

retry_dns: 30

master_port
Default: 4506

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

master_port: 4506

publish_port
Default: 4505

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

publish_port: 4505

user
Default: root

The user to run the Salt processes

user: root

sudo_user
Default: ''

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

sudo_user: root

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

The location of the daemon's process ID file

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

root_dir
Default: /

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

root_dir: /

conf_file
Default: /etc/salt/minion

The path to the minion's configuration file.

conf_file: /etc/salt/minion

pki_dir
Default: /etc/salt/pki/minion

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

pki_dir: /etc/salt/pki/minion

id
Default: the system's hostname

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
                    ┌──────────────────────────────────────┬─────────────────────────────────────┐
                    │                                      │                                     │
--

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
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Functions AWS CloudStack Digital EC2 GoGrid JoyEnt Linode OpenStack Parallels Rackspace Saltify Softlayer Softlayer Aliyun
(Legacy) Ocean (Legacy) Hardware
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
block_device_mappings Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
create_keypair Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
create_volume Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
delete_key Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
delete_keypair Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
delete_volume Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_image Yes Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_ip Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_key Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_keyid Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_keypair Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_networkid Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_node Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_password Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_size Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_spot_config Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
get_subnetid Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
iam_profile Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
import_key Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
key_list Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
keyname Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
list_availability_zones Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
list_custom_images Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
list_keys Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
list_nodes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
list_nodes_full Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
list_nodes_select Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
list_vlans Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
rackconnect Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
reboot Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
reformat_node Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
securitygroup Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
securitygroupid Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
show_image Yes Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
show_key Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
show_keypair Yes Yes
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
show_volume Yes Yes
┌─────────────────────────┬──────────┬────────────┬─────────┬─────┬────────┬────────┬────────┬───────────┬───────────┬───────────┬─────────┬───────────┬───────────┬────────┐
│ Tutorials │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ Salt Cloud Quickstart │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
--

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