Ubuntu Manpage: salt - Salt Documentation

Provided by: salt-doc_2018.3.4+dfsg1-6ubuntu1_all

NAME

       salt - Salt Documentation

INTRODUCTION TO SALT

We’re not just talking about NaCl..SS The 30 second summary

Salt is:

· a configuration management system, capable of maintaining remote nodes in defined states
(for example, ensuring that specific packages are installed and specific services are
running)

· a distributed remote execution system used to execute commands and query data on remote
nodes, either individually or by arbitrary selection criteria

It was developed in order to bring the best solutions found in the world of remote
execution together and make them better, faster, and more malleable. Salt accomplishes
this through its ability to handle large loads of information, and not just dozens but
hundreds and even thousands of individual servers quickly through a simple and manageable
interface.

Simplicity
Providing versatility between massive scale deployments and smaller systems may seem
daunting, but Salt is very simple to set up and maintain, regardless of the size of the
project. The architecture of Salt is designed to work with any number of servers, from a
handful of local network systems to international deployments across different data
centers. The topology is a simple server/client model with the needed functionality built
into a single set of daemons. While the default configuration will work with little to no
modification, Salt can be fine tuned to meet specific needs.

Parallel execution
The core functions of Salt:

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

· use a secure and encrypted protocol

· use the smallest and fastest network payloads possible

· provide a simple programming interface

Salt also introduces more granular controls to the realm of remote execution, allowing
systems to be targeted not just by hostname, but also by system properties.

Builds on proven technology
Salt takes advantage of a number of technologies and techniques. The networking layer is
built with the excellent ZeroMQ networking library, so the Salt daemon includes a viable
and transparent AMQ broker. Salt uses public keys for authentication with the master
daemon, then uses faster AES encryption for payload communication; authentication and
encryption are integral to Salt. Salt takes advantage of communication via msgpack,
enabling fast and light network traffic.

Python client interface
In order to allow for simple expansion, Salt execution routines can be written as plain
Python modules. The data collected from Salt executions can be sent back to the master
server, or to any arbitrary program. Salt can be called from a simple Python API, or from
the command line, so that Salt can be used to execute one-off commands as well as operate
as an integral part of a larger application.

Fast, flexible, scalable
The result is a system that can execute commands at high speed on target server groups
ranging from one to very many servers. Salt is very fast, easy to set up, amazingly
malleable and provides a single remote execution architecture that can manage the diverse
requirements of any number of servers. The Salt infrastructure brings together the best
of the remote execution world, amplifies its capabilities and expands its range, resulting
in a system that is as versatile as it is practical, suitable for any network.

Open
Salt is developed under the Apache 2.0 license, and can be used for open and proprietary
projects. Please submit your expansions back to the Salt project so that we can all
benefit together as Salt grows. Please feel free to sprinkle Salt around your systems and
let the deliciousness come forth.

Salt Community
Join the Salt!

There are many ways to participate in and communicate with the Salt community.

Salt has an active IRC channel and a mailing list.

Mailing List
Join the salt-users mailing list. It is the best place to ask questions about Salt and see
whats going on with Salt development! The Salt mailing list is hosted by Google Groups. It
is open to new members.

IRC
The #salt IRC channel is hosted on the popular Freenode network. You can use the Freenode
webchat client right from your browser.

Logs of the IRC channel activity are being collected courtesy of Moritz Lenz.

If you wish to discuss the development of Salt itself join us in #salt-devel.

Follow on Github
The Salt code is developed via Github. Follow Salt for constant updates on what is
happening in Salt development:

https://github.com/saltstack/salt

Blogs
SaltStack Inc. keeps a blog with recent news and advancements:

http://www.saltstack.com/blog/

Example Salt States
The official salt-states repository is: https://github.com/saltstack/salt-states

A few examples of salt states from the community:

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

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

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

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

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

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

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

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

Follow on ohloh
https://www.ohloh.net/p/salt

Other community links
· Salt Stack Inc.

· Subreddit

· Google+

· YouTube

· Facebook

· Twitter

· Wikipedia page

Hack the Source
If you want to get involved with the development of source code or the documentation
efforts, please review the contributing 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 Debian release contains old
outdated Salt releases. It is recommended to use SaltStack repository for Debian as
described below.

Installation from official Debian and Raspbian repositories is described here.

Installation from the Official SaltStack Repository
Packages for Debian 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
The Debian distributions contain mostly old Salt packages built by the Debian Salt Team.
You can install Salt components directly from Debian but it is recommended to use the
instructions above for the packages from the official Salt repository.

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

To install fresh release of Salt minion on Jessie:

1. Add jessie-backports and stretch repositories:

Debian:

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

Raspbian:

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

2. Make Jessie a default release:

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

3. Install Salt dependencies:

Debian:

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

Raspbian:

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

4. Install Salt minion package from Latest Debian Release:

apt-get install salt-minion/stretch

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

· apt-get install salt-api

· apt-get install salt-cloud

· apt-get install salt-master

· apt-get install salt-minion

· apt-get install salt-ssh

· apt-get install salt-syndic

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

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

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

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

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

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

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

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

Install the Extension
Copy the Salt package to extension

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

Install the SWIX

veos#extension salt-eos-latest.swix force

Verify the installation

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

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

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

Make sure you enable the eAPI with unix-socket

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

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

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

salt-minion should be running

Copy the installed extensions to boot-extensions

veos#copy installed-extensions boot-extensions

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

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

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

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

1. Remove the extension from boot-extensions

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

2. Remove the extension from extensions folder

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

2. Remove boot-up script

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

Additional Information
This SWIX extension contains the following RPM packages:

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

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

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

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

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

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

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

yum install salt-master
yum install salt-minion

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

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

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

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

Installing from pip has a few additional requirements:

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

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

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

Installation from pip:

pip install salt

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

Post-installation tasks
Master

To have the Master start automatically at boot time:

systemctl enable salt-master.service

To start the Master:

systemctl start salt-master.service

Minion

To have the Minion start automatically at boot time:

systemctl enable salt-minion.service

To start the Minion:

systemctl start salt-minion.service

Now go to the Configuring Salt page.

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

NOTE:
Packages in this repository 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.

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.

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 commercial 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
If the system is missing the appropriate version of the Visual C++ Redistributable
(vcredist) the user will be prompted to install it. Click OK to install the vcredist.
Click Cancel to abort the installation without making modifications to the system.

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

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

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

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

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

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

sc start salt-minion
net start salt-minion

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

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

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

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

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

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

Here are some examples of using the silent installer:

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

Salt-Minion-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

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

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

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

· These instructions were tested with Windows Server 2008 R2

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

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

2. Click Add or remove user accounts.

3. Click Create new account.

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

5. Select the Standard user radio button.

6. Click the Create Account button.

7. Click on the newly created user account.

8. Click the Create a password link.

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

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

11. Click the Create password button.

12. Close the Change an Account window.

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

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

3. Click on the Security tab.

4. Click the Edit button.

5. Click the Add button.

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

7. Check the box to Allow the Modify permission.

8. Click the OK button.

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

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

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

3. Click the Log On tab.

4. Click the This account radio button.

5. Provide the account credentials created in section A.

6. Click the OK button.

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

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

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

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

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

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

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

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

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

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

Prerequisite Software
The only prerequisite is Git for Windows.

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

Open a command line and type:

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

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

cd salt
git checkout 2017.7.2

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

cd pkg\windows
powershell -file build_env_2.ps1

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

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

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

Set-ExecutionPolicy RemoteSigned

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

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

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

NOTE:
The . is important

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cd salt
git checkout 2017.7.2

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

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

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

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

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

3. Edit C:\salt\conf\minion

master: ipaddress or hostname of your salt-master

4. Start the salt-minion

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

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

sudo salt-key -A

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

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

sudo salt '*' test.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

enable_ssh_minions
Default: False

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

enable_ssh_minions: True

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

ret_port
Default: 4506

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

ret_port: 4506

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

Specify the location of the master pidfile.

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

root_dir
Default: /

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

root_dir: /

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

conf_file
Default: /etc/salt/master

The path to the master’s configuration file.

conf_file: /etc/salt/master

pki_dir
Default: /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

· tokens

module_dirs
Default: []

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

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

cachedir
Default: /var/cache/salt/master

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

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

cachedir: /var/cache/salt/master

verify_env
Default: True

Verify and set permissions on configuration directories at startup.

verify_env: True

keep_jobs
Default: 24

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

keep_jobs: 24

gather_job_timeout
New in version 2014.7.0.

Default: 10

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

gather_job_timeout: 10

timeout
Default: 5

Set the default timeout for the salt command and api.

loop_interval
Default: 60

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

output
Default: nested

Set the default outputter used by the salt command.

outputter_dirs
Default: []

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

outputter_dirs: []

output_file
Default: None

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

output_file: /path/output/file

show_timeout
Default: True

Tell the client to show minions that have timed out.

show_timeout: True

show_jid
Default: False

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

show_jid: False

color
Default: True

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

color: False

color_theme
Default: ""

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

color_theme: /etc/salt/color_theme

cli_summary
Default: False

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

cli_summary: False

sock_dir
Default: /var/run/salt/master

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

sock_dir: /var/run/salt/master

enable_gpu_grains
Default: False

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

enable_gpu_grains: True

job_cache
Default: True

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

job_cache: True

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

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

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

minion_data_cache
Default: True

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

minion_data_cache: True

cache
Default: localfs

Cache subsystem module to use for minion data cache.

cache: consul

memcache_expire_seconds
Default: 0

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

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

memcache_expire_seconds: 30

memcache_max_items
Default: 1024

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

memcache_max_items: 1024

memcache_full_cleanup
Default: False

If cache storage got full, i.e. the items count exceeds the memcache_max_items value,
memcache cleans up 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

master_job_cache
New in version 2014.7.0.

Default: local_cache

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

master_job_cache: redis

job_cache_store_endtime
New in version 2015.8.0.

Default: False

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

job_cache_store_endtime: False

enforce_mine_cache
Default: False

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

enforce_mine_cache: False

max_minions
Default: 0

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

max_minions: 100

con_cache
Default: False

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

con_cache: True

presence_events
Default: False

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

presence_events: False

ping_on_rotate
New in version 2014.7.0.

Default: False

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

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

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

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

ping_on_rotate: False

transport
Default: zeromq

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

transport: zeromq

transport_opts
Default: {}

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

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

master_stats
Default: False

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

master_stats_event_iter
Default: 60

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

sock_pool_size
Default: 1

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

sock_pool_size: 15

ipc_mode
Default: ipc

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

ipc_mode: ipc

tcp_master_pub_port
Default: 4512

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

tcp_master_pub_port: 4512

tcp_master_pull_port
Default: 4513

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

tcp_master_pull_port: 4513

tcp_master_publish_pull
Default: 4514

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

tcp_master_publish_pull: 4514

tcp_master_workers
Default: 4515

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

tcp_master_workers: 4515

auth_events
New in version 2017.7.3.

Default: True

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

auth_events: True

minion_data_cache_events
New in version 2017.7.3.

Default: True

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

minion_data_cache_events: True

Salt-SSH Configuration
roster
Default: flat

Define the default salt-ssh roster module to use

roster: cache

roster_defaults
New in version 2017.7.0.

Default settings which will be inherited by all rosters.

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

roster_file
Default: /etc/salt/roster

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

roster_file: /root/roster

rosters
Default: None

Define locations for flat roster files so they can be chosen when using Salt API. An
administrator can place roster files into these locations. Then, when calling Salt API,
the roster_file parameter should contain a relative path to these locations. That is,
roster_file=/foo/roster will be resolved as /etc/salt/roster.d/foo/roster etc. This
feature prevents passing insecure custom rosters through the Salt API.

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

ssh_passwd
Default: ''

The ssh password to log in with.

ssh_passwd: ''

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

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

autoreject_file
New in version 2014.1.0.

Default: not defined

Works like autosign_file, but instead allows you to specify minion IDs for which keys will
automatically be rejected. Will override both membership in the autosign_file and the
auto_accept setting.

autosign_grains_dir
New in version 2018.3.0.

Default: not defined

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

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

autosign_grains_dir: /etc/salt/autosign_grains

permissive_pki_access
Default: False

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

permissive_pki_access: False

publisher_acl
Default: {}

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

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

publisher_acl_blacklist
Default: {}

Blacklist users or modules

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

This is completely disabled by default.

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

sudo_acl
Default: False

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

sudo_acl: False

external_auth
Default: {}

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

external_auth:
pam:
fred:
- test.*

token_expire
Default: 43200

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

Default: 12 hours

token_expire: 43200

token_expire_user_override
Default: False

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

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

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

keep_acl_in_token
Default: False

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

keep_acl_in_token: False

eauth_acl_module
Default: ''

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

eauth_acl_module: django

file_recv
Default: False

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

file_recv: False

file_recv_max_size
New in version 2014.7.0.

Default: 100

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

file_recv_max_size: 100

master_sign_pubkey
Default: False

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

master_sign_pubkey: True

master_sign_key_name
Default: master_sign

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

master_sign_key_name: <filename_without_suffix>

master_pubkey_signature
Default: master_pubkey_signature

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

master_pubkey_signature: <filename>

master_use_pubkey_signature
Default: False

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

master_use_pubkey_signature: True

rotate_aes_key
Default: True

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

rotate_aes_key: True

publish_session
Default: 86400

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

publish_session: Default: 86400

ssl
New in version 2016.11.0.

Default: None

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

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

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

preserve_minion_cache
Default: False

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

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

preserve_minion_cache: False

allow_minion_key_revoke
Default: True

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

allow_minion_key_revoke: False

optimization_order
Default: [0, 1, 2]

In cases where Salt is distributed without .py files, this option determines the priority
of optimization level(s) Salt’s module loader should prefer.

NOTE:
This option is only supported on Python 3.5+.

optimization_order:
- 2
- 0
- 1

Master Large Scale Tuning Settings
max_open_files
Default: 100000

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

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

max_open_files: 100000

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

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

raise max open files hard limit debian

worker_threads
Default: 5

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

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

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

worker_threads: 5

pub_hwm
Default: 1000

The zeromq high water mark on the publisher interface.

pub_hwm: 1000

zmq_backlog
Default: 1000

The listen queue size of the ZeroMQ backlog.

zmq_backlog: 1000

Master Module Management
runner_dirs
Default: []

Set additional directories to search for runner modules.

runner_dirs:
- /var/lib/salt/runners

utils_dirs
New in version 2018.3.0.

Default: []

Set additional directories to search for util modules.

utils_dirs:
- /var/lib/salt/utils

cython_enable
Default: False

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

cython_enable: False

Master State System Settings
state_top
Default: top.sls

The state system uses a “top” file to tell the minions what environment to use and what
modules to use. The state_top file is defined relative to the root of the base
environment. The value of “state_top” is also used for the pillar top file

state_top: top.sls

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

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

state_top_saltenv: dev

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

Default: merge

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

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

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

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

top_file_merging_strategy: same

env_order
Default: []

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

env_order:
- base
- dev
- qa

master_tops
Default: {}

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

master_tops:
ext_nodes: <Shell command which returns yaml>

renderer
Default: 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_env
New in version 2018.3.0.

Default: {}

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

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

The default options are:

jinja_env:
block_start_string: '{%'
block_end_string: '%}'
variable_start_string: '{{'
variable_end_string: '}}'
comment_start_string: '{#'
comment_end_string: '#}'
line_statement_prefix:
line_comment_prefix:
trim_blocks: False
lstrip_blocks: False
newline_sequence: '\n'
keep_trailing_newline: False

jinja_sls_env
New in version 2018.3.0.

Default: {}

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

The default options are:

jinja_sls_env:
block_start_string: '{%'
block_end_string: '%}'
variable_start_string: '{{'
variable_end_string: '}}'
comment_start_string: '{#'
comment_end_string: '#}'
line_statement_prefix:
line_comment_prefix:
trim_blocks: False
lstrip_blocks: False
newline_sequence: '\n'
keep_trailing_newline: False

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

If your configuration options are

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

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

This allows the following more convenient syntax to be used:

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

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

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

jinja_trim_blocks
Deprecated since version 2018.3.0: Replaced by jinja_env and jinja_sls_env

New in version 2014.1.0.

Default: False

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

jinja_trim_blocks: False

jinja_lstrip_blocks
Deprecated since version 2018.3.0: Replaced by jinja_env and jinja_sls_env

New in version 2014.1.0.

Default: False

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

jinja_lstrip_blocks: False

failhard
Default: False

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

failhard: False

state_verbose
Default: True

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

state_verbose: False

state_output
Default: full

The state_output setting controls which results will be output full multi line:

· full, terse - each state will be full/terse

· mixed - only states with errors will be full

· changes - states with changes and errors will be full

full_id, mixed_id, changes_id and terse_id are also allowed; when set, the state ID will
be used as name in the output.

state_output: full

state_output_diff
Default: False

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

state_output_diff: False

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

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

fileserver_followsymlinks
New in version 2014.1.0.

Default: True

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

fileserver_followsymlinks: True

fileserver_ignoresymlinks
New in version 2014.1.0.

Default: False

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

fileserver_ignoresymlinks: False

fileserver_limit_traversal
New in version 2014.1.0.

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

Default: False

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

fileserver_limit_traversal: False

fileserver_list_cache_time
New in version 2014.1.0.

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

Default: 20

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

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

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

fileserver_list_cache_time: 5

fileserver_verify_config
New in version 2017.7.0.

Default: True

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

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

fileserver_verify_config: False

hash_type
Default: sha256

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

hash_type: sha256

file_buffer_size
Default: 1048576

The buffer size in the file server in bytes.

file_buffer_size: 1048576

file_ignore_regex
Default: ''

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

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

file_ignore_glob
Default ''

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

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

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

master_roots
Default: /srv/salt-master

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

master_roots: /srv/salt-master

roots: Master’s Local File Server
file_roots
Default:

base:
- /srv/salt

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

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

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.

roots_update_interval
New in version 2018.3.0.

Default: 60

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

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

roots_update_interval: 120

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

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

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

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

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

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

gitfs_provider
New in version 2014.7.0.

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

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

gitfs_provider: gitpython

gitfs_ssl_verify
Default: True

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

gitfs_ssl_verify: False

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

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

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

gitfs_mountpoint
New in version 2014.7.0.

Default: ''

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

gitfs_mountpoint: salt://foo/bar

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

gitfs_root
Default: ''

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

gitfs_root: somefolder/otherfolder

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

gitfs_base
Default: master

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

gitfs_base: salt

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

gitfs_saltenv
New in version 2016.11.0.

Default: []

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

gitfs_saltenv:
- dev:
- ref: develop

gitfs_disable_saltenv_mapping
New in version 2018.3.0.

Default: False

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

gitfs_disable_saltenv_mapping: True

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

gitfs_ref_types
New in version 2018.3.0.

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

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

gitfs_ref_types:
- branch

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

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

gitfs_saltenv_whitelist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from gitfs_env_whitelist to gitfs_saltenv_whitelist

Default: []

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

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

gitfs_saltenv_blacklist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from gitfs_env_blacklist to gitfs_saltenv_blacklist

Default: []

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

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

gitfs_global_lock
New in version 2015.8.9.

Default: True

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

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

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

# Disable global lock
gitfs_global_lock: False

gitfs_update_interval
New in version 2018.3.0.

Default: 60

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

gitfs_update_interval: 120

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

gitfs_user
New in version 2014.7.0.

Default: ''

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

gitfs_user: git

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

gitfs_password
New in version 2014.7.0.

Default: ''

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

gitfs_password: mypassword

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

gitfs_insecure_auth
New in version 2014.7.0.

Default: False

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

gitfs_insecure_auth: True

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

gitfs_pubkey
New in version 2014.7.0.

Default: ''

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

gitfs_pubkey: /path/to/key.pub

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

gitfs_privkey
New in version 2014.7.0.

Default: ''

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

gitfs_privkey: /path/to/key

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

gitfs_passphrase
New in version 2014.7.0.

Default: ''

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

gitfs_passphrase: mypassphrase

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

gitfs_refspecs
New in version 2017.7.0.

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

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

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

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

Default: []

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

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

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

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

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

hgfs_branch_method
New in version 0.17.0.

Default: branches

Defines the objects that will be used as fileserver environments.

· branches - Only branches and tags will be used

· bookmarks - Only bookmarks and tags will be used

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

hgfs_branch_method: mixed

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

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

hgfs_mountpoint
New in version 2014.7.0.

Default: ''

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

hgfs_mountpoint: salt://foo/bar

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

hgfs_root
New in version 0.17.0.

Default: ''

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

hgfs_root: somefolder/otherfolder

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

hgfs_base
New in version 2014.1.0.

Default: default

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

hgfs_base: salt

hgfs_saltenv_whitelist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from hgfs_env_whitelist to hgfs_saltenv_whitelist

Default: []

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

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

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

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

hgfs_saltenv_blacklist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from hgfs_env_blacklist to hgfs_saltenv_blacklist

Default: []

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

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

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

hgfs_update_interval
New in version 2018.3.0.

Default: 60

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

hgfs_update_interval: 120

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

Default: []

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

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

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

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

· svnfs_root

· svnfs_mountpoint

· svnfs_trunk

· svnfs_branches

· svnfs_tags

For example:

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

svnfs_mountpoint
New in version 2014.7.0.

Default: ''

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

svnfs_mountpoint: salt://foo/bar

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

svnfs_root
New in version 0.17.0.

Default: ''

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

svnfs_root: somefolder/otherfolder

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

svnfs_trunk
New in version 2014.7.0.

Default: trunk

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

svnfs_trunk: trunk

svnfs_branches
New in version 2014.7.0.

Default: branches

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

svnfs_branches: branches

svnfs_tags
New in version 2014.7.0.

Default: tags

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

svnfs_tags: tags

svnfs_saltenv_whitelist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from svnfs_env_whitelist to svnfs_saltenv_whitelist

Default: []

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

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

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

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

svnfs_saltenv_blacklist
New in version 2014.7.0.

Changed in version 2018.3.0: Renamed from svnfs_env_blacklist to svnfs_saltenv_blacklist

Default: []

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

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

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

svnfs_update_interval
New in version 2018.3.0.

Default: 60

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

svnfs_update_interval: 120

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

Default: base

Environment from which MinionFS files are made available.

minionfs_env: minionfs

minionfs_mountpoint
New in version 2014.7.0.

Default: ''

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

minionfs_mountpoint: salt://foo/bar

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

minionfs_whitelist
New in version 2014.7.0.

Default: []

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

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

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

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

minionfs_blacklist
New in version 2014.7.0.

Default: []

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

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

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

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

minionfs_update_interval
New in version 2018.3.0.

Default: 60

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

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

minionfs_update_interval: 120

azurefs: Azure File Server Backend
New in version 2015.8.0.

See the azurefs documentation for usage examples.

azurefs_update_interval
New in version 2018.3.0.

Default: 60

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

azurefs_update_interval: 120

s3fs: S3 File Server Backend
New in version 0.16.0.

See the s3fs documentation for usage examples.

s3fs_update_interval
New in version 2018.3.0.

Default: 60

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

s3fs_update_interval: 120

Pillar Configuration
pillar_roots
Default:

base:
- /srv/pillar

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

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:

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

New in version 2016.3.4.

· recurse:

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

foo: 42
bar:
element1: True

bar:
element2: True
baz: quux

will be merged as:

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

· aggregate:

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

For example, these two documents:

#!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_includes_override_sls
New in version 2017.7.6,2018.3.1.

Default: False

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

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

pillar_includes_override_sls: True

Pillar Cache Options
pillar_cache
New in version 2015.8.8.

Default: False

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

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

pillar_cache: False

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

pillar_cache_ttl
New in version 2015.8.8.

Default: 3600

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

pillar_cache_backend
New in version 2015.8.8.

Default: disk

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

· disk (default):

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

· memory [EXPERIMENTAL]:

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

pillar_cache_backend: disk

Master Reactor Settings
reactor
Default: []

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

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

reactor_refresh_interval
Default: 60

The TTL for the cache of the reactor configuration.

reactor_refresh_interval: 60

reactor_worker_threads
Default: 10

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

reactor_worker_threads: 10

reactor_worker_hwm
Default: 10000

The queue size for workers in the reactor.

reactor_worker_hwm: 10000

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

api_logfile
Default: /var/log/salt/api

The logfile location for salt-api.

api_logfile: /var/log/salt/api

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

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

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

rest_timeout
Default: 300

Used by salt-api for the master requests timeout.

rest_timeout: 300

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

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

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

order_masters
Default: False

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

order_masters: False

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

Default: masterofmasters

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

syndic_master: masterofmasters

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

syndic_master:
- masterofmasters1
- masterofmasters2

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

syndic_master_port
Default: 4506

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

syndic_master_port: 4506

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

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

syndic_pidfile: /var/run/syndic.pid

syndic_log_file
Default: /var/log/salt/syndic

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

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

syndic_failover
New in version 2016.3.0.

Default: random

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

syndic_failover: random

syndic_wait
Default: 5

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

syndic_wait: 5

syndic_forward_all_events
New in version 2017.7.0.

Default: False

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

syndic_forward_all_events: False

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

peer
Default: {}

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

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

This will allow all minions to execute all commands:

peer:
.*:
- .*

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

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

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

peer_run
Default: {}

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

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

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

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

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

Examples:

log_file: /var/log/salt/master

log_file: file:///dev/log

log_file: udp://loghost:10514

log_level
Default: warning

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

log_level: warning

log_level_logfile
Default: warning

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

log_level_logfile: warning

log_datefmt
Default: %H:%M:%S

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

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

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

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

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

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

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

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

Console log colors are specified by these additional formatters:

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

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

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

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

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

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

log_granular_levels
Default: {}

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

Node Groups
nodegroups
Default: {}

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

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

More information on using nodegroups can be found here.

Range Cluster Settings
range_server
Default: 'range:80'

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

range_server: range:80

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

1. The master config file itself

2. The files matching the glob in default_include

3. The files matching the glob in include (if defined)

Each successive step overrides any values defined in the previous steps. Therefore, any
config options defined in one of the default_include files would override the same value
in the master config file, and any options defined in include would override both.

default_include
Default: master.d/*.conf

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

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

include
Default: not defined

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

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

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

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

Keepalive Settings
tcp_keepalive
Default: True

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

tcp_keepalive: True

tcp_keepalive_cnt
Default: -1

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

tcp_keepalive_cnt: -1

tcp_keepalive_idle
Default: 300

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

tcp_keepalive_idle: 300

tcp_keepalive_intvl
Default: -1

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

tcp_keepalive_intvl': -1

Windows Software Repo Settings
winrepo_provider
New in version 2015.8.0.

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

winrepo_provider: gitpython

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

Default: /srv/salt/win/repo

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

winrepo_dir: /srv/salt/win/repo

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

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

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

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

winrepo_cachefile
Changed in version 2015.8.0: Renamed from win_repo_mastercachefile to winrepo_cachefile

NOTE:
2015.8.0 and later minions do not use this setting since the cachefile is now 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

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

winrepo_ssl_verify
New in version 2015.8.0.

Changed in version 2016.11.0.

Default: False

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

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

winrepo_ssl_verify: True

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

winrepo_user
New in version 2015.8.0.

Default: ''

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

winrepo_user: git

winrepo_password
New in version 2015.8.0.

Default: ''

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

winrepo_password: mypassword

winrepo_insecure_auth
New in version 2015.8.0.

Default: False

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

winrepo_insecure_auth: True

winrepo_pubkey
New in version 2015.8.0.

Default: ''

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

winrepo_pubkey: /path/to/key.pub

winrepo_privkey
New in version 2015.8.0.

Default: ''

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

winrepo_privkey: /path/to/key

winrepo_passphrase
New in version 2015.8.0.

Default: ''

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

winrepo_passphrase: mypassphrase

winrepo_refspecs
New in version 2017.7.0.

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

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

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

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

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

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

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

Common Directories
┌─────────────────────────────────┬───────────────────────────────────────┐
│Linux Paths │ Windows Paths │
├─────────────────────────────────┼───────────────────────────────────────┤
│cachedir: /var/cache/salt/master │ cachedir: │
│ │ c:\salt\var\cache\salt\master │
├─────────────────────────────────┼───────────────────────────────────────┤
│extension_modules: │ c:\salt\var\cache\salt\master\extmods │
│/var/cache/salt/master/extmods │ │
├─────────────────────────────────┼───────────────────────────────────────┤
│pki_dir: /etc/salt/pki/master │ pki_dir: c:\salt\conf\pki\master │
├─────────────────────────────────┼───────────────────────────────────────┤
│root_dir: / │ root_dir: c:\salt │
└─────────────────────────────────┴───────────────────────────────────────┘

│sock_dir: /var/run/salt/master │ sock_dir: c:\salt\var\run\salt\master │
└─────────────────────────────────┴───────────────────────────────────────┘

Roots
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: │ winrepo_dir_ng: │
│/srv/salt/win/repo-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_tops_first
New in version 2018.3.0.

Default: False

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

master_tops_first: True

master_type
New in version 2014.7.0.

Default: str

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

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

retry_dns_count
New in version 2018.3.4.

Default: None

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

retry_dns_count: 3

master_port
Default: 4506

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

master_port: 4506

publish_port
Default: 4505

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

publish_port: 4505

source_interface_name
New in version 2018.3.0.

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

NOTE:
If multiple IP addresses are configured on the named interface, the first one will be
selected. In that case, for a better selection, consider using the source_address
option.

NOTE:
To use an IPv6 address from the named interface, make sure the option ipv6 is enabled,
i.e., ipv6: true.

NOTE:
If the interface is down, it will avoid using it, and the Minion will bind to 0.0.0.0
(all interfaces).

WARNING:
This option requires modern version of the underlying libraries used by the selected
transport:

· zeromq requires pyzmq >= 16.0.1 and libzmq >= 4.1.6

· tcp requires tornado >= 4.5

Configuration example:

source_interface_name: bond0.1234

source_address
New in version 2018.3.0.

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

WARNING:
This option requires modern version of the underlying libraries used by the selected
transport:

· zeromq requires pyzmq >= 16.0.1 and libzmq >= 4.1.6

· tcp requires tornado >= 4.5

Configuration example:

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

source_ret_port
New in version 2018.3.0.

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

WARNING:
This option requires modern version of the underlying libraries used by the selected
transport:

· zeromq requires pyzmq >= 16.0.1 and libzmq >= 4.1.6

· tcp requires tornado >= 4.5

Configuration example:

source_ret_port: 49017

source_publish_port
New in version 2018.3.0.

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

WARNING:
This option requires modern version of the underlying libraries used by the selected
transport:

· zeromq requires pyzmq >= 16.0.1 and libzmq >= 4.1.6

· tcp requires tornado >= 4.5

Configuration example:

source_publish_port: 49018

user
Default: root

The user to run the Salt processes

user: root

sudo_user
Default: ''

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

sudo_user: root

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

The location of the daemon’s process ID file

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

root_dir
Default: /

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

root_dir: /

conf_file
Default: /etc/salt/minion

The path to the minion’s configuration file.

conf_file: /etc/salt/minion

pki_dir
Default: /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:

'roles:webserver':
- match: grain
- state0

'roles:memcache':
- match: grain
- state1
- state2

For this example to work, you would need to have defined the grain role for the minions
you wish to match.

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

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.

Dynamic Pillar Environments
If environment __env__ is specified in pillar_roots, all environments that are not
explicitly specified in pillar_roots will map to the directories from __env__. This allows
one to use dynamic git branch based environments for state/pillar files with the same
file-based pillar applying to all environments. For example:

pillar_roots:
__env__:
- /srv/pillar

ext_pillar:
- git:
- __env__ https://example.com/git-pillar.git

New in version 2017.7.5,2018.3.1.

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"}}'

Lists can be passed via command line pillar data as follows:

salt '*' state.sls my_sls_file pillar='{"some_list": ["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 dictionary 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.

   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), 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 Python dictionary
       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.

   __init__ Function
       If  you  want your module to have different execution modes based on minion configuration,
       you can use the __init__(opts) function to perform initial  module  setup.  The  parameter
       opts is the complete minion configuration, as also available in the __opts__ dict.

          '''
          Cheese module initialization example
          '''
          def __init__(opts):
              '''
              Allow foreign imports if configured to do so
              '''
              if opts.get('cheese.allow_foreign', False):
                  _enable_foreign_products()

   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  unreliable  as
       not  all  modules  will  be  available  at this point in time. The __pillar and __grains__
       “dunder” dictionaries are available however.

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

          def slice():
              pass

          '''
          Cheese state module. Note that this works in state modules because it is
          guaranteed that execution modules are loaded first
          '''

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

   Executors
       Executors are used by minion to execute module functions. Executors can be used to  modify
       the  functions behavior, do any pre-execution steps or execute in a specific way like sudo
       executor.

       Executors could be passed as a list and they will be used one-by-one in the order.  If  an
       executor  returns  None  the  next one will be called. If an executor returns non-None the
       execution sequence is terminated and the returned value is used as a result.  It’s  a  way
       executor  could  control  modules  execution working as a filter. Note that executor could
       actually not execute the function but just do something else and return  None  like  splay
       executor  does.  In this case some other executor have to be used as a final executor that
       will actually execute the function. See examples below.

       Executors list could be passed by minion config file in the following way:

          module_executors:
            - splay
            - direct_call
          splaytime: 30

       The same could be done by command line:

          salt -t 40 --module-executors='[splay, direct_call]' --executor-opts='{splaytime: 30}' '*' test.ping

       And the same command called via netapi will look like this:

          curl -sSk https://localhost:8000 \
              -H 'Accept: application/x-yaml' \
              -H 'X-Auth-Token: 697adbdc8fe971d09ae4c2a3add7248859c87079' \
              -H 'Content-type: application/json' \
              -d '[{
                  "client": "local",
                  "tgt": "*",
                  "fun": "test.ping",
                  "module_executors": ["splay", "direct_call"],
                  "executor_opts": {"splaytime": 10}
                  }]'

       SEE ALSO:
          The full list of executors

   Writing Salt Executors
       A Salt executor is written in a similar manner to a Salt execution module.  Executor is  a
       python  module  placed  into the executors folder and containing the execute function with
       the following signature:

          def execute(opts, data, func, args, kwargs)

       Where the args are:

       opts:  Dictionary containing the minion configuration options

       data:  Dictionary containing the load data including executor_opts passed via cmdline/API.

       func, args, kwargs:
              Execution module function to be executed  and  it’s  arguments.  For  instance  the
              simplest direct_call executor just runs it as func(*args, **kwargs).

       Returns:
              None  if  the  execution  sequence must be continued with the next executor.  Error
              string or execution result if the job is done and execution must be stopped.

       Specific options could be passed to the executor via minion config  or  via  executor_opts
       argument.  For  instance  to  access splaytime option set by minion config executor should
       access  opts.get('splaytime').  To  access  the  option  set   by   commandline   or   API
       data.get('executor_opts', {}).get('splaytime') should be used. So if an option is safe and
       must be accessible by user executor should check it in both places, but if  an  option  is
       unsafe it should be read from the only config ignoring the passed request data.

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.

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 = __utils__['state.gen_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'

       New in version 2018.3.0: Instantiating objects from classes declared in util modules works
       with Master side modules, such as Runners, Outputters, etc.

       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 a highstate is
       run, as well as when any of the following Salt functions are called:

       · saltutil.sync_utils

       · saltutil.sync_all

       As  of  the Fluorine release, as well as 2017.7.7 and 2018.3.2 in their respective release
       cycles, the sync argument to state.apply/state.sls can be used to sync custom  types  when
       running individual SLS files.

       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 uses a
publish-subscribe pattern, otherwise know as pub/sub.

Event Bus
The event system is comprised of a two primary components, which make up the concept of an
Event Bus:

· The event sockets, which publish events

· The event library, which can listen to events and send events into the salt system

Events are published onto the event bus and event bus subscribers listen for the published
events.

The event bus is used for both inter-process communication as well as network transport in
Salt. Inter-process communication is provided through UNIX domain sockets (UDX).

The Salt Master and each Salt Minion has their own event bus.

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 system 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 or add it to
pillars for that minion:

beacons:
inotify:
- files:
/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.

All beacon configuration is done using list based configuration.

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:
- files:
/etc/important_file: {}
/opt: {}
- interval: 5
- disable_during_state_run: True
load:
- averages:
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:
- files:
/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:
- files:
/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:

{
"_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 via the standard methods, see Modular
Systems.

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 available 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 likely be renamed in a future 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,
however.

Where to Put Reactor SLS Files
Reactor SLS files can come both from files local to the master, and from any of backends
enabled via the fileserver_backend config option. Files placed in the Salt fileserver can
be referenced using a salt:// URL, just like they can in State SLS files.

It is recommended to place reactor and orchestrator SLS files in their own uniquely-named
subdirectories such as orch/, orchestrate/, react/, reactor/, etc., to keep them
organized.

Writing Reactor SLS
The different reaction types were developed separately and have historically had different
methods for passing arguments. For the 2017.7.2 release a new, unified configuration
schema has been introduced, which applies to all reaction types.

The old config schema will continue to be supported, and there is no plan to deprecate it
at this time.

Local Reactions
A local reaction runs a remote-execution function on the targeted minions.

The old config schema required the positional and keyword arguments to be manually
separated by the user under arg and kwarg parameters. However, this is not very
user-friendly, as it forces the user to distinguish which type of argument is which, and
make sure that positional arguments are ordered properly. Therefore, the new config schema
is recommended if the master is running a supported release.

The below two examples are equivalent:

┌─────────────────────────────────────┬─────────────────────────────────────┐
│Supported in 2017.7.2 and later │ Supported in all releases │
├─────────────────────────────────────┼─────────────────────────────────────┤
│ │ │
│ install_zsh: │ install_zsh: │
│ local.state.single: │ local.state.single: │
│ - tgt: 'kernel:Linux' │ - tgt: 'kernel:Linux' │
│ - tgt_type: grain │ - tgt_type: grain │
│ - args: │ - arg: │
│ - fun: pkg.installed │ - pkg.installed │
│ - name: zsh │ - zsh │
│ - fromrepo: updates │ - kwarg: │
│ │ fromrepo: updates │
└─────────────────────────────────────┴─────────────────────────────────────┘

This reaction would be equivalent to running the following Salt command:

salt -G 'kernel:Linux' state.single pkg.installed name=zsh fromrepo=updates

NOTE:
Any other parameters in the LocalClient().cmd_async() method can be passed at the same
indentation level as tgt.

NOTE:
tgt_type is only required when the target expression defined in tgt uses a target type
other than a minion ID glob.

The tgt_type argument was named expr_form in releases prior to 2017.7.0.

Runner Reactions
Runner reactions execute runner functions locally on the master.

The old config schema called for passing arguments to the reaction directly under the name
of the runner function. However, this can cause unpredictable interactions with the
Reactor system’s internal arguments. It is also possible to pass positional and keyword
arguments under arg and kwarg like above in local reactions, but as noted above this is
not very user-friendly. Therefore, the new config schema is recommended if the master is
running a supported release.

The below two examples are equivalent:

┌────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┐
├────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
└────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────┘

Assuming that the event tag is foo, and the data passed to the event is {'bar': 'baz'},
then this reaction is equivalent to running the following Salt command:

salt-run state.orchestrate mods=orchestrate.deploy_app pillar='{"event_tag": "foo", "event_data": {"bar": "baz"}}'

Wheel Reactions
Wheel reactions run wheel functions locally on the master.

Like runner reactions, the old config schema called for wheel reactions to have arguments
passed directly under the name of the wheel function (or in arg or kwarg parameters).

The below two examples are equivalent:

┌──────────────────────────────────────────┬─────────────────────────────────────────┐
│Supported in 2017.7.2 and later │ Supported in all releases │
├──────────────────────────────────────────┼─────────────────────────────────────────┤
│ │ │
│ remove_key: │ remove_key: │
│ wheel.key.delete: │ wheel.key.delete: │
│ - args: │ - match: {{ data['id'] }} │
│ - match: {{ data['id'] }} │ │
└──────────────────────────────────────────┴─────────────────────────────────────────┘

Caller Reactions
Caller reactions run remote-execution functions on a minion daemon’s Reactor system. To
run a Reactor on the minion, it is necessary to configure the Reactor Engine in the minion
config file, and then setup your watched events in a reactor section in the minion config
file as well.

NOTE:
Masterless Minions use this Reactor

This is the only way to run the Reactor if you use masterless minions.

Both the old and new config schemas involve passing arguments under an args parameter.
However, the old config schema only supports positional arguments. Therefore, the new
config schema is recommended if the masterless minion is running a supported release.

The below two examples are equivalent:

┌─────────────────────────────────┬────────────────────────────────┐
│Supported in 2017.7.2 and later │ Supported in all releases │
├─────────────────────────────────┼────────────────────────────────┤
│ │ │
│ touch_file: │ touch_file: │
│ caller.file.touch: │ caller.file.touch: │
│ - args: │ - args: │
│ - name: /tmp/foo │ - /tmp/foo │
└─────────────────────────────────┴────────────────────────────────┘

This reaction is equivalent to running the following Salt command:

salt-call file.touch name=/tmp/foo

Best Practices for Writing Reactor SLS Files
The Reactor works as follows:

1. The Salt Reactor watches Salt’s event bus for new events.

2. Each event’s tag is matched against the list of event tags configured under the reactor
section in the Salt Master config.

3. The SLS files for any matches are rendered into a data structure that represents one or
more function calls.

4. That data structure is given to a pool of worker threads for execution.

Matching and rendering Reactor SLS files is done sequentially in a single process. For
that reason, reactor SLS files should contain few individual reactions (one, if at all
possible). Also, keep in mind that reactions are fired asynchronously (with the exception
of caller) and do not support requisites.

Complex Jinja templating that calls out to slow remote-execution or runner functions slows
down the rendering and causes other reactions to pile up behind the current one. The
worker pool is designed to handle complex and long-running processes like orchestration
jobs.

Therefore, when complex tasks are in order, orchestration is a natural fit. Orchestration
SLS files can be more complex, and use requisites. Performing a complex task using
orchestration lets the Reactor system fire off the orchestration job and proceed with
processing other reactions.

Jinja Context
Reactor SLS files only have access to a minimal Jinja context. grains and pillar are not
available. The salt object is available for calling remote-execution or runner functions,
but it should be used sparingly and only for quick tasks for the reasons mentioned above.

In addition to the salt object, the following variables are available in the Jinja
context:

· tag - the tag from the event that triggered execution of the Reactor SLS file

· data - the event’s data dictionary

The data dict will contain an id key containing the minion ID, if the event was fired from
a minion, and a data key containing the data passed to the event.

Advanced State System Capabilities
Reactor SLS files, by design, do not support requisites, ordering, onlyif/unless
conditionals and most other powerful constructs from Salt’s State system.

Complex Master-side operations are best performed by Salt’s Orchestrate system so using
the Reactor to kick off an Orchestrate run is a very common pairing.

For example:

# /etc/salt/master.d/reactor.conf
# A custom event containing: {"foo": "Foo!", "bar: "bar*", "baz": "Baz!"}
reactor:
- my/custom/event:
- /srv/reactor/some_event.sls

# /srv/reactor/some_event.sls
invoke_orchestrate_file:
runner.state.orchestrate:
- args:
- mods: orchestrate.do_complex_thing
- pillar:
event_tag: {{ tag }}
event_data: {{ data|json }}

# /srv/salt/orchestrate/do_complex_thing.sls
{% set tag = salt.pillar.get('event_tag') %}
{% set data = salt.pillar.get('event_data') %}

# Pass data from the event to a custom runner function.
# The function expects a 'foo' argument.
do_first_thing:
salt.runner:
- name: custom_runner.custom_function
- foo: {{ data.foo }}

# Wait for the runner to finish then send an execution to minions.
# Forward some data from the event down to the minion's state run.
do_second_thing:
salt.state:
- tgt: {{ data.bar }}
- sls:
- do_thing_on_minion
- kwarg:
pillar:
baz: {{ data.baz }}
- require:
- salt: do_first_thing

Beacons and Reactors
An event initiated by a beacon, when it arrives at the master will be wrapped inside a
second event, such that the data object containing the beacon information will be
data['data'], rather than data.

For example, to access the id field of the beacon event in a reactor file, you will need
to reference {{ data['data']['id'] }} rather than {{ data['id'] }} as for events initiated
directly on the event bus.

Similarly, the data dictionary attached to the event would be located in {{
data['data']['data'] }} instead of {{ data['data'] }}.

See the beacon documentation for examples.

Manually Firing an Event
From the Master
Use the event.send runner:

salt-run event.send foo '{orchestrate: refresh}'

From the Minion
To fire an event to the master from a minion, call event.send:

salt-call event.send foo '{orchestrate: refresh}'

To fire an event to the minion’s local event bus, call event.fire:

salt-call event.fire '{orchestrate: refresh}' foo

Referencing Data Passed in Events
Assuming any of the above examples, any reactor SLS files triggered by watching the event
tag foo will execute with {{ data['data']['orchestrate'] }} equal to 'refresh'.

Getting Information About Events
The best way to see exactly what events have been fired and what data is available in each
event is to use the state.event runner.

ORCHESTRATION

   Orchestrate Runner
       Executing states or highstate on a minion is perfect when you want to ensure  that  minion
       configured  and running the way you want. Sometimes however you want to configure a set of
       minions all at once.

       For example, if you want to set up a load balancer in front of a cluster  of  web  servers
       you can ensure the load balancer is set up first, and then the same matching configuration
       is applied consistently across the whole cluster.

       Orchestration is the way to do this.

   The Orchestrate Runner
       New in version 0.17.0.

       NOTE:
          Orchestrate Deprecates OverState

          The Orchestrate  Runner  (originally  called  the  state.sls  runner)  offers  all  the
          functionality of the OverState, but with some advantages:

          · All requisites available in states can be used.

          · The states/functions will also work on salt-ssh minions.

          The Orchestrate Runner replaced the OverState system in Salt 2015.8.0.

       The  orchestrate  runner  generalizes  the  Salt  state  system  to a Salt master context.
       Whereas  the  state.sls,  state.highstate,  et  al.   functions   are   concurrently   and
       independently  executed  on  each Salt minion, the state.orchestrate runner is executed on
       the master, giving it a master-level view and  control  over  requisites,  such  as  state
       ordering  and  conditionals.   This  allows for inter minion requisites, like ordering the
       application of states on different minions that must not  happen  simultaneously,  or  for
       halting the state run on all minions if a minion fails one of its states.

       The  state.sls,  state.highstate,  et  al.  functions  allow you to statefully manage each
       minion and the state.orchestrate runner  allows  you  to  statefully  manage  your  entire
       infrastructure.

   Writing SLS Files
       Orchestrate  SLS files are stored in the same location as State SLS files. This means that
       both file_roots and gitfs_remotes impact what SLS files are available to the  reactor  and
       orchestrator.

       It  is  recommended to keep reactor and orchestrator SLS files in their own uniquely named
       subdirectories such as _orch/, orch/, _orchestrate/, react/,  _reactor/,  etc.  This  will
       avoid duplicate naming and will help prevent confusion.

   Executing the Orchestrate Runner
       The  Orchestrate  Runner  command format is the same as for the state.sls function, except
       that since it is a runner, it is executed with salt-run rather than  salt.   Assuming  you
       have  a  state.sls  file called /srv/salt/orch/webserver.sls the following command, run on
       the master, will apply the states defined in that file.

          salt-run state.orchestrate orch.webserver

       NOTE:
          state.orch is a synonym for state.orchestrate

       Changed in version 2014.1.1: The runner function was renamed to state.orchestrate to avoid
       confusion  with  the  state.sls  execution  function. In versions 0.17.0 through 2014.1.0,
       state.sls must be used.

   Masterless Orchestration
       New in version 2016.11.0.

       To support salt orchestration on masterless minions, the Orchestrate Runner  is  available
       as  an  execution module. The syntax for masterless orchestration is exactly the same, but
       it uses the salt-call command and the minion configuration  must  contain  the  file_mode:
       local option. Alternatively, use salt-call --local on the command line.

          salt-call --local state.orchestrate orch.webserver

       NOTE:
          Masterless  orchestration  supports only the salt.state command in an sls file; it does
          not (currently) support the salt.function command.

   Examples
   Function
       To execute a function, use salt.function:

          # /srv/salt/orch/cleanfoo.sls
          cmd.run:
            salt.function:
              - tgt: '*'
              - arg:
                - rm -rf /tmp/foo

          salt-run state.orchestrate orch.cleanfoo

       If you omit the “name” argument, the ID of the state will be the default name, or  in  the
       case  of  salt.function,  the execution module function to run. You can specify the “name”
       argument to avoid conflicting IDs:

          copy_some_file:
            salt.function:
              - name: file.copy
              - tgt: '*'
              - arg:
                - /path/to/file
                - /tmp/copy_of_file
              - kwarg:
                  remove_existing: true

   Fail Functions
       When running a remote execution function in orchestration, certain return values for those
       functions  may  indicate failure, while the function itself doesn’t set a return code. For
       those circumstances, using a “fail function” allows for a more flexible means of assessing
       success or failure.

       A  fail  function can be written as part of a custom execution module. The function should
       accept one argument, and return a boolean result. For example:

          def check_func_result(retval):
              if some_condition:
                  return True
              else:
                  return False

       The function can then be referenced in orchestration SLS like so:

          do_stuff:
            salt.function:
              - name: modname.funcname
              - tgt: '*'
              - fail_function: mymod.check_func_result

       IMPORTANT:
          Fail  functions  run  on  the  master,  so  they  must   be   synced   using   salt-run
          saltutil.sync_modules.

   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"}'

   Return Codes in Runner/Wheel Jobs
       New in version 2018.3.0.

       State (salt.state) jobs are able to report failure via the state return dictionary. Remote
       execution  (salt.function) jobs are able to report failure by setting a retcode key in the
       __context__ dictionary. However, runner (salt.runner) and wheel  (salt.wheel)  jobs  would
       only  report  a False result when the runner/wheel function raised an exception. As of the
       2018.3.0 release, it is now possible to set a retcode in runner and wheel  functions  just
       as you can do in remote execution functions. Here is some example pseudocode:

          def myrunner():
              ...
              do stuff
              ...
              if some_error_condition:
                  __context__['retcode'] = 1
              return result

       This  allows  a  custom runner/wheel function to report its failure so that requisites can
       accurately tell that a job has failed.

   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.

   Parsing Results Programmatically
       Orchestration jobs return output in a specific data  structure.  That  data  structure  is
       represented  differently  depending  on the outputter used. With the default outputter for
       orchestration, you get a nice human-readable output.  Assume the  following  orchestration
       SLS:

          good_state:
            salt.state:
              - tgt: myminion
              - sls:
              - succeed_with_changes

          bad_state:
            salt.state:
              - tgt: myminion
              - sls:
              - fail_with_changes

          mymod.myfunc:
            salt.function:
              - tgt: myminion

          mymod.myfunc_false_result:
            salt.function:
              - tgt: myminion

       Running this using the default outputter would produce output which looks like this:

          fa5944a73aa8_master:
          ----------
                    ID: good_state
              Function: salt.state
                Result: True
               Comment: States ran successfully. Updating myminion.
               Started: 21:08:02.681604
              Duration: 265.565 ms
               Changes:
                        myminion:
                        ----------
                                  ID: test succeed with changes
                            Function: test.succeed_with_changes
                              Result: True
                             Comment: Success!
                             Started: 21:08:02.835893
                            Duration: 0.375 ms
                             Changes:
                                      ----------
                                      testing:
                                          ----------
                                          new:
                                              Something pretended to change
                                          old:
                                              Unchanged

                        Summary for myminion
                        ------------
                        Succeeded: 1 (changed=1)
                        Failed:    0
                        ------------
                        Total states run:     1
                        Total run time:   0.375 ms
          ----------
                    ID: bad_state
              Function: salt.state
                Result: False
               Comment: Run failed on minions: myminion
               Started: 21:08:02.947702
              Duration: 177.01 ms
               Changes:
                        myminion:
                        ----------
                                  ID: test fail with changes
                            Function: test.fail_with_changes
                              Result: False
                             Comment: Failure!
                             Started: 21:08:03.116634
                            Duration: 0.502 ms
                             Changes:
                                      ----------
                                      testing:
                                          ----------
                                          new:
                                              Something pretended to change
                                          old:
                                              Unchanged

                        Summary for myminion
                        ------------
                        Succeeded: 0 (changed=1)
                        Failed:    1
                        ------------
                        Total states run:     1
                        Total run time:   0.502 ms
          ----------
                    ID: mymod.myfunc
              Function: salt.function
                Result: True
               Comment: Function ran successfully. Function mymod.myfunc ran on myminion.
               Started: 21:08:03.125011
              Duration: 159.488 ms
               Changes:
                        myminion:
                            True
          ----------
                    ID: mymod.myfunc_false_result
              Function: salt.function
                Result: False
               Comment: Running function mymod.myfunc_false_result failed on minions: myminion. Function mymod.myfunc_false_result ran on myminion.
               Started: 21:08:03.285148
              Duration: 176.787 ms
               Changes:
                        myminion:
                            False

          Summary for fa5944a73aa8_master
          ------------
          Succeeded: 2 (changed=4)
          Failed:    2
          ------------
          Total states run:     4
          Total run time: 778.850 ms

       However,  using  the  json  outputter,  you  can  get the output in an easily loadable and
       parsable format:

          salt-run state.orchestrate test --out=json

          {
              "outputter": "highstate",
              "data": {
                  "fa5944a73aa8_master": {
                      "salt_|-good_state_|-good_state_|-state": {
                          "comment": "States ran successfully. Updating myminion.",
                          "name": "good_state",
                          "start_time": "21:35:16.868345",
                          "result": true,
                          "duration": 267.299,
                          "__run_num__": 0,
                          "__jid__": "20171130213516897392",
                          "__sls__": "test",
                          "changes": {
                              "ret": {
                                  "myminion": {
                                      "test_|-test succeed with changes_|-test succeed with changes_|-succeed_with_changes": {
                                          "comment": "Success!",
                                          "name": "test succeed with changes",
                                          "start_time": "21:35:17.022592",
                                          "result": true,
                                          "duration": 0.362,
                                          "__run_num__": 0,
                                          "__sls__": "succeed_with_changes",
                                          "changes": {
                                              "testing": {
                                                  "new": "Something pretended to change",
                                                  "old": "Unchanged"
                                              }
                                          },
                                          "__id__": "test succeed with changes"
                                      }
                                  }
                              },
                              "out": "highstate"
                          },
                          "__id__": "good_state"
                      },
                      "salt_|-bad_state_|-bad_state_|-state": {
                          "comment": "Run failed on minions: test",
                          "name": "bad_state",
                          "start_time": "21:35:17.136511",
                          "result": false,
                          "duration": 197.635,
                          "__run_num__": 1,
                          "__jid__": "20171130213517202203",
                          "__sls__": "test",
                          "changes": {
                              "ret": {
                                  "myminion": {
                                      "test_|-test fail with changes_|-test fail with changes_|-fail_with_changes": {
                                          "comment": "Failure!",
                                          "name": "test fail with changes",
                                          "start_time": "21:35:17.326268",
                                          "result": false,
                                          "duration": 0.509,
                                          "__run_num__": 0,
                                          "__sls__": "fail_with_changes",
                                          "changes": {
                                              "testing": {
                                                  "new": "Something pretended to change",
                                                  "old": "Unchanged"
                                              }
                                          },
                                          "__id__": "test fail with changes"
                                      }
                                  }
                              },
                              "out": "highstate"
                          },
                          "__id__": "bad_state"
                      },
                      "salt_|-mymod.myfunc_|-mymod.myfunc_|-function": {
                          "comment": "Function ran successfully. Function mymod.myfunc ran on myminion.",
                          "name": "mymod.myfunc",
                          "start_time": "21:35:17.334373",
                          "result": true,
                          "duration": 151.716,
                          "__run_num__": 2,
                          "__jid__": "20171130213517361706",
                          "__sls__": "test",
                          "changes": {
                              "ret": {
                                  "myminion": true
                              },
                              "out": "highstate"
                          },
                          "__id__": "mymod.myfunc"
                      },
                      "salt_|-mymod.myfunc_false_result-mymod.myfunc_false_result-function": {
                          "comment": "Running function mymod.myfunc_false_result failed on minions: myminion. Function mymod.myfunc_false_result ran on myminion.",
                          "name": "mymod.myfunc_false_result",
                          "start_time": "21:35:17.486625",
                          "result": false,
                          "duration": 174.241,
                          "__run_num__": 3,
                          "__jid__": "20171130213517536270",
                          "__sls__": "test",
                          "changes": {
                              "ret": {
                                  "myminion": false
                              },
                              "out": "highstate"
                          },
                          "__id__": "mymod.myfunc_false_result"
                      }
                  }
              },
              "retcode": 1
          }

       The 2018.3.0 release includes a couple fixes to make parsing this  data  easier  and  more
       accurate.  The  first  is  the  ability  to  set a return code in a custom runner or wheel
       function, as noted above. The second is a change to  how  failures  are  included  in  the
       return data. Prior to the 2018.3.0 release, minions that failed a salt.state orchestration
       job would show up in the comment field of the return data, in a human-readable string that
       was  not  easily  parsed.  They  are  now included in the changes dictionary alongside the
       minions that succeeded. In addition, salt.function jobs  which  failed  because  the  fail
       function returned False used to handle their failures in the same way salt.state jobs did,
       and this has likewise been corrected.

   Running States on the Master without a Minion
       The orchestrate runner can be used to execute states on the master without using a minion.
       For example, assume that salt://foo.sls contains the following SLS:

          /etc/foo.conf:
            file.managed:
              - source: salt://files/foo.conf
              - mode: 0600

       In  this case, running salt-run state.orchestrate foo would be the equivalent of running a
       state.sls foo, but it would execute on the master only, and would  not  require  a  minion
       daemon to be running on the master.

       This is not technically orchestration, but it can be useful in certain use cases.

   Limitations
       Only  one  SLS target can be run at a time using this method, while using state.sls allows
       for multiple SLS files to be passed in a comma-separated list.

SOLARIS

       This section contains details on Solaris specific quirks and workarounds.

       NOTE:
          Solaris refers to both Solaris  10  comaptible  platforms  like  Solaris  10,  illumos,
          SmartOS, OmniOS, OpenIndiana,… and Oracle Solaris 11 platforms.

   Solaris-specific Behaviour
       Salt  is  capable  of managing Solaris systems, however due to various differences between
       the operating systems, there are some things you need to keep in mind.

       This document will contain any quirks that  apply  across  Salt  or  limitations  in  some
       modules.

   FQDN/UQDN
       On Solaris platforms the FQDN will not always be properly detected.  If an IPv6 address is
       configured pythons `socket.getfqdn()` fails to return a  FQDN  and  returns  the  nodename
       instead. For a full breakdown see the following issue on github: #37027

   Grains
       Not  all  grains  are  available  or some have empty or 0 as value. Mostly grains that are
       depenend on hardware discovery like: - num_gpus - gpus

       Also some resolver related grains like: - domain - dns:options - dns:sortlist

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.

THORIUM COMPLEX REACTOR

       NOTE:
          Thorium  is  a  provisional feature of Salt and is subject to change and removal if the
          feature proves to not be a viable solution.

       NOTE:
          Thorium was added to Salt as an experimental feature in the  2016.3.0  release,  as  of
          2016.3.0 this feature is considered experimental, no guarantees are made for support of
          any kind yet.

       The original Salt Reactor is based on the idea of listening for a specific event and  then
       reacting  to  it.  This model comes with many logical limitations, for instance it is very
       difficult (and hacky) to fire a reaction based on aggregate  data  or  based  on  multiple
       events.

       The  Thorium reactor is intended to alleviate this problem in a very elegant way.  Instead
       of using extensive jinja routines or complex python sls files the aggregation of data  and
       the  determination  of  what  should run becomes isolated to the sls data logic, makes the
       definitions much cleaner.

   Starting the Thorium Engine
       To enable the thorium engine add the following configuration to  the  engines  section  of
       your Salt Master or Minion configuration file and restart the daemon:

          engines:
            - thorium: {}

   Thorium Modules
       Because  of  its specialized nature, Thorium uses its own set of modules. However, many of
       these modules are designed to wrap the more commonly-used Salt subsystems.  These  modules
       are:

       · local: Execution modules

       · runner: Runner modules

       · wheel: Wheel modules

       There  are other modules that ship with Thorium as well. Some of these will be highlighted
       later in this document.

   Writing Thorium Formulas
       Like some other Salt subsystems, Thorium uses its own  directory  structure.  The  default
       location   for  this  structure  is  /srv/thorium/,  but  it  can  be  changed  using  the
       thorium_roots setting in the master configuration file.

       This would explicitly set the roots to the default:

          thorium_roots:
            base:
              - /srv/thorium

       Example thorium_roots configuration:

          thorium_roots:
            base:
              - /etc/salt/thorium

   The Thorium top.sls File
       Thorium uses its own top.sls file, which follows  the  same  convention  as  is  found  in
       /srv/salt/:

          <srv>:
            <target>:
              - <formula 1>
              - <formula 2>
              - <etc...>

       For  instance,  a  top.sls  using a standard base environment and a single Thorium formula
       called key_clean, would look like:

          base:
            '*':
              - key_clean

       Take note that the target in a Thorium top.sls is not used; it only exists to  follow  the
       same convention as other top.sls files. Leave this set to '*' in your own Thorium top.sls.

   Thorium Formula Files
       Thorium  SLS  files  are  processed  by  the same state compiler that processes Salt state
       files. This means that features like requisites, templates, and so on are available.

       Let’s take a look at an example, and then discuss each component of it. This formula  uses
       Thorium  to  detect when a minion has disappeared and then deletes the key from the master
       when the minion has been gone for 60 seconds:

          statreg:
            status.reg

          keydel:
            key.timeout:
              - delete: 60
              - require:
                - status: statreg

       There are two stanzas in this formula, whose IDs are statreg and keydel. The first stanza,
       statreg,  tells Thorium to keep track of minion status beacons in its register. We’ll talk
       more about the register in a moment.

       The second stanza, keydel, is the one that does the real work. It uses the key  module  to
       apply an expiration (using the timeout function) to a minion. Because delete is set to 60,
       this is a 60 second expiration. If a minion does not check  in  at  least  once  every  60
       seconds, its key will be deleted from the master. This particular function also allows you
       to use reject instead of delete, allowing for a minion to be rejected instead  of  deleted
       if it does not check in within the specified time period.

       There  is also a require requisite in this stanza. It states that the key.timeout function
       will not be called unless the status.reg  function  in  the  statreg  codeblock  has  been
       successfully called first.

   Thorium Links to Beacons
       The  above  example was added in the 2016.11.0 release of Salt and makes use of the status
       beacon also added in the 2016.11.0 release.  For  the  above  Thorium  state  to  function
       properly you will also need to enable the status beacon in the minion configuration file:

          beacons:
            status:
              - interval: 10

       This  will  cause the minion to use the status beacon to check in with the master every 10
       seconds.

   The Thorium Register
       In order to keep track of information, Thorium uses  an  in-memory  register  (or  rather,
       collection of registers) on the master. These registers are only populated when told to by
       a formula, and they normally will be erased when the master is restarted. It  is  possible
       to persist the registers to disk, but we’ll get to that in a moment.

       The  example  above uses status.reg to populate a register for you, which is automatically
       used by the key.timeout function. However, you can set your own register values  as  well,
       using the reg module.

       Because  Thorium  watches  the  event  bus,  the  reg  module  is  designed  to  look  for
       user-specified tags, and then extract data from the payload of  events  that  match  those
       tags.  For  instance,  the  following  stanza  will  look  for  an  event  with  a  tag of
       my/custom/event:

          foo:
            reg.list:
              - add: bar
              - match: my/custom/event

       When such an event is found, the data found in the payload dictionary key of bar  will  be
       stored  in  a  register  called foo. This register will store that data in a list. You may
       also use reg.set to add data to a set() instead.

       If you would like to see a copy of the register as it is stored in memory, you can use the
       file.save function:

          myreg:
            file.save

       In  this  case,  each time the register is updated, a copy will be saved in JSON format at
       /var/cache/salt/master/thorium/saves/myreg. If you  would  like  to  see  when  particular
       events  are added to a list-type register, you may add a stamp option to reg.list (but not
       reg.set). With the above two stanzas put together, this would look like:

          foo:
            reg.list:
              - add: bar
              - match: my/custom/event
              - stamp: True

          myreg:
            file.save

       If you would like to only keep a certain number of the most recent register  entries,  you
       may also add a prune option to reg.list (but not reg.set):

          foo:
            reg.list:
              - add: bar
              - match: my/custom/event
              - stamp: True
              - prune: 50

       This example will only keep the 50 most recent entries in the foo register.

   Using Register Data
       Putting  data  in a register is useless if you don’t do anything with it. The check module
       is designed  to  examine  register  data  and  determine  whether  it  matches  the  given
       parameters.  For instance, the check.contains function will return True if the given value
       is contained in the specified register:

          foo:
            reg.list:
              - add: bar
              - match: my/custom/event
              - stamp: True
              - prune: 50
            check.contains:
              - value: somedata

       Used with a require requisite, we can call one of  the  wrapper  modules  and  perform  an
       operation. For example:

          shell_test:
            local.cmd:
              - tgt: dufresne
              - func: cmd.run
              - arg:
                - echo 'thorium success' > /tmp/thorium.txt
              - require:
                - check: foo

       This  stanza  will  only  run if the check.contains function under the foo ID returns true
       (meaning the match was found).

       There are a number of other functions in the check module which  use  different  means  of
       comparing values:

       · gt: Check whether the register entry is greater than the given value

       · gte: Check whether the register entry is greater than or equal to the given value

       · lt: Check whether the register entry is less than the given value

       · lte: Check whether the register entry is less than or equal to the given value

       · eq: Check whether the register entry is equal to the given value

       · ne: Check whether the register entry is not equal to the given value

       There  is also a function called check.event which does not examine the register. Instead,
       it looks directly at an event as it is coming in on the event bus,  and  returns  True  if
       that event’s tag matches. For example:

          salt/foo/*/bar:
            check.event

          run_remote_ex:
            local.cmd:
              - tgt: '*'
              - func: test.ping
              - require:
                - check: salt/foo/*/bar

       This  formula  will look for an event whose tag is salt/foo/<anything>/bar and if it comes
       in, issue a test.ping to all minions.

   Register Persistence
       It is possible to persist the register data to disk when a master is  stopped  gracefully,
       and reload it from disk when the master starts up again. This functionality is provided by
       the returner subsystem, and is enabled whenever any returner containing a load_reg  and  a
       save_reg function is used.

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 digitalocean, 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:
highstate, json, key, overstatestage, pprint, raw, txt, yaml, and many others.

Some outputters are formatted only for data returned from specific functions. 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

When salt cloud creates a new minon, it can automatically add grain information to the
minion configuration file identifying the sources originally used to define it.

The generated grain information will appear similar to:

grains:
salt-cloud:
driver: ec2
provider: my_ec2:ec2
profile: ec2-web

The generation of the salt-cloud grain can be suppressed by the option
enable_cloud_grains: 'False' in the cloud configuration file.

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

providers:
my-openstack:
driver: openstack
region_name: ORD
cloud: mycloud

profiles:
ubuntu-openstack:
provider: my-openstack
size: ds512M
image: CentOS 7
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
Using Salt for OpenStack uses the shade <https://docs.openstack.org/shade/latest/> driver
managed by the openstack-infra team.

This driver can be configured using the /etc/openstack/clouds.yml file with
os-client-config <https://docs.openstack.org/os-client-config/latest/>

myopenstack:
driver: openstack
region_name: RegionOne
cloud: mycloud

Or by just configuring the same auth block directly in the cloud provider config.

myopenstack:
driver: openstack
region_name: RegionOne
auth:
username: 'demo'
password: secret
project_name: 'demo'
auth_url: 'http://openstack/identity'

Both of these methods support using the vendor
<https://docs.openstack.org/os-client-config/latest/user/vendor-support.html> options.

For more information, look at Openstack Cloud Driver Docs

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

Vagrant
The Vagrant driver is a new, experimental driver for controlling a VagrantBox virtual
machine, and installing Salt on it. The target host machine must be a working salt minion,
which is controlled via the salt master using salt-api. For more information, see Getting
Started With Vagrant.

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

Self Signed Certificates with WinRM
Salt-Cloud can use versions of pywinrm<=0.1.1 or pywinrm>=0.2.1.

For versions greater than 0.2.1, winrm_verify_ssl needs to be set to False if the
certificate is self signed and not verifiable.

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 `@`{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). And winrm_verify_ssl can be set to False
to use a self signed certificate.

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 generation
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
· Azure Cli `pip install 'azure-cli>=2.0.12'`

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

load_balancer
Optional. The load-balancer for the VM’s network interface to join. If specified the
backend_pool option need to be set.

backend_pool
Optional. Required if the load_balancer option is set. The load-balancer’s Backend Pool
the VM’s network interface will join.

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.

dns_servers
Optional. A list of the DNS servers to configure for the network interface (will be set on
the VM by the DHCP of the VNET).

my-azurearm-profile:
provider: azurearm-provider
network: mynetwork
dns_servers:
- 10.1.1.4
- 10.1.1.5

availability_set
Optional. If set, the VM will be added to the specified availability set.

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 specify 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: digitalocean
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
tags:
- tag1
- tag2
- tag3

Locations can be obtained using the --list-locations option for the salt-cloud command:

# salt-cloud --list-locations my-digitalocean-config
my-digitalocean-config:
----------
digitalocean:
----------
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:
----------
digitalocean:
----------
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:
----------
digitalocean:
----------
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 DigitalOcean, 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:
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
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 corresponding user (default 'salt') 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 you 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 tags=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 together 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:
Empty strings as values for service_account_private_key and
service_account_email_address can be used on GCE instances. This will result in the
service account assigned to the GCE instance being used.

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/

Host Dependencies
· libvirt >= 1.2.18 (older might work)

Salt-Cloud Dependencies
· libvirt-python

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
# work around flag for XML validation errors while cloning
validate_xml: no

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 2GB
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 2GB:
----------
AVAIL:
----------
10:
500
11:
500
2:
500
3:
500
4:
500
6:
500
7:
500
8:
500
9:
500
CORES:
1
DISK:
50
HOURLY:
0.015
LABEL:
Linode 2GB
PLANID:
2
PRICE:
10.0
RAM:
2048
XFER:
2000
...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 1and1
1&1 is one of the world’s leading Web hosting providers. 1&1 currently offers a wide range
of Web hosting products, including email solutions and high-end servers in 10 different
countries including Germany, Spain, Great Britain and the United States. From domains to
1&1 MyWebsite to eBusiness solutions like Cloud Hosting and Web servers for complex tasks,
1&1 is well placed to deliver a high quality service to its customers. All 1&1 products
are hosted in 1&1‘s high-performance, green data centers in the USA and Europe.

Dependencies
· 1and1 >= 1.2.0

Configuration
· Using the new format, set up the cloud configuration at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/oneandone.conf:

my-oneandone-config:
driver: oneandone

# Set the location of the salt-master
#
minion:
master: saltmaster.example.com

# Configure oneandone authentication credentials
#
api_token: <api_token>
ssh_private_key: /path/to/id_rsa
ssh_public_key: /path/to/id_rsa.pub

Authentication
The api_key is used for API authorization. This token can be obtained from the CloudPanel
in the Management section below Users.

Profiles
Here is an example of a profile:

oneandone_fixed_size:
provider: my-oneandone-config
description: Small instance size server
fixed_instance_size: S
appliance_id: 8E3BAA98E3DFD37857810E0288DD8FBA

oneandone_custom_size:
provider: my-oneandone-config
description: Custom size server
vcore: 2
cores_per_processor: 2
ram: 8
appliance_id: 8E3BAA98E3DFD37857810E0288DD8FBA
hdds:
-
is_main: true
size: 20
-
is_main: false
size: 20

The following list explains some of the important properties.

fixed_instance_size_id
When creating a server, either fixed_instance_size_id or custom hardware params
containing vcore, cores_per_processor, ram, and hdds must be provided. Can be one
of the IDs listed among the output of the following command:

salt-cloud --list-sizes oneandone

vcore Total amount of processors.

cores_per_processor
Number of cores per processor.

ram RAM memory size in GB.

hdds Hard disks.

appliance_id
ID of the image that will be installed on server. Can be one of the IDs listed in
the output of the following command:

salt-cloud --list-images oneandone

datacenter_id
ID of the datacenter where the server will be created. Can be one of the IDs
listed in the output of the following command:

salt-cloud --list-locations oneandone

description
Description of the server.

password
Password of the server. Password must contain more than 8 characters using
uppercase letters, numbers and other special symbols.

power_on
Power on server after creation. Default is set to true.

firewall_policy_id
Firewall policy ID. If it is not provided, the server will assign the best firewall
policy, creating a new one if necessary. If the parameter is sent with a 0 value,
the server will be created with all ports blocked.

ip_id IP address ID.

load_balancer_id
Load balancer ID.

monitoring_policy_id
Monitoring policy ID.

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 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 Cloud Driver
depends
shade

OpenStack is an open source project that is in use by a number a cloud providers, each of
which have their own ways of using it.

This OpenStack driver uses a the shade python module which is managed by the OpenStack
Infra team. This module is written to handle all the different versions of different
OpenStack tools for salt, so most commands are just passed over to the module to handle
everything.

Provider
There are two ways to configure providers for this driver. The first one is to just let
shade handle everything, and configure using os-client-config and setting up
/etc/openstack/clouds.yml.

clouds:
democloud:
region_name: RegionOne
auth:
username: 'demo'
password: secret
project_name: 'demo'
auth_url: 'http://openstack/identity'

And then this can be referenced in the salt provider based on the democloud name.

myopenstack:
driver: openstack
cloud: democloud
region_name: RegionOne

This allows for just using one configuration for salt-cloud and for any other openstack
tools which are all using /etc/openstack/clouds.yml

The other method allows for specifying everything in the provider config, instead of using
the extra configuration file. This will allow for passing salt-cloud configs only through
pillars for minions without having to write a clouds.yml file on each minion.abs

myopenstack:
driver: openstack
region_name: RegionOne
auth:
username: 'demo'
password: secret
project_name: 'demo'
auth_url: 'http://openstack/identity'

Or if you need to use a profile to setup some extra stuff, it can be passed as a profile
to use any of the vendor config options.

myrackspace:
driver: openstack
profile: rackspace
auth:
username: rackusername
api_key: myapikey
region_name: ORD
auth_type: rackspace_apikey

And this will pull in the profile for rackspace and setup all the correct options for the
auth_url and different api versions for services.

Profile
Most of the options for building servers are just passed on to the create_server function
from shade.

The salt specific ones are:

· ssh_key_file: The path to the ssh key that should be used to login to the machine to
bootstrap it

· ssh_key_file: The name of the keypair in openstack

· userdata_template: The renderer to use if the userdata is a file that is templated.
Default: False

· ssh_interface: The interface to use to login for bootstrapping: public_ips,
private_ips, floating_ips, fixed_ips

centos:
provider: myopenstack
image: CentOS 7
size: ds1G
ssh_key_name: mykey
ssh_key_file: /root/.ssh/id_rsa

This is the minimum setup required.

If metadata is set to make sure that the host has finished setting up the
wait_for_metadata can be set.

centos:
provider: myopenstack
image: CentOS 7
size: ds1G
ssh_key_name: mykey
ssh_key_file: /root/.ssh/id_rsa
meta:
build_config: rack_user_only
wait_for_metadata:
rax_service_level_automation: Complete
rackconnect_automation_status: DEPLOYED

Anything else from the create_server docs can be passed through here.

image: Image dict, name or ID to boot with. image is required
unless boot_volume is given.

· flavor: Flavor dict, name or ID to boot onto.

auto_ip: Whether to take actions to find a routable IP for
the server. (defaults to True)

· ips: List of IPs to attach to the server (defaults to None)

ip_pool: Name of the network or floating IP pool to get an
address from. (defaults to None)

root_volume: Name or ID of a volume to boot from
(defaults to None - deprecated, use boot_volume)

boot_volume: Name or ID of a volume to boot from
(defaults to None)

terminate_volume: If booting from a volume, whether it should
be deleted when the server is destroyed. (defaults to False)

· volumes: (optional) A list of volumes to attach to the server

meta: (optional) A dict of arbitrary key/value metadata to
store for this server. Both keys and values must be <=255 characters.

files: (optional, deprecated) A dict of files to overwrite
on the server upon boot. Keys are file names (i.e. /etc/passwd) and values are
the file contents (either as a string or as a file-like object). A maximum of
five entries is allowed, and each file must be 10k or less.

· reservation_id: a UUID for the set of servers being requested.

min_count: (optional extension) The minimum number of
servers to launch.

max_count: (optional extension) The maximum number of
servers to launch.

· security_groups: A list of security group names

userdata: user data to pass to be exposed by the metadata
server this can be a file type object as well or a string.

key_name: (optional extension) name of previously created
keypair to inject into the instance.

availability_zone: Name of the availability zone for instance
placement.

block_device_mapping: (optional) A dict of block
device mappings for this server.

block_device_mapping_v2: (optional) A dict of block
device mappings for this server.

nics: (optional extension) an ordered list of nics to be
added to this server, with information about connected networks, fixed IPs, port
etc.

scheduler_hints: (optional extension) arbitrary key-value pairs
specified by the client to help boot an instance

config_drive: (optional extension) value for config drive
either boolean, or volume-id

disk_config: (optional extension) control how the disk is
partitioned when the server is created. possible values are ‘AUTO’ or ‘MANUAL’.

admin_pass: (optional extension) add a user supplied admin
password.

timeout: (optional) Seconds to wait, defaults to 60.
See the wait parameter.

reuse_ips: (optional) Whether to attempt to reuse pre-existing
floating ips should a floating IP be needed (defaults to True)

network: (optional) Network dict or name or ID to attach the
server to. Mutually exclusive with the nics parameter. Can also be be a list of
network names or IDs or network dicts.

boot_from_volume: Whether to boot from volume. ‘boot_volume’
implies True, but boot_from_volume=True with no boot_volume is valid and will
create a volume from the image and use that.

volume_size: When booting an image from volume, how big should
the created volume be? Defaults to 50.

nat_destination: Which network should a created floating IP
be attached to, if it’s not possible to infer from the cloud’s configuration.
(Optional, defaults to None)

group: ServerGroup dict, name or id to boot the server in.
If a group is provided in both scheduler_hints and in the group param, the group
param will win. (Optional, defaults to None)

NOTE:
If there is anything added, that is not in this list, it can be added to an extras
dictionary for the profile, and that will be to the create_server function.

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_id is the UUID of a pre-existing virtual data center.
datacenter_id: 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

# Public key to add to /root/.ssh/authorized_keys.
pubkey: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABA...'

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/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 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 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 can have 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
driver: saltify

However, if you wish to use the more advanced capabilities of salt-cloud, such as
rebooting, listing, and disconnecting machines, then the salt master must fill the role
usually performed by a vendor’s cloud management system. The salt master must be running
on the salt-cloud machine, and created nodes must be connected to the master.

Additional information about which configuration options apply to which actions can be
studied in the Saltify Module documentation and the Miscellaneous Salt Cloud Options
document.

Profiles
Saltify requires a separate profile to be configured for each machine that needs Salt
installed [1]. 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.

[1] Unless you are using a map file to provide the unique parameters.

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 accepted by 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.version

Destroy Options
New in version 2018.3.0.

For obvious reasons, the destroy action does not actually vaporize hardware. If the salt
master is connected, it can tear down parts of the client machines. It will remove the
client’s key from the salt master, and can execute the following options:

- remove_config_on_destroy: true
# default: true
# Deactivate salt-minion on reboot and
# delete the minion config and key files from its "/etc/salt" directory,
# NOTE: If deactivation was unsuccessful (older Ubuntu machines) then when
# salt-minion restarts it will automatically create a new, unwanted, set
# of key files. Use the "force_minion_config" option to replace them.

- shutdown_on_destroy: false
# default: false
# last of all, send a "shutdown" command to the client.

Wake On LAN
New in version 2018.3.0.

In addition to connecting a hardware machine to a Salt master, you have the option of
sending a wake-on-LAN magic packet to start that machine running.

The “magic packet” must be sent by an existing salt minion which is on the same network
segment as the target machine. (Or your router must be set up especially to route WoL
packets.) Your target machine must be set up to listen for WoL and to respond
appropriately.

You must provide the Salt node id of the machine which will send the WoL packet (parameter
wol_sender_node), and the hardware MAC address of the machine you intend to wake,
(parameter wake_on_lan_mac). If both parameters are defined, the WoL will be sent. The
cloud master will then sleep a while (parameter wol_boot_wait) to give the target machine
time to boot up before we start probing its SSH port to begin deploying Salt to it. The
default sleep time is 30 seconds.

# /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
wake_on_lan_mac: '00:e0:4c:70:2a:b2' # found with ifconfig
wol_sender_node: bevymaster # its on this network segment
wol_boot_wait: 45 # seconds to sleep

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.

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
# Use a dedicated host instead of cloud
dedicated_host_id: 1234
# 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

Dedicated Host
Soflayer allows the creation of new VMs in a dedicated host. This means that you can order
and pay a fixed amount for a bare metal dedicated host and use it to provision as many VMs
as you can fit in there. If you want your VMs to be launched in a dedicated host, instead
of Sofltayer’s cloud, set the dedicated_host_id parameter in your profile.

dedicated_host_id
The id of the dedicated host where the VMs should be created. If not set, VMs will be
created in Softlayer’s cloud instead.

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

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

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 Vagrant
The Vagrant driver is a new, experimental driver for spinning up a VagrantBox virtual
machine, and installing Salt on it.

Dependencies
The Vagrant driver itself has no external dependencies.

The machine which will host the VagrantBox must be an already existing minion of the cloud
server’s Salt master. It must have Vagrant installed, and a Vagrant-compatible virtual
machine engine, such as VirtualBox. (Note: The Vagrant driver does not depend on the
salt-cloud VirtualBox driver in any way.)

[Caution: The version of Vagrant packaged for apt install in Ubuntu 16.04 will not connect
a bridged network adapter correctly. Use a version downloaded directly from the web site.]

Include the Vagrant guest editions plugin: vagrant plugin install vagrant-vbguest.

Configuration
Configuration of the client virtual machine (using VirtualBox, VMware, etc) will be done
by Vagrant as specified in the Vagrantfile on the host machine.

Salt-cloud will push the commands to install and provision a salt minion on the virtual
machine, so you need not (perhaps should not) provision salt in your Vagrantfile, in most
cases.

If, however, your cloud master cannot open an SSH connection to the child VM, you may need
to let Vagrant provision the VM with Salt, and use some other method (such as passing a
pillar dictionary to the VM) to pass the master’s IP address to the VM. The VM can then
attempt to reach the salt master in the usual way for non-cloud minions. Specify the
profile configuration argument as deploy: False to prevent the cloud master from trying.

# Note: This example is for /etc/salt/cloud.providers file or any file in
# the /etc/salt/cloud.providers.d/ directory.

my-vagrant-config:
minion:
master: 111.222.333.444
provider: vagrant

Because the Vagrant driver needs a place to store the mapping between the node name you
use for Salt commands and the Vagrantfile which controls the VM, you must configure your
salt minion as a Salt smb server. (See host provisioning example below.)

Profiles
Vagrant 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 a vagrantfile parameter. If the Vagrantfile has definitions for
multiple machines then you need a machine parameter,

Salt-cloud uses SSH to provision the minion. There must be a routable path from the cloud
master to the VM. Usually, you will want to use a bridged network adapter for SSH. The
address may not be known until DHCP assigns it. If ssh_host is not defined, and
target_network is defined, the driver will attempt to read the address from the output of
an ifconfig command. Lacking either setting, the driver will try to use the value Vagrant
returns as its ssh_host, which will work only if the cloud master is running somewhere on
the same host.

The target_network setting should be used to identify the IP network your bridged adapter
is expected to appear on. Use CIDR notation, like target_network: '2001:DB8::/32' or
target_network: '192.0.2.0/24'.

Profile configuration example:

# /etc/salt/cloud.profiles.d/vagrant.conf

vagrant-machine:
host: my-vhost # the Salt id of the virtual machine's host computer.
provider: my-vagrant-config
cwd: /srv/machines # the path to your Virtualbox file.
vagrant_runas: my-username # the username who defined the Vagrantbox on the host
# vagrant_up_timeout: 300 # (seconds) timeout for cmd.run of the "vagrant up" command
# vagrant_provider: '' # option for "vagrant up" like: "--provider vmware_fusion"
# ssh_host: None # "None" means try to find the routable IP address from "ifconfig"
# ssh_username: '' # also required when ssh_host is used.
# target_network: None # Expected CIDR address range of your bridged network
# force_minion_config: false # Set "true" to re-purpose an existing VM

The machine can now be created and configured with the following command:

salt-cloud -p vagrant-machine my-id

This will create the machine specified by the cloud profile vagrant-machine, and will give
the machine the minion id of my-id. If the cloud master is also the salt-master, its Salt
key will automatically be accepted on the master.

Once a salt-minion has been successfully installed on the instance, connectivity to it can
be verified with Salt:

salt my-id test.ping

Provisioning a Vagrant cloud host (example)
In order to query or control minions it created, each host minion needs to track the Salt
node names associated with any guest virtual machines on it. It does that using a Salt
sdb database.

The Salt sdb is not configured by default. The following example shows a simple
installation.

This example assumes:

· you are on a large network using the 10.x.x.x IP address space

· your Salt master’s Salt id is “bevymaster”

· it will also be your salt-cloud controller

· it is at hardware address 10.124.30.7

· it is running a recent Debian family Linux (raspbian)

· your workstation is a Salt minion of bevymaster

· your workstation’s minion id is “my_laptop”

· VirtualBox has been installed on “my_laptop” (apt install is okay)

· Vagrant was installed from vagrantup.com. (not the 16.04 Ubuntu apt)

· “my_laptop” has done “vagrant plugin install vagrant-vbguest”

· the VM you want to start is on “my_laptop” at “/home/my_username/Vagrantfile”

# file /etc/salt/minion.d/vagrant_sdb.conf on host computer "my_laptop"
# -- this sdb database is required by the Vagrant module --
vagrant_sdb_data: # The sdb database must have this name.
driver: sqlite3 # Let's use SQLite to store the data ...
database: /var/cache/salt/vagrant.sqlite # ... in this file ...
table: sdb # ... using this table name.
create_table: True # if not present

Remember to re-start your minion after changing its configuration files…
sudo systemctl restart salt-minion

# -*- mode: ruby -*-
# file /home/my_username/Vagrantfile on host computer "my_laptop"
BEVY = "bevy1"
DOMAIN = BEVY + ".test" # .test is an ICANN reserved non-public TLD

# must supply a list of names to avoid Vagrant asking for interactive input
def get_good_ifc() # try to find a working Ubuntu network adapter name
addr_infos = Socket.getifaddrs
addr_infos.each do |info|
a = info.addr
if a and a.ip? and not a.ip_address.start_with?("127.")
return info.name
end
end
return "eth0" # fall back to an old reliable name
end

Vagrant.configure(2) do |config|
config.ssh.forward_agent = true # so you can use git ssh://...

# add a bridged network interface. (try to detect name, then guess MacOS names, too)
interface_guesses = [get_good_ifc(), 'en0: Ethernet', 'en1: Wi-Fi (AirPort)']
config.vm.network "public_network", bridge: interface_guesses
if ARGV[0] == "up"
puts "Trying bridge network using interfaces: #{interface_guesses}"
end
config.vm.provision "shell", inline: "ip address", run: "always" # make user feel good

# . . . . . . . . . . . . Define machine QUAIL1 . . . . . . . . . . . . . .
config.vm.define "quail1", primary: true do |quail_config|
quail_config.vm.box = "boxesio/xenial64-standard" # a public VMware & Virtualbox box
quail_config.vm.hostname = "quail1." + DOMAIN # supply a name in our bevy
quail_config.vm.provider "virtualbox" do |v|
v.memory = 1024 # limit memory for the virtual box
v.cpus = 1
v.linked_clone = true # make a soft copy of the base Vagrant box
v.customize ["modifyvm", :id, "--natnet1", "192.168.128.0/24"] # do not use 10.x network for NAT
end
end
end

# file /etc/salt/cloud.profiles.d/my_vagrant_profiles.conf on bevymaster
q1:
host: my_laptop # the Salt id of your virtual machine host
machine: quail1 # a machine name in the Vagrantfile (if not primary)
vagrant_runas: my_username # owner of Vagrant box files on "my_laptop"
cwd: '/home/my_username' # the path (on "my_laptop") of the Vagrantfile
provider: my_vagrant_provider # name of entry in provider.conf file
target_network: '10.0.0.0/8' # VM external address will be somewhere here

# file /etc/salt/cloud.providers.d/vagrant_provider.conf on bevymaster
my_vagrant_provider:
driver: vagrant
minion:
master: 10.124.30.7 # the hard address of the master

Create and use your new Salt minion
· Typing on the Salt master computer bevymaster, tell it to create a new minion named v1
using profile q1…

sudo salt-cloud -p q1 v1
sudo salt v1 network.ip_addrs
[ you get a list of IP addresses, including the bridged one ]

· logged in to your laptop (or some other computer known to GitHub)…
[NOTE:] if you are using MacOS, you need to type ssh-add -K after each boot, unless
you use one of the methods in this gist.

ssh -A vagrant@< the bridged network address >
# [ or, if you are at /home/my_username/ on my_laptop ]
vagrant ssh quail1

· then typing on your new node “v1” (a.k.a. quail1.bevy1.test)…

password: vagrant
# [ stuff types out ... ]

ls -al /vagrant
# [ should be shared /home/my_username from my_laptop ]

# you can access other network facilities using the ssh authorization
# as recorded in your ~.ssh/ directory on my_laptop ...

sudo apt update
sudo apt install git
git clone ssh://git@github.com/yourID/your_project
# etc...

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
annotation: Created by Salt-Cloud

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

New in version 2016.11.0.

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.

eagerly_scrub
Specifies whether the disk should be rewrite with zeros during thick
provisioning or not. Default is eagerly_scrub: 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.

annotation
User-provided description of the virtual machine. This will store a message in the
vSphere interface, under the annotations section in the Summary view of the virtual
machine.

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'

Getting Started With Xen
The Xen cloud driver works with Citrix XenServer.

It can be used with a single XenServer or a XenServer resource pool.

Setup Dependencies
This driver requires a copy of the freely available XenAPI.py Python module.

Information about the Xen API Python module in the XenServer SDK can be found at
https://xenserver.org/partners/developing-products-for-xenserver.html

Place a copy of this module on your system. For example, it can be placed in the site
packages location on your system.

The location of site packages can be determined by running:

python -m site --user-site

Provider Configuration
Xen requires login credentials to a XenServer.

Set up the provider cloud configuration file at /etc/salt/cloud.providers or
/etc/salt/cloud.providers.d/*.conf.

# /etc/salt/cloud.providers.d/myxen.conf
myxen:
driver: xen
url: https://10.0.0.120
user: root
password: p@ssw0rd

url: The url option supports both http and https uri prefixes.

user: A valid user id to login to the XenServer host.

password:
The associated password for the user.

NOTE:
Changed in version 2015.8.0.

Profile Configuration
Xen profiles require a provider and image.

provider:
This will be the name of your defined provider.

image: The name of the VM template used to clone or copy.

clone: The default behavior is to clone a template or VM. This is very fast, but requires
the source template or VM to be in the same storage repository of the new target
system. If the source and target are in different storage repositories then you
must copy the source and not clone it by setting clone: False.

deploy:
The provisioning process will attempt to install the Salt minion service on the new
target system by default. This will require login credentials for Salt cloud to
login via ssh to it. The user and password options are required. If deploy is set
to False then these options are not needed.

resource_pool:
The name of the resource pool used for this profile.

storage_repo:
The name of the storage repository for the target system.

ipv4_cidr:
If template is Windows, and running guest tools then a static ip address can be
set.

ipv4_gw:
If template is Windows, and running guest tools then a gateway can be set.

Set up an initial profile at /etc/salt/cloud.profiles or in the
/etc/salt/cloud.profiles.d/ directory:

# file: /etc/salt/cloud.profiles.d/xenprofiles.conf
sles:
provider: myxen
deploy: False
image: sles12sp2-template

suse:
user: root
password: p@ssw0rd
provider: myxen
image: opensuseleap42_2-template
storage_repo: 'Local storage'
clone: False
minion:
master: 10.0.0.20

w2k12:
provider: myxen
image: w2k12svr-template
clone: True
userdata_file: /srv/salt/win/files/windows-firewall.ps1
win_installer: /srv/salt/win/files/Salt-Minion-2016.11.3-AMD64-Setup.exe
win_username: Administrator
win_password: p@ssw0rd
use_winrm: False
ipv4_cidr: 10.0.0.215/24
ipv4_gw: 10.0.0.1
minion:
master: 10.0.0.21

The first example will create a clone of the sles12sp2-template in the same storage
repository without deploying the Salt minion.

The second example will make a copy of the image and deploy a new suse VM with the Salt
minion installed.

The third example will create a clone of the Windows 2012 template and deploy the Salt
minion.

The profile can be used with a salt command:

salt-cloud -p suse xenvm02

This will create an salt minion instance named xenvm02 in Xen. 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 xenvm02 test.ping

Listing Sizes
Sizes can be obtained using the --list-sizes option for the salt-cloud command:

# salt-cloud --list-sizes myxen

NOTE:
Since size information is build in a template this command is not implemented.

Listing Images
Images can be obtained using the --list-images option for the salt-cloud command:

# salt-cloud --list-images myxen

This command will return a list of templates with details.

Listing Locations
Locations can be obtained using the --list-locations option for the salt-cloud command:

# salt-cloud --list-locations myxen

Returns a list of resource pools.

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

Running Pre-Flight Commands
New in version 2018.3.0.

To execute specified preflight shell commands on a VM before the deploy script is run, use
the preflight_cmds option. These must be defined as a list in a cloud configuration file.
For example:

my-cloud-profile:
provider: linode-config
image: Ubuntu 16.04 LTS
size: Linode 2048
preflight_cmds:
- whoami
- echo 'hello world!'

These commands will run in sequence before the bootstrap script is executed.

Force Minion Config
New in version 2018.3.0.

The force_minion_config option requests the bootstrap process to overwrite an existing
minion configuration file and public/private key files. Default: False

This might be important for drivers (such as saltify) which are expected to take over a
connection from a former salt master.

my_saltify_provider:
driver: saltify
force_minion_config: true

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
import salt.utils.functools

And then a series of declarations will make the necessary functions available within the
cloud module.

get_size = salt.utils.functools.namespaced_function(get_size, globals())
get_image = salt.utils.functools.namespaced_function(get_image, globals())
avail_locations = salt.utils.functools.namespaced_function(avail_locations, globals())
avail_images = salt.utils.functools.namespaced_function(avail_images, globals())
avail_sizes = salt.utils.functools.namespaced_function(avail_sizes, globals())
script = salt.utils.functools.namespaced_function(script, globals())
destroy = salt.utils.functools.namespaced_function(destroy, globals())
list_nodes = salt.utils.functools.namespaced_function(list_nodes, globals())
list_nodes_full = salt.utils.functools.namespaced_function(list_nodes_full, globals())
list_nodes_select = salt.utils.functools.namespaced_function(list_nodes_select, globals())
show_instance = salt.utils.functools.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/digitalocean.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/blob/develop/salt/cloud/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.

┌──────────┬──────────┬────────────┬─────────┬─────┬────────┬────────┬────────┬───────────┬───────────┬───────────┬─────────┬─────────┬───────────┬───────────┬────────┐
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
├──────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼─────────┼─────────┼───────────┼───────────┼────────┤
└──────────┴──────────┴────────────┴─────────┴─────┴────────┴────────┴────────┴───────────┴───────────┴───────────┴─────────┴─────────┴───────────┴───────────┴────────┘

[1] Yes, if salt-api is enabled.

[2] Always returns {}.

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

┌───────────────────────┬──────────┬────────────┬─────────┬─────┬────────┬────────┬────────┬───────────┬───────────┬───────────┬───────────────────────┬───────────┬───────────┬────────┐
│ │ (Legacy) │ │ Ocean │ │ │ │ │ │ │ (Legacy) │ Saltify& │ │ Hardware │ │
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├───────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
└───────────────────────┴──────────┴────────────┴─────────┴─────┴────────┴────────┴────────┴───────────┴───────────┴───────────┴───────────────────────┴───────────┴───────────┴────────┘

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

┌────────────────────────┬──────────┬────────────┬─────────┬─────┬────────┬────────┬────────┬───────────┬───────────┬───────────┬───────────────────────┬───────────┬───────────┬────────┐
│ │ (Legacy) │ │ Ocean │ │ │ │ │ │ │ (Legacy) │ Saltify& │ │ Hardware │ │
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
├────────────────────────┼──────────┼────────────┼─────────┼─────┼────────┼────────┼────────┼───────────┼───────────┼───────────┼───────────────────────┼───────────┼───────────┼────────┤
└────────────────────────┴──────────┴────────────┴─────────┴─────┴────────┴────────┴────────┴───────────┴───────────┴───────────┴───────────────────────┴───────────┴───────────┴────────┘

[1] Yes, if salt-api is enabled.

Tutorials
Salt Cloud Quickstart
Salt Cloud is built-in to Salt, and the easiest way to run Salt Cloud is directly from
your Salt Master.

Alternatively, the -L option can be passed to the Salt Bootstrap script when installing
Salt. The -L option will install salt-cloud and the required libcloud package.

This quickstart walks you through the basic steps of setting up a cloud host and defining
some virtual machines to create.

NOTE:
Salt Cloud has its own process and does not rely on the Salt Master, so it can be
installed on a standalone minion instead of your Salt Master.

Define a Provider
The first step is to add the credentials for your cloud host. Credentials and other
settings provided by the cloud host are stored in provider configuration files. Provider
configurations contain the details needed to connect to a cloud host such as EC2, GCE,
Rackspace, etc., and any global options that you want set on your cloud minions (such as
the location of your Salt Master).

On your Salt Master, browse to /etc/salt/cloud.providers.d/ and create a file called
<provider>.conf, replacing <provider> with ec2, softlayer, and so on. The name helps you
identify the contents, and is not important as long as the file ends in .conf.

Next, browse to the Provider specifics and add any required settings for your cloud host
to this file. Here is an example for Amazon EC2:

my-ec2:
driver: ec2
# Set the EC2 access credentials (see below)
#
id: 'HJGRYCILJLKJYG'
key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
# Make sure this key is owned by root with permissions 0400.
#
private_key: /etc/salt/my_test_key.pem
keyname: my_test_key
securitygroup: default
# Optional: Set up the location of the Salt Master
#
minion:
master: saltmaster.example.com

The required configuration varies between cloud hosts so make sure you read the provider
specifics.

List Cloud Provider Options
You can now query the cloud provider you configured for available locations, images, and
sizes. This information is used when you set up VM profiles.

salt-cloud --list-locations <provider_name> # my-ec2 in the previous example
salt-cloud --list-images <provider_name>
salt-cloud --list-sizes <provider_name>

Replace <provider_name> with the name of the provider configuration you defined.

Create VM Profiles
On your Salt Master, browse to /etc/salt/cloud.profiles.d/ and create a file called
<profile>.conf, replacing <profile> with ec2, softlayer, and so on. The file must end in
.conf.

You can now add any custom profiles you’d like to define to this file. Here are a few
examples:

micro_ec2:
provider: my-ec2
image: ami-d514f291
size: t1.micro

medium_ec2:
provider: my-ec2
image: ami-d514f291
size: m3.medium

large_ec2:
provider: my-ec2
image: ami-d514f291
size: m3.large

Notice that the provider in our profile matches the provider name that we defined? That is
how Salt Cloud knows how to connect to a cloud host to create a VM with these attributes.

Create VMs
VMs are created by calling salt-cloud with the following options:

salt-cloud -p <profile> <name1> <name2> ...

For example:

salt-cloud -p micro_ec2 minion1 minion2

Destroy VMs
Add a -d and the minion name you provided to destroy:

salt-cloud -d minion1 minion2

Query VMs
You can view details about the VMs you’ve created using --query:

salt-cloud --query

Cloud Map
Now that you know how to create and destoy individual VMs, next you should learn how to
use a cloud map to create a number of VMs at once.

Cloud maps let you define a map of your infrastructure and quickly provision any number of
VMs. On subsequent runs, any VMs that do not exist are created, and VMs that are already
configured are left unmodified.

See Cloud Map File.

Using Salt Cloud with the Event Reactor
One of the most powerful features of the Salt framework is the Event Reactor. As the
Reactor was in development, Salt Cloud was regularly updated to take advantage of the
Reactor upon completion. As such, various aspects of both the creation and destruction of
instances with Salt Cloud fire events to the Salt Master, which can be used by the Event
Reactor.

Event Structure
As of this writing, all events in Salt Cloud have a tag, which includes the ID of the
instance being managed, and a payload which describes the task that is currently being
handled. A Salt Cloud tag looks like:

salt/cloud/<minion_id>/<task>

For instance, the first event fired when creating an instance named web1 would look like:

salt/cloud/web1/creating

Assuming this instance is using the ec2-centos profile, which is in turn using the
ec2-config provider, the payload for this tag would look like:

{'name': 'web1',
'profile': 'ec2-centos',
'provider': 'ec2-config:ec2'}

Available Events
When an instance is created in Salt Cloud, whether by map, profile, or directly through an
API, a minimum of five events are normally fired. More may be available, depending upon
the cloud provider being used. Some of the common events are described below.

salt/cloud/<minion_id>/creating
This event states simply that the process to create an instance has begun. At this point
in time, no actual work has begun. The payload for this event includes:

name profile provider

salt/cloud/<minion_id>/requesting
Salt Cloud is about to make a request to the cloud provider to create an instance. At this
point, all of the variables required to make the request have been gathered, and the
payload of the event will reflect those variables which do not normally pose a security
risk. What is returned here is dependent upon the cloud provider. Some common variables
are:

name image size location

salt/cloud/<minion_id>/querying
The instance has been successfully requested, but the necessary information to log into
the instance (such as IP address) is not yet available. This event marks the beginning of
the process to wait for this information.

The payload for this event normally only includes the instance_id.

salt/cloud/<minion_id>/waiting_for_ssh
The information required to log into the instance has been retrieved, but the instance is
not necessarily ready to be accessed. Following this event, Salt Cloud will wait for the
IP address to respond to a ping, then wait for the specified port (usually 22) to respond
to a connection, and on Linux systems, for SSH to become available. Salt Cloud will
attempt to issue the date command on the remote system, as a means to check for
availability. If no ssh_username has been specified, a list of usernames (starting with
root) will be attempted. If one or more usernames was configured for ssh_username, they
will be added to the beginning of the list, in order.

The payload for this event normally only includes the ip_address.

salt/cloud/<minion_id>/deploying
The necessary port has been detected as available, and now Salt Cloud can log into the
instance, upload any files used for deployment, and run the deploy script. Once the script
has completed, Salt Cloud will log back into the instance and remove any remaining files.

A number of variables are used to deploy instances, and the majority of these will be
available in the payload. Any keys, passwords or other sensitive data will be scraped from
the payload. Most of the variables returned will be related to the profile or provider
config, and any default values that could have been changed in the profile or provider,
but weren’t.

salt/cloud/<minion_id>/created
The deploy sequence has completed, and the instance is now available, Salted, and ready
for use. This event is the final task for Salt Cloud, before returning instance
information to the user and exiting.

The payload for this event contains little more than the initial creating event. This
event is required in all cloud providers.

Filtering Events
When creating a VM, it is possible with certain tags to filter how much information is
sent to the event bus. The tags that can be filtered on any provider are:

· salt/cloud/<minion_id>/creating

· salt/cloud/<minion_id>/requesting

· salt/cloud/<minion_id>/created

Other providers may allow other tags to be filtered; when that is the case, the
documentation for that provider will contain more details.

To filter information, create a section in your /etc/salt/cloud file called filter_events.
Create a section for each tag that you want to filter, using the last segment of the tag.
For instance, use creating to represent salt/cloud/<minion_id>/creating:

filter_events:
creating:
keys:
- name
- profile
- provider

Any keys listed here will be added to the default keys that are already set to be
displayed for that provider. If you wish to start with a clean slate and only show the
keys specified, add another option called use_defaults and set it to False.

filter_events:
creating:
keys:
- name
- profile
- provider
use_defaults: False

Configuring the Event Reactor
The Event Reactor is built into the Salt Master process, and as such is configured via the
master configuration file. Normally this will be a YAML file located at /etc/salt/master.
Additionally, master configuration items can be stored, in YAML format, inside the
/etc/salt/master.d/ directory.

These configuration items may be stored in either location; however, they may only be
stored in one location. For organizational and security purposes, it may be best to create
a single configuration file, which contains only Event Reactor configuration, at
/etc/salt/master.d/reactor.

The Event Reactor uses a top-level configuration item called reactor. This block contains
a list of tags to be watched for, each of which also includes a list of sls files. For
instance:

reactor:
- 'salt/minion/*/start':
- '/srv/reactor/custom-reactor.sls'
- 'salt/cloud/*/created':
- '/srv/reactor/cloud-alert.sls'
- 'salt/cloud/*/destroyed':
- '/srv/reactor/cloud-destroy-alert.sls'

The above configuration configures reactors for three different tags: one which is fired
when a minion process has started and is available to receive commands, one which is fired
when a cloud instance has been created, and one which is fired when a cloud instance is
destroyed.

Note that each tag contains a wildcard (*) in it. For each of these tags, this will
normally refer to a minion_id. This is not required of event tags, but is very common.

Reactor SLS Files
Reactor sls files should be placed in the /srv/reactor/ directory for consistency between
environments, but this is not currently enforced by Salt.

Reactor sls files follow a similar format to other sls files in Salt. By default they are
written in YAML and can be templated using Jinja, but since they are processed through
Salt’s rendering system, any available renderer (JSON, Mako, Cheetah, etc.) can be used.

As with other sls files, each stanza will start with a declaration ID, followed by the
function to run, and then any arguments for that function. For example:

# /srv/reactor/cloud-alert.sls
new_instance_alert:
cmd.pagerduty.create_event:
- tgt: alertserver
- kwarg:
description: "New instance: {{ data['name'] }}"
details: "New cloud instance created on {{ data['provider'] }}"
service_key: 1626dead5ecafe46231e968eb1be29c4
profile: my-pagerduty-account

When the Event Reactor receives an event notifying it that a new instance has been
created, this sls will create a new incident in PagerDuty, using the configured PagerDuty
account.

The declaration ID in this example is new_instance_alert. The function called is
cmd.pagerduty.create_event. The cmd portion of this function specifies that an execution
module and function will be called, in this case, the pagerduty.create_event function.

Because an execution module is specified, a target (tgt) must be specified on which to
call the function. In this case, a minion called alertserver has been used. Any arguments
passed through to the function are declared in the kwarg block.

Example: Reactor-Based Highstate
When Salt Cloud creates an instance, by default it will install the Salt Minion onto the
instance, along with any specified minion configuration, and automatically accept that
minion’s keys on the master. One of the configuration options that can be specified is
startup_states, which is commonly set to highstate. This will tell the minion to
immediately apply a highstate, as soon as it is able to do so.

This can present a problem with some system images on some cloud hosts. For instance, Salt
Cloud can be configured to log in as either the root user, or a user with sudo access.
While some hosts commonly use images that lock out remote root access and require a user
with sudo privileges to log in (notably EC2, with their ec2-user login), most cloud hosts
fall back to root as the default login on all images, including for operating systems
(such as Ubuntu) which normally disallow remote root login.

For users of these operating systems, it is understandable that a highstate would include
configuration to block remote root logins again. However, Salt Cloud may not have finished
cleaning up its deployment files by the time the minion process has started, and kicked
off a highstate run. Users have reported errors from Salt Cloud getting locked out while
trying to clean up after itself.

The goal of a startup state may be achieved using the Event Reactor. Because a minion
fires an event when it is able to receive commands, this event can effectively be used
inside the reactor system instead. The following will point the reactor system to the
right sls file:

reactor:
- 'salt/cloud/*/created':
- '/srv/reactor/startup_highstate.sls'

And the following sls file will start a highstate run on the target minion:

# /srv/reactor/startup_highstate.sls
reactor_highstate:
cmd.state.apply:
- tgt: {{ data['name'] }}

Because this event will not be fired until Salt Cloud has cleaned up after itself, the
highstate run will not step on salt-cloud’s toes. And because every file on the minion is
configurable, including /etc/salt/minion, the startup_states can still be configured for
future minion restarts, if desired.

SALT PROXY MINION

       Proxy minions are a developing Salt feature that enables  controlling  devices  that,  for
       whatever  reason,  cannot  run a standard salt-minion.  Examples include network gear that
       has an API but runs a proprietary OS, devices with limited CPU or memory, or devices  that
       could run a minion, but for security reasons, will not.

       Proxy  minions  are not an “out of the box” feature.  Because there are an infinite number
       of controllable devices, you will most  likely  have  to  write  the  interface  yourself.
       Fortunately,  this  is  only  as  difficult as the actual interface to the proxied device.
       Devices that have an existing Python module (PyUSB for example) would be relatively simple
       to  interface.   Code  to control a device that has an HTML REST-based interface should be
       easy.  Code to control your typical housecat would be excellent source material for a  PhD
       thesis.

       Salt  proxy-minions  provide  the ‘plumbing’ that allows device enumeration and discovery,
       control, status, remote execution, and state management.

       See the Proxy Minion Walkthrough for an end-to-end demonstration of a  working  REST-based
       proxy minion.

       See  the  Proxy  Minion  SSH  Walkthrough for an end-to-end demonstration of a working SSH
       proxy minion.

       See Proxyminion States to configure and run salt-proxy on a  remote  minion.  Specify  all
       your  master  side  proxy  (pillar) configuration and use this state to remotely configure
       proxies on one or more minions.

       See Proxyminion Beacon to help  with  easy  configuration  and  management  of  salt-proxy
       processes.

   New in 2017.7.0
       The  proxy_merge_grains_in_module  configuration  variable  introduced in 2016.3, has been
       changed, defaulting to True.

       The connection with the remote device is kept alive by default, when the module implements
       the  alive function and proxy_keep_alive is set to True. The polling interval is set using
       the proxy_keep_alive_interval option which defaults to 1 minute.

       The developers are also able to use the proxy_always_alive, when designing a proxy  module
       flexible enough to open the connection with the remote device only when required.

   New in 2016.11.0
       Proxy  minions now support configuration files with names ending in ‘*.conf’ and placed in
       /etc/salt/proxy.d.

       Proxy minions can now be configured in /etc/salt/proxy  or  /etc/salt/proxy.d  instead  of
       just pillar.  Configuration format is the same as it would be in pillar.

   New in 2016.3
       The deprecated config option enumerate_proxy_minions has been removed.

       As  mentioned in earlier documentation, the add_proxymodule_to_opts configuration variable
       defaults to False in this release.  This means if you  have  proxymodules  or  other  code
       looking   in   __opts__['proxymodule']  you  will  need  to  set  this  variable  in  your
       /etc/salt/proxy file, or modify your code to use the __proxy__ injected variable.

       The __proxyenabled__ directive now only applies to grains and  proxy  modules  themselves.
       Standard  execution  modules  and  state  modules are not prevented from loading for proxy
       minions.

       Enhancements in grains  processing  have  made  the  __proxyenabled__  directive  somewhat
       redundant  in  dynamic  grains  code.   It  is  still required, but best practices for the
       __virtual__ function in grains files  have  changed.   It  is  now  recommended  that  the
       __virtual__  functions check to make sure they are being loaded for the correct proxytype,
       example below:

          def __virtual__():
              '''
              Only work on proxy
              '''
              try:
                  if salt.utils.platform.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.  NOTE:  This  function  was  renamed  to
       salt.utils.platform.is_proxy() for the 2018.3.0 release

   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.platform.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 salt.utils.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 salt.utils.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:
              - proxies:
                  p8000: {}
                  p8001: {}

       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

NETWORK AUTOMATION

       Network automation is a continuous process of automating the configuration, management and
       operations  of  a  computer  network.  Although the abstraction could be compared with the
       operations on the server side, there are many particular challenges,  the  most  important
       being  that  a  network  device  is  traditionally closed hardware able to run proprietary
       software only. In other words, the user is not able to  install  the  salt-minion  package
       directly  on  a traditional network device. For these reasons, most network devices can be
       controlled only remotely via proxy minions or using the Salt SSH. However, there are  also
       vendors  producing whitebox equipment (e.g. Arista, Cumulus) or others that have moved the
       operating system  in  the  container  (e.g.  Cisco  NX-OS,  Cisco  IOS-XR),  allowing  the
       salt-minion to be installed directly on the platform.

   New in Carbon (2016.11)
       The  methodologies  for  network  automation  have  been  introduced in 2016.11.0. Network
       automation support is based on proxy minions.

       · NAPALM proxy

       · Junos proxy

       · Cisco NXOS

       · Cisco NOS

   NAPALM
       NAPALM (Network Automation and Programmability Abstraction Layer with Multivendor support)
       is  an  opensourced  Python  library  that  implements a set of functions to interact with
       different router vendor devices using a unified  API.   Being  vendor-agnostic  simplifies
       operations,  as the configuration and interaction with the network device does not rely on
       a particular vendor.  [image]

       Beginning with 2017.7.0, the NAPALM modules have been transformed so they can run in  both
       proxy  and  regular  minions.  That means, if the operating system allows, the salt-minion
       package can be installed directly on the network gear.  The interface between the  network
       operating system and Salt in that case would be the corresponding NAPALM sub-package.

       For example, if the user installs the salt-minion on a Arista switch, the only requirement
       is napalm-eos.

       The following modules are available in 2017.7.0:

       · NAPALM grains

       · NET execution module - Networking basic features

       · NTP execution module

       · BGP execution module

       · Routes execution module

       · SNMP execution module

       · Users execution module

       · Probes execution module

       · NTP peers management state

       · SNMP configuration management state

       · Users management state

       · Netconfig state module - Manage the configuration of  network  devices  using  arbitrary
         templates and the Salt-specific advanced templating methodologies.

       · Network ACL execution module - Generate and load ACL (firewall) configuration on network
         devices.

       · Network ACL state - Manage the firewall configuration.  It  only  requires  writing  the
         pillar structure correctly!

       · NAPALM YANG execution module - Parse, generate and load native device configuration in a
         standard way, using the OpenConfig/IETF models. This module contains  also  helpers  for
         the states.

       · NAPALM YANG state module - Manage the network device configuration according to the YANG
         models (OpenConfig or IETF).

       · NET finder - Runner to find details easily and fast. It’s smart enough to know what  you
         are  looking for. It will search in the details of the network interfaces, IP addresses,
         MAC address tables, ARP tables and LLDP neighbors.

       · BGP finder - Runner to search BGP neighbors details.

       · NAPALM syslog - Engine to import events from the napalm-logs library into the Salt event
         bus. The events are based on the syslog messages from the network devices and structured
         following the OpenConfig/IETF YANG models.

       · NAPALM Helpers -  Generic  helpers  for  NAPALM-related  operations.  For  example,  the
         Compliance  report function can be used inside the state modules to compare the expected
         and the existing configuration.

   Getting started
       Install NAPALM - follow the notes and check the platform-specific dependencies.

       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 may already contain all the details of  proxy  targets.  To  use
       static files in pillar_roots, pattern your files after the following examples:

       /etc/salt/pillar/top.sls

          base:
            router1:
              - router1
            router2:
              - router2
            switch1:
              - swtich1
            swtich2:
              - switch2
            cpe1:
              - cpe1

       /etc/salt/pillar/router1.sls

          proxy:
            proxytype: napalm
            driver: junos
            host: r1.bbone.as1234.net
            username: my_username
            password: my_password

       /etc/salt/pillar/router2.sls

          proxy:
            proxytype: napalm
            driver: iosxr
            host: r2.bbone.as1234.net
            username: my_username
            password: my_password
            optional_args:
              port: 22022

       /etc/salt/pillar/switch1.sls

          proxy:
            proxytype: napalm
            driver: eos
            host: sw1.bbone.as1234.net
            username: my_username
            password: my_password
            optional_args:
              enable_password: my_secret

       /etc/salt/pillar/switch2.sls

          proxy:
            proxytype: napalm
            driver: nxos
            host: sw2.bbone.as1234.net
            username: my_username
            password: my_password

       /etc/salt/pillar/cpe1.sls

          proxy:
            proxytype: napalm
            driver: ios
            host: cpe1.edge.as1234.net
            username: ''
            password: ''
            optional_args:
              use_keys: True
              auto_rollback_on_error: True

   CLI examples
       Display the complete running configuration on router1:

          $ sudo salt 'router1' net.config source='running'

       Retrieve the NTP servers configured on all devices:

          $ sudo salt '*' ntp.servers
          router1:
            ----------
            comment:
            out:
                - 1.2.3.4
            result:
                True
          cpe1:
            ----------
            comment:
            out:
                - 1.2.3.4
            result:
                True
          switch2:
            ----------
            comment:
            out:
                - 1.2.3.4
            result:
                True
          router2:
            ----------
            comment:
            out:
                - 1.2.3.4
            result:
                True
          switch1:
            ----------
            comment:
            out:
                - 1.2.3.4
            result:
                True

       Display the ARP tables on all Cisco devices running IOS-XR 5.3.3:

          $ sudo salt -G 'os:iosxr and version:5.3.3' net.arp

       Return operational details for interfaces from Arista switches:

          $ sudo salt -C 'sw* and os:eos' net.interfaces

       Execute traceroute from the edge of the network:

          $ sudo salt 'router*' net.traceroute 8.8.8.8 vrf='CUSTOMER1-VRF'

       Verbatim display from the CLI of Juniper routers:

          $ sudo salt -C 'router* and G@os:junos' net.cli 'show version and haiku'

       Retrieve the results of the RPM probes configured on Juniper MX960 routers:

          $ sudo salt -C 'router* and G@os:junos and G@model:MX960' probes.results

       Return the list of configured users on the CPEs:

          $ sudo salt 'cpe*' users.config

       Using the BGP finder, return the list of BGP neighbors that are down:

          $ sudo salt-run bgp.neighbors up=False

       Using  the NET finder, determine the devices containing the pattern “PX-1234-LHR” in their
       interface description:

          $ sudo salt-run net.find PX-1234-LHR

   Cross-platform configuration management example: NTP
       Assuming that the user adds the following two lines under file_roots:

          file_roots:
            base:
              - /etc/salt/pillar/
              - /etc/salt/templates/
              - /etc/salt/states/

       Define the list of NTP peers and servers wanted:

       /etc/salt/pillar/ntp.sls

          ntp.servers:
            - 1.2.3.4
            - 5.6.7.8
          ntp.peers:
             - 10.11.12.13
             - 14.15.16.17

       Include the new file: for example, if we want to have the same NTP servers on all  network
       devices, we can add the following line inside the top.sls file:

          '*':
            - ntp

       /etc/salt/pillar/top.sls

          base:
            '*':
              - ntp
            router1:
              - router1
            router2:
              - router2
            switch1:
              - swtich1
            swtich2:
              - switch2
            cpe1:
              - cpe1

       Or include only where needed:

       /etc/salt/pillar/top.sls

          base:
            router1:
              - router1
              - ntp
            router2:
              - router2
              - ntp
            switch1:
              - swtich1
            swtich2:
              - switch2
            cpe1:
              - cpe1

       Define the cross-vendor template:

       /etc/salt/templates/ntp.jinja

          {%- if grains.vendor|lower == 'cisco' %}
            no ntp
            {%- for server in servers %}
            ntp server {{ server }}
            {%- endfor %}
            {%- for peer in peers %}
            ntp peer {{ peer }}
            {%- endfor %}
          {%- elif grains.os|lower == 'junos' %}
            system {
              replace:
              ntp {
                {%- for server in servers %}
                server {{ server }};
                {%- endfor %}
                {%- for peer in peers %}
                peer {{ peer }};
                {%- endfor %}
              }
            }
          {%- endif %}

       Define the SLS state file, making use of the Netconfig state module:

       /etc/salt/states/router/ntp.sls

          ntp_config_example:
            netconfig.managed:
              - template_name: salt://ntp.jinja
              - peers: {{ pillar.get('ntp.peers', []) | json }}
              - servers: {{ pillar.get('ntp.servers', []) | json }}

       Run the state and assure NTP configuration consistency across your multi-vendor network:

          $ sudo salt 'router*' state.sls router.ntp

       Besides CLI, the state can be scheduled or executed when triggered by a certain event.

   JUNOS
       Juniper  has developed a Junos specific proxy infrastructure which allows remote execution
       and configuration management of Junos devices without having to install SaltStack  on  the
       device. The infrastructure includes:

       · Junos proxy

       · Junos execution module

       · Junos state module

       · Junos syslog engine

       The  execution and state modules are implemented using junos-eznc (PyEZ).  Junos PyEZ is a
       microframework for Python that enables you to remotely manage and automate devices running
       the Junos operating system.

   Getting started
       Install  PyEZ  on the system which will run the Junos proxy minion.  It is required to run
       Junos specific modules.

          pip install junos-eznc

       Next, set the master of the proxy minions.

       /etc/salt/proxy

          master: <master_ip>

       Add the details of the Junos device. Device details are usually stored in salt pillars. If
       the you do not wish to store credentials in the pillar, one can setup passwordless ssh.

       /srv/pillar/vmx_details.sls

          proxy:
            proxytype: junos
            host: <hostip>
            username: user
            passwd: secret123

       Map the pillar file to the proxy minion. This is done in the top file.

       /srv/pillar/top.sls

          base:
            vmx:
              - vmx_details

       NOTE:
          Before  starting the Junos proxy make sure that netconf is enabled on the Junos device.
          This can be done by adding the following configuration on the Junos device.

              set system services netconf ssh

       Start the salt master.

          salt-master -l debug

       Then start the salt proxy.

          salt-proxy --proxyid=vmx -l debug

       Once the master and junos proxy minion have  started,  we  can  run  execution  and  state
       modules on the proxy minion. Below are few examples.

   CLI examples
       For  detailed  documentation  of  all  the  junos execution modules refer: Junos execution
       module

       Display device facts.

          $ sudo salt 'vmx' junos.facts

       Refresh the Junos facts. This function will also refresh the facts  which  are  stored  in
       salt grains. (Junos proxy stores Junos facts in the salt grains)

          $ sudo salt 'vmx' junos.facts_refresh

       Call an RPC.

          $ sudo salt 'vmx' junos.rpc 'get-interface-information' '/var/log/interface-info.txt' terse=True

       Install config on the device.

          $ sudo salt 'vmx' junos.install_config 'salt://my_config.set'

       Shutdown the junos device.

          $ sudo salt 'vmx' junos.shutdown shutdown=True in_min=10

   State file examples
       For detailed documentation of all the junos state modules refer: Junos state module

       Executing an RPC on Junos device and storing the output in a file.

       /srv/salt/rpc.sls

          get-interface-information:
              junos:
                - rpc
                - dest: /home/user/rpc.log
                - interface_name: lo0

       Lock the junos device, load the configuration, commit it and unlock the device.

       /srv/salt/load.sls

          lock the config:
            junos.lock

          salt://configs/my_config.set:
            junos:
              - install_config
              - timeout: 100
              - diffs_file: 'var/log/diff'

          commit the changes:
            junos:
              - commit

          unlock the config:
            junos.unlock

       According to the device personality install appropriate image on the device.

       /srv/salt/image_install.sls

          {% if grains['junos_facts']['personality'] == MX %}
          salt://images/mx_junos_image.tgz:
            junos:
              - install_os
              - timeout: 100
              - reboot: True
          {% elif grains['junos_facts']['personality'] == EX %}
          salt://images/ex_junos_image.tgz:
            junos:
              - install_os
              - timeout: 150
          {% elif grains['junos_facts']['personality'] == SRX %}
          salt://images/srx_junos_image.tgz:
            junos:
              - install_os
              - timeout: 150
          {% endif %}

   Junos Syslog Engine
       Junos  Syslog  Engine  is  a  Salt  engine which receives data from various Junos devices,
       extracts event information and forwards it on the master/minion event bus.  To  start  the
       engine on the salt master, add the following configuration in the master config file.  The
       engine can also run on the salt minion.

       /etc/salt/master

          engines:
            - junos_syslog:
                port: xxx

       For junos_syslog engine to receive events, syslog must be set on the Junos  device.   This
       can be done via following configuration:

          set system syslog host <ip-of-the-salt-device> port xxx any any

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.

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.

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

--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, and pam. 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.

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