salt(7) - Linux man page

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

Building 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 licence, 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.

Installation

The Salt system setup is amazingly simple, as this is one of the central design goals of Salt.

See also: Installing Salt for development and contributing to the project.

Quick Install

Many popular distributions will be able to install the salt minion by executing the bootstrap script: wget -O - http://bootstrap.saltstack.org | sudo sh The script should also make it simple to install a salt master, if desired. Currently the install script has been tested to work on:
• Ubuntu 10.x/11.x/12.x • Debian 6.x • CentOS 6.3 • Fedora • Arch • FreeBSD 9.0
See Salt Bootstrap for more information.

Platform-specific installation instructions

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

Arch Linux

Installation

Salt is currently available via the Arch User Repository (AUR). There are currently stable and -git packages available.

Stable Release

Install Salt stable releases from the Arch Linux AUR as follows:
wget https://aur.archlinux.org/packages/sa/salt/salt.tar.gz tar xf salt.tar.gz cd salt/ makepkg -is
A few of Salt's dependencies are currently only found within the AUR, so it is necessary to download and run makepkg -is on these as well. As a reference, Salt currently relies on the following packages which are only available via the AUR:

•

https://aur.archlinux.org/packages/py/python2-msgpack/python2-msgpack.tar.gz

•

https://aur.archlinux.org/packages/py/python2-psutil/python2-psutil.tar.gz

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

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
See the note above about Salt's dependencies.

Post-installation tasks

Configuration files
The Salt package installs two template configuration files, /etc/salt/master.template and /etc/salt/minion.template. These files need to be copied as follows:
cp /etc/salt/master.template /etc/salt/master cp /etc/salt/minion.template /etc/salt/minion
Note: only the configuration files for the services to be run need be copied.
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 Installation

Currently the latest packages for Debian are published in Martin F. Krafft's personal debian.org repository.

Confiure Apt

Setup apt to install Salt from the repository and use Debian's stable (squeeze) backports for dependencies: for i in salt-{common,master,minion,syndic,doc} sysvinit-utils; do echo "Package: $i" echo "Pin: release a=squeeze-backports" echo "Pin-Priority: 600" echo done > /etc/apt/preferences.d/local-salt-backport.pref

Add repository

Add the repository to the list of sources: cat <<_eof > /etc/apt/sources.list.d/local-madduck-backports.list deb http://debian.madduck.net/repo squeeze-backports main deb-src http://debian.madduck.net/repo squeeze-backports main _eof Import the repository key. wget -q -O- "http://debian.madduck.net/repo/gpg/archive.key" | apt-key add -

Note
You can optionally verify the key integrity with sha512sum using the public key signature shown here. E.g:

echo "8b1983fc2d2c55c83e2bbc15d93c3fc090c8e0e92c04ece555a6b6d8ff26de8b4fc2ccbe1bbd16a6357ff86b8b69fd261e90d61350e07a518d50fc9f5f0a1eb3 archive.key" | sha512sum -c

Update the package database: apt-get update

Install packages

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

Post-installation tasks

Now go to the Configuring Salt page.

Packages from Source

To build your own salt Debian packages on squeeze use: cat <<EOF | sudo tee /etc/apt/sources.list.d/backports.list deb http://backports.debian.org/debian-backports squeeze-backports main EOF apt-get update apt-get install build-essential fakeroot apt-get install python-argparse python-zmq apt-get -t squeeze-backports install debhelper python-sphinx After installing the necessary dependencies build the packages with: git clone https://github.com/saltstack/salt.git cd salt fakeroot debian/rules binary You will need to install the salt-common package along with the salt-minion or salt-master packages. For example: dpkg -i salt-common_<version>.deb salt-minion<version>.deb apt-get -f install The last command pulls in the required dependencies for your salt packages. For more information how to use debian-backports see http://backports-master.debian.org/Instructions/

Fedora

Beginning with version 0.9.4, Salt has been available in the primary Fedora repositories and EPEL. It is installable using yum. Fedora will have more up to date versions of Salt than other members of the Red Hat family, which makes it a great place to help improve Salt!

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

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

Salt was added to the FreeBSD ports tree Dec 26th, 2011 by Christer Edwards <christer.edwards@gmail.com>. It has been tested on FreeBSD 7.4, 8.2, 9.0 and 9.1 releases.
Salt is dependent on the following additional ports. These will be installed as dependencies of the sysutils/py-salt port.
/devel/py-yaml /devel/py-pyzmq /devel/py-Jinja2 /devel/py-msgpack /security/py-pycrypto /security/py-m2crypto

Installation

To install Salt from the FreeBSD ports tree, use the command: make -C /usr/ports/sysutils/py-salt install clean

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 or /etc/rc.conf.local and add:
+ 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 or /etc/rc.conf.local and add:
+ salt_minion_enable="YES" + salt_minion_paths="/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin"
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.

OS X

Dependency Installation

ZeroMQ and swig need to be installed first. Using homebrew: brew install swig brew install zmq Using macports, zmq and swig may need to be installed this way: sudo port install pyzmq sudo port install py27-m2crypto sudo port install py27-crypto sudo port install py27-msgpack sudo port install python-swig For installs using the OSX system python, pip install needs to use 'sudo': sudo pip install salt For installs using python installed via homebrew, sudo should be unnecessary: pip install salt

Salt-Master Customizations

To run salt-master on OSX, the root user maxfiles limit must be increased: sudo launchctl limit maxfiles 10000 And add this configuration option to the /etc/salt/master file: max_open_files: 10000 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

Beginning with version 0.9.4, Salt has been available in EPEL. It is installable using yum. Salt should work properly with all mainstream derivatives of RHEL, including CentOS, Scientific Linux, Oracle Linux and Amazon Linux. Report any bugs or issues to the salt github project.

Installation

Salt and all dependencies have been accepted into the yum reposities for EPEL5 and EPEL6. The latest salt version can be found in epel-testing, while an older but more tested version can be found in regular epel.
Example showing how to install salt from epel-testing:
yum --enablerepo=epel-testing install salt-minion
On RHEL6, the proper jinja package 'python-jinja2' was moved from EPEL to the "RHEL Server Optional Channel". Verify this repository is enabled before installing salt on RHEL6.
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. On the salt-master, run this: yum install salt-master On each salt-minion, run this: yum install salt-minion

Post-installation tasks

Master
To have the Master start automatically at boot time:
chkconfig salt-master on
To start the Master:
service salt-master start
Minion
To have the Minion start automatically at boot time:
chkconfig salt-minion on
To start the Minion:
service salt-minion start
Now go to the Configuring Salt page.

Solaris

Salt was added to the OpenCSW package repository in September of 2012 by Romeo Theriault <romeot@hawaii.edu> at version 0.10.2 of Salt. It has mainly been tested on Solaris 10 (sparc), though it is built for and has been tested minimally on Solaris 10 (x86), Solaris 9 (sparc/x86) and 11 (sparc/x86). (Please let me know if you're using it on these platforms!) Most of the testing has also just focused on the minion, though it has verified that the master starts up successfully on Solaris 10. Comments and patches for better support on these platforms is very welcome. As of version 0.10.4, solaris is well supported under salt, with all of the following working well:
1. remote execution 2. grain detection 3. service control with SMF 4. 'pkg' states with 'pkgadd' and 'pkgutil' modules 5. cron modules/states 6. user and group modules/states 7. shadow password management modules/states
Salt is dependent on the following additional packages. These will automatically be installed as dependencies of the py_salt package.:
py_yaml py_pyzmq py_jinja2 py_msgpack_python py_m2crypto py_crypto python

Installation

To install Salt from the OpenCSW package repository you first need to install pkgutil assuming you don't already have it installed:
On Solaris 10:
pkgadd -d http://get.opencsw.org/now
On Solaris 9:
wget http://mirror.opencsw.org/opencsw/pkgutil.pkg pkgadd -d pkgutil.pkg all
Once pkgutil is installed you'll need to edit it's config file /etc/opt/csw/pkgutil.conf to point it at the unstable catalog:
- #mirror=http://mirror.opencsw.org/opencsw/testing + mirror=http://mirror.opencsw.org/opencsw/unstable
Ok, time to install salt.
# Update the catalog root> /opt/csw/bin/pkgutil -U # Install salt root> /opt/csw/bin/pkgutil -i -y py_salt

Minion Configuration

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

Troubleshooting

Logs are in /var/log/salt

Ubuntu Installation

Add repository

The latest packages for Ubuntu are published in the saltstack PPA. If you have the add-apt-repository utility, you can add the repository and import the key in one step:
sudo add-apt-repository ppa:saltstack/salt
Alternately, manually add the repository and import the PPA key with these commands:
echo deb http://ppa.launchpad.net/saltstack/salt/ubuntu `lsb_release -sc` main | sudo tee /etc/apt/sources.list.d/saltstack.list wget -q -O- "http://keyserver.ubuntu.com:11371/pks/lookup?op=get&search=0x4759FA960E27C0A6" | sudo apt-key add -
After adding the repository, update the package management database:
sudo apt-get update

Install packages

Install the Salt master, minion, or syndic from the repository with the apt-get command. These examples each install one daemon, but more than one package name may be given at a time: sudo apt-get install salt-master sudo apt-get install salt-minion sudo 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. There are no plans for the foreseeable future to develop a Salt Master on Windows. For now you must run your Salt Master on a supported operating system to control your Salt Minions on Windows. 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.

Windows Installer

A Salt Minion Windows installer can be found here:
Download here

•

http://saltstack.org/static/downloads/Salt-Minion-0.12.1-Setup-amd64.exe

•

http://saltstack.org/static/downloads/Salt-Minion-0.12.1-Setup-win32.exe
The 64bit installer has been tested on Windows 7 64bit and Windows Server 2008R2 64bit. The 32bit installer has been tested on Windows 2003 Server 32bit. Please file a bug report on our github repo if issues for other platforms are found. The installer asks for 2 bits of information; the master hostname and the minion name. The installer will update the minion config with these options and then start the minion. The salt-minion service will appear in the Windows Service Manager and can be started and stopped there or with the command line program sc like any other Windows service. If the minion won't start, try installing the Microsoft Visual C++ 2008 x64 redistributable. Make sure that the minion config file has the line ipc_mode: tcp

Silent Installer option

The installer can be run silently by providing the /S option at the command line. The options /master and /minion-name allow for configuring the master hostname and minion name, respectively. Here's an example of using the silent installer: Salt-Minion-0.11.1-Setup-amd64.exe /S /master=yoursaltmaster /minion-name=yourminionname

Installer Source

The Salt Windows installer is built with the open-source NSIS compiler. The source for the installer is found in the pkg directory of the Salt repo here: https://github.com/saltstack/salt/blob/develop/pkg/windows/installer/Salt-Minion-Setup.nsi. To create the installer run python setup.py bdist_esky, extract the frozen archive from dist/ into pkg/windows/buildenv/ and run NSIS.
The NSIS installer can be found here: http://nsis.sourceforge.net/Main_Page

Installation from source

To install Salt from source one must install each dependency separately and configure Salt to run on your Windows host. Rather than send you on a wild goose chase across the Internet, we've collected some of the more difficult to find installers in our github repo for you.

Install on Windows XP 32bit

1. Install msysgit 1. Clone the Salt git repository from github
git clone git://github.com/saltstack/salt.git
2.
Install Microsoft Visual Studio 2008 Express. You must use Visual Studio 2008 Express, not Visual Studio 2010 Express.
3.
Install Python 2.7.x
4.
Add c:\Python27 to your system path
5.
Install the Microsoft Visual C++ 2008 SP1 Redistributable, vcredist_x86.
6.
Install Win32OpenSSL-1_0_0e.exe
1. Choose first option to install in Windows system directory 7. Install pyzmq-2.1.11.win32-py2.7.msi 8. Install pycrypto-2.3.win32-py2.7.msi 9. Install PyYAML-3.10.win32-py2.7.msi 10. Install Cython-0.15.1.win32-py2.79.exe 11. Download and run distribute_setup.py
python distribute_setup.py
12. Download and run pip
python get-pip.py
13. Add c:\python27\scripts to your path 14. Close terminal window and open a new terminal window (cmd) 15. Install jinja2
pip install jinja2
16. Install Messagepack
pip install msgpack-python
17. Install Salt
cd ./salt python setup.py install
18. Edit c:\etc\salt\minon
master: ipaddress or hostname of your salt-master master_port: 4506 ipc_mode: tcp root_dir: c:\ pki_dir: /etc/salt/pki cachedir: /var/cache/salt renderer: yaml_jinja open_mode: False multiprocessing: False
19. Start the salt-minion
cd c:\python27\scripts python salt-minion
20. 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)
21. 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}

Single command bootstrap script

On a 64 bit Windows host the following script makes an unattended install of salt, including all dependencies: "PowerShell (New-Object System.Net.WebClient).DownloadFile('http://csa-net.dk/salt/bootstrap64.bat','C:\bootstrap.bat');(New-Object -com Shell.Application).ShellExecute('C:\bootstrap.bat');" (All in one line.) You can execute the above command remotely from a Linux host using winexe: winexe -U "administrator" //fqdn "PowerShell (New-Object ......);" For more info check http://csa-net.dk/salt

Dependencies

Salt should run on any Unix-like platform so long as the dependencies are met.
• Python 2.6 >= 2.6 <3.0 • ZeroMQ >= 2.1.9 • pyzmq >= 2.1.9 - ZeroMQ Python bindings • PyCrypto - The Python cryptography toolkit • msgpack-python - High-performance message interchange format • YAML - Python YAML bindings • Jinja2 - parsing Salt States (configurable in the master settings)

Optional Dependencies

• mako - an optional parser for Salt States (configurable in the master settings) • gcc - dynamic Cython module compiling

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.

master
The Salt master is the central server that all minions connect to. Commands are run on the minions through the master, and minions send data back to the master (unless otherwise redirected with a returner). It is started with the salt-master program.
minion
Salt minions are the potentially hundreds or thousands of servers that may be queried and controlled from the master.
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.

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

Run as an unprivileged (non-root) user?

To run Salt as another user, specify --user in the command line or assign user in the configuration file.

There is also a full troubleshooting guide available.

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.
See also: salt-key manpage

Sending Commands

Communication between the Master and a Minion may be verified by running the test.ping remote command.
[root@master ~]# salt 'alpha' test.ping {'alpha': True}
Communication between the Master and all Minions may be tested in a similar way.
[root@master ~]# salt '*' test.ping {'alpha': True} {'bravo': True} {'charlie': True} {'delta': True}
Each of the Minions should send a "True" response as shown above.

What's Next?

Depending on the primary way you want to manage your machines you may either want to visit the section regarding Salt States, or the section on Modules.

Developing Salt

There is a great need for contributions to salt and patches are welcome! The goal here is to make contributions clear, make sure there is a trail for where the code has come from, and most importantly, to give credit where credit is due!

There are a number of ways to contribute to salt development.

Sending a Github pull request

This is the preferred method for contributions. Simply create a Github fork, commit changes to the fork, and then open up a pull request. The following is an example (from Open Comparison Contributing Docs ) of an efficient workflow for forking, cloning, branching, committing, and sending a pull request for a github repository. First, make a local clone of your github fork of the salt github repo and make edits and changes locally. Then, create a new branch on your clone by entering the following commands: git checkout -b fixed-broken-thing Switched to a new branch 'fixed-broken-thing' Choose a name for your branch that describes its purpose. Now commit your changes to this new branch with the following command: #add and commit all changes at once git commit -a -m 'description of my fixes for the broken thing' And then push your locally committed changes back up to GitHub: git push --set-upstream origin fixed-broken-thing Now go look at your fork of the salt repo on the GitHub website. The new branch will now be listed under the "Source" tab where it says "Switch Branches". Select the new branch from this list, and then click the "Pull request" button. Put in a descriptive comment, and include links to any project issues related to the pull request. The repo managers will be notified of your pull request and it will be reviewed. If a reviewer asks for changes, just make the changes locally in the same local feature branch, push them to GitHub, then add a comment to the discussion section of the pull request.
Note Travis-CI
To make reviewing pull requests easier for the maintainers, please enable Travis-CI on the fork. Salt is already configured, so simply follow the first 2 steps on the Travis-CI Getting Started Doc.

Keeping Salt Forks in Sync

Salt is advancing quickly. It is therefore critical to pull upstream changes from master into forks on a regular basis. Nothing is worse than putting in a days of hard work into a pull request only to have it rejected because it has diverged too far from master. To pull in upstream changes: # For ssh github git remote add upstream git@github.com:saltstack/salt.git git fetch upstream # For https github git remote add upstream https://github.com/saltstack/salt.git git fetch upstream To check the log to be sure that you actually want the changes, run this before merging: git log upstream/develop Then to accept the changes and merge into the current branch: git merge upstream/develop For more info, see Github Fork a Repo Guide or Open Comparison Contributing Docs

Posting patches to the mailing list

Patches will also be accepted by email. Format patches using git format-patch and send them to the Salt users mailing list. The contributor will then get credit for the patch, and the Salt community will have an archive of the patch and a place for discussion.

Installing Salt for development

Clone the repository using: git clone https://github.com/saltstack/salt

Note tags

Just cloning the repository is enough to work with Salt and make contributions. However, fetching additional tags from git is required to have Salt report the correct version for itself. To do this, first add the git repository as an upstream source:

git remote add upstream http://github.com/saltstack/salt

Fetching tags is done with the git 'fetch' utility:

git fetch --tags upstream

Create a new virtualenv:
virtualenv /path/to/your/virtualenv
On Arch Linux, where Python 3 is the default installation of Python, use the virtualenv2 command instead of virtualenv.

Note Using system Python modules in the virtualenv

To use already-installed python modules in virtualenv (instead of having pip download and compile new ones), run virtualenv --system-site-packages Using this method eliminates the requirement to install the salt dependencies again, although it does assume that the listed modules are all installed in the system PYTHONPATH at the time of virtualenv creation.

Activate the virtualenv: source /path/to/your/virtualenv/bin/activate Install Salt (and dependencies) into the virtualenv: pip install M2Crypto # Don't install on Debian/Ubuntu (see below) pip install pyzmq PyYAML pycrypto msgpack-python jinja2 psutil pip install -e ./salt # the path to the salt git clone from above

Note Installing M2Crypto

swig and libssl-dev are required to build M2Crypto. To fix the error command 'swig' failed with exit status 1 while installing M2Crypto, try installing it with the following command:

env SWIG_FEATURES="-cpperraswarn -includeall -D__`uname -m`__ -I/usr/include/openssl" pip install M2Crypto

Debian and Ubuntu systems have modified openssl libraries and mandate that a patched version of M2Crypto be installed. This means that M2Crypto needs to be installed via apt:

apt-get install python-m2crypto

This also means that pulling in the M2Crypto installed using apt requires using --system-site-packages when creating the virtualenv.

Note Important note for those developing using RedHat variants

For developers using a RedHat variant, be advised that the package provider for newer Redhat-based systems (yumpkg.py) relies on RedHat's python interface for yum. The variants that use this module to provide package support include the following:

• RHEL and CentOS releases 6 and later • Fedora Linux releases 11 and later • Amazon Linux

Developers using one of these systems should create the salt virtualenv using the --system-site-packages option to ensure that the correct modules are available.

Note Installing dependencies on OS X.

You can install needed dependencies on OS X using homebrew or macports. See OS X Installation

Running a self-contained development version

During development it is easiest to be able to run the Salt master and minion that are installed in the virtualenv you created above, and also to have all the configuration, log, and cache files contained in the virtualenv as well. Copy the master and minion config files into your virtualenv: mkdir -p /path/to/your/virtualenv/etc/salt cp ./salt/conf/master /path/to/your/virtualenv/etc/salt/master cp ./salt/conf/minion /path/to/your/virtualenv/etc/salt/minion Edit the master config file:
1.
Uncomment and change the user: root value to your own user.
2.
Uncomment and change the root_dir: / value to point to /path/to/your/virtualenv.
3.
If you are running version 0.11.1 or older, uncomment and change the pidfile: /var/run/salt-master.pid value to point to /path/to/your/virtualenv/salt-master.pid.
4.
If you are also running a non-development version of Salt you will have to change the publish_port and ret_port values as well.
Edit the minion config file:
1.
Repeat the edits you made in the master config for the user and root_dir values as well as any port changes.
2.
If you are running version 0.11.1 or older, uncomment and change the pidfile: /var/run/salt-minion.pid value to point to /path/to/your/virtualenv/salt-minion.pid.
3.
Uncomment and change the master: salt value to point at localhost.
4.
Uncomment and change the id: value to something descriptive like "saltdev". This isn't strictly necessary but it will serve as a reminder of which Salt installation you are working with.

Note

Using salt-call with a Standalone Minion

If you plan to run salt-call with this self-contained development environment in a masterless setup, you should invoke salt-call with -c /path/to/your/virtualenv/etc/salt so that salt can find the minion config file. Without the -c option, Salt finds its config files in /etc/salt.

Start the master and minion, accept the minon's key, and verify your local Salt installation is working:
cd /path/to/your/virtualenv salt-master -c ./etc/salt -d salt-minion -c ./etc/salt -d salt-key -c ./etc/salt -L salt-key -c ./etc/salt -A salt -c ./etc/salt '*' test.ping
Running the master and minion in debug mode can be helpful when developing. To do this, add -l debug to the calls to salt-master and salt-minion. If you would like to log to the console instead of to the log file, remove the -d.
Once the minion starts, you may see an error like the following:
zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" is longer than 107 characters (sizeof(sockaddr_un.sun_path)).
This means the the path to the socket the minion is using is too long. This is a system limitation, so the only workaround is to reduce the length of this path. This can be done in a couple different ways:

1.
Create your virtualenv in a path that is short enough.
2.
Edit the sock_dir minion config variable and reduce its length. Remember that this path is relative to the value you set in root_dir.

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

Note File descriptor limits

Ensure that the system open file limit is raised to at least 2047:

# check your current limit
ulimit -n

# raise the limit. persists only until reboot
# use 'limit descriptors 2047' for c-shell
ulimit -n 2047

To set file descriptors on OSX, refer to the OS X Installation instructions.

Running the tests

You will need mock to run the tests:
pip install mock
If you are on Python < 2.7 then you will also need unittest2:
pip install unittest2
Finally you use setup.py to run the tests with the following command:
./setup.py test
For greater control while running the tests, please try:
./tests/runtests.py -h

Editing and previewing the documention

You need sphinx-build command to build the docs. In Debian/Ubuntu this is provided in the python-sphinx package. You can also install this directly to your virtual environment using pip:
pip install Sphinx
Change to salt documention directory, then:
cd doc; make html
• The docs then are built in the docs/_build/html/ folder. If you make changes and want to see the results, make html again.
• The docs use reStructuredText for markup. See a live demo at http://rst.ninjs.org/.
• The help information on each module or state is culled from the python code that runs for that piece. Find them in salt/modules/ or salt/states/.
• If you are developing using Arch Linux (or any other distribution for which Python 3 is the default Python installation), then sphinx-build may be named sphinx-build2 instead. If this is the case, then you will need to run the following make command:
make SPHINXBUILD=sphinx-build2 html

Targeting

Targeting

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
There are many ways to target individual minions or groups of minions in Salt:

Matching the minion id

minion id: A unique identifier for a given minion. By default the minion id is the FQDN of that host but this can be overridden.
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 web-x, web-y, and web-z minions:
salt 'web-[x-z]' test.ping

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

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
Static bits of information that a minion collects about the system when the minion first starts.
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. It is important to remember that grains are bits of information loaded when the salt minion starts, so this information is static. This means that the information in grains is unchanging, therefore the nature of the data is static. So grains information are things like the running kernel, or the operating system. Match all CentOS minions: salt -G 'os:CentOS' test.ping Match all minions with 64-bit CPUs and return number of available cores: salt -G 'cpuarch:x86_64' grains.item num_cpus

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.

Writing Grains

Grains are easy to write. The grains interface is derived by executing all of the "public" functions found in the modules located in the grains package or the custom grains directory. The functions in the modules of the grains must return a Python dict, where the keys in the dict are the names of the grains and the values are the values.
Custom grains should be placed in a _grains directory located under the file_roots specified by the master config file. They will be distributed to the minions when state.highstate is run, or by executing the saltutil.sync_grains or saltutil.sync_all functions.
Before adding a grain to Salt, consider what the grain is and remember that grains need to be static data. If the data is something that is likely to change, consider using Pillar instead.

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 the grains can be synced and reloaded by calling the saltutil.sync_grains or saltutil.sync_all functions.

Node groups

Node group: A predefined group of minions declared in the master configuration file nodegroups setting as a compound target.
Nodegroups are declared using a compound target specification. The compount target documentation can be found here:
Compound Matchers
For example, in the master config file nodegroups setting:
nodegroups: group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com' group2: 'G@os:Debian and foo.domain.com'
Specify a nodegroup via the -N option at the command-line:
salt -N group1 test.ping
Specify a nodegroup with - match: nodegroup in a top file:
base: group1: - match: nodegroup - webserver

Compound matchers

Compound matcher

A combination of many target definitions that can be combined with boolean operators.

Compound matchers allow very granular minion targeting using any of the previously discussed matchers. The default matcher is a glob, as usual. For matching via anything other than glob, preface it with the letter denoting the match type. The currently implemented "letters" are:

Matchers can be joined using boolean and, or, and not operators.

For example, the following command matches all minions that have a hostname that begins with "webserv" and that are running Debian or it matches any minions that have a hostname that 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

Batch Size

The batch size option allows commands to be executed while maintaining that only so many hosts are executing the command at one time. This option can take a percentage or a finite number:
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.

Salt Tutorials

Bootstrapping Salt on Linux EC2 with Cloud-Init

Salt is a great tool for remote execution and configuration management, however you will still need to bootstrap the daemon when spinning up a new node. One option is to create and save a custom AMI, but this creates another resource to maintain and document.
A better method for Linux machines uses Canonical's CloudInit to run a bootstrap script during an EC2 Instance initialization. Cloud-init takes the user_data string passed into a new AWS instance and runs it in a manner similar to rc.local. The bootstrap script needs to:
1. Install Salt with dependencies 2. Point the minion to the master
Here is a sample script:
#!/bin/bash # Install saltstack add-apt-repository ppa:saltstack/salt -y apt-get update -y apt-get install salt-minion -y apt-get install salt-master -y apt-get upgrade -y # Set salt master location and start minion sed -i 's/#master: salt/master: [salt_master_fqdn]/' /etc/salt/minion salt-minion -d
First the script adds the saltstack ppa and installs the package. Then we copy over the minion config template and tell it where to find the master. You will have to replace [salt_master_fqdn] with something that resolves to your Salt master.

Used With Boto

Boto will accept a string for user data which can be used to pass our bootstrap script. If the script is saved to a file, you can read it into a string: import boto user_data = open('salt_bootstrap.sh') conn = boto.connect_ec2(<AWS_ACCESS_ID>, <AWS_SECRET_KEY>) reservation = conn.run_instances(image_id=<ami_id>, key_name=<key_name>, user_data=user_data.read())

Additional Notes

Sometime in the future the ppa will include and install an upstart file. In the meantime, you can use the bootstrap to build one. It may also be useful to set the node's role during this phase. One option would be saving the node's role to a file and then using a custom Grain to select it.

Using cron with Salt

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

Use cron to initiate a highstate

If you would like the Salt Minion to regularly check in with the master you can use the venerable cron to run the salt-call command. # PATH=/bin:/sbin:/usr/bin:/usr/sbin 00 00 * * * salt-call state.highstate The above cron entry will run a highstate every day at midnight.
Note Be aware that you may need to ensure the PATH for cron includes any scripts or commands that need to be executed.

Automatic Updates / Frozen Deployments

New in version 0.10.3.d. Salt has support for the Esky application freezing and update tool. This tool allows one to build a complete zipfile out of the salt scripts and all their dependencies - including shared objects / DLLs.

Getting Started

To build frozen applications, you'll need a suitable build environment for each of your platforms. You should probably set up a virtualenv in order to limit the scope of Q/A.
This process does work on Windows. Follow the directions at https://github.com/saltstack/salt-windows-install for details on installing Salt in Windows. Only the 32-bit Python and dependencies have been tested, but they have been tested on 64-bit Windows.
You will need to install esky and bbfreeze from Pypi in order to enable the bdist_esky command in setup.py.

Building and Freezing

Once you have your tools installed and the environment configured, you can then python setup.py bdist to get the eggs prepared. After that is done, run python setup.py bdist_esky to have Esky traverse the module tree and pack all the scripts up into a redistributable. There will be an appropriately versioned salt-VERSION.zip in dist/ if everything went smoothly.

Windows

You will need to add C:\Python27\lib\site-packages\zmq to your PATH variable. This helps bbfreeze find the zmq dll so it can pack it up.

Using the Frozen Build

Unpack the zip file in your desired install location. Scripts like salt-minion and salt-call will be in the root of the zip file. The associated libraries and bootstrapping will be in the directories at the same level. (Check the Esky documentation for more information)
To support updating your minions in the wild, put your builds on a web server that your minions can reach. salt.modules.saltutil.update() will trigger an update and (optionally) a restart of the minion service under the new version.

Gotchas

My Windows minion isn't responding

The process dispatch on Windows is slower than it is on *nix. You may need to add '-t 15' to your salt calls to give them plenty of time to return.

Windows and the Visual Studio Redist

You will need to install the Visual C++ 2008 32-bit redistributable on all Windows minions. Esky has an option to pack the library into the zipfile, but OpenSSL does not seem to acknowledge the new location. If you get a no OPENSSL_Applink error on the console when trying to start your frozen minion, you have forgotten to install the redistributable.

Mixed Linux environments and Yum

The Yum Python module doesn't appear to be available on any of the standard Python package mirrors. If you need to support RHEL/CentOS systems, you should build on that platform to support all your Linux nodes. Also remember to build your virtualenv with --system-site-packages so that the yum module is included.

Automatic (Python) module discovery

Automatic (Python) module discovery does not work with the late-loaded scheme that Salt uses for (Salt) modules. You will need to explicitly add any misbehaving modules to the freezer_includes in Salt's setup.py. Always check the zipped application to make sure that the necessary modules were included.

Opening the Firewall up for Salt

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

RHEL 6 / CENTOS 6

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

iptables

Different Linux distributions store their iptables rules in different places, which makes it difficult to standardize firewall documentation. Included are some of the more common locations, but your mileage may vary.
Fedora / RHEL / CentOS
/etc/sysconfig/iptables
Arch Linux
/etc/iptables/iptables.rules
Debian
Follow these instructions: http://wiki.debian.org/iptables
Once you've found your firewall rules, you'll need to add the two lines below to allow traffic on tcp/4505 and tcp/4506:
-A INPUT -m state --state new -m tcp -p tcp --dport 4505 -j ACCEPT -A INPUT -m state --state new -m tcp -p tcp --dport 4506 -j ACCEPT
Ubuntu
Create a file named /etc/ufw/applications.d/salt-master
[Salt Master] title=Salt master description=Salt is a remote execution and configuration management tool. ports=4505,4506/tcp

pf.conf

The BSD-family of operating systems uses packet filter (pf). The following example describes the additions to pf.conf needed to access the Salt master.
pass in on $int_if proto tcp from any to $int_if port 4505 pass in on $int_if proto tcp from any to $int_if port 4506
Once these additions have been made to the pf.conf the rules will need to be reloaded. This can be done using the pfctl command.
pfctl -vf /etc/pf.conf

Remote execution tutorial

Before continuing make sure you have a working Salt installation by following the installation and the configuration instructions.
Stuck?
There are many ways to get help from the Salt community including our mailing list and our IRC channel #salt.

Order your minions around

Now that you have a master and at least one minion communicating with each other you can perform commands on the minion via the salt command. Salt calls are comprised of three main components:
salt '<target>' <function> [arguments]
See also: salt manpage

target

The target component allows you to filter which minions should run the following function. The default filter is a glob on the minion id. For example: salt '*' test.ping salt '*.example.org' test.ping Targets can be based on minion system information using the Grains system: salt -G 'os:Ubuntu' test.ping
See also: Grains system
Targets can be filtered by regular expression: salt -E 'virtmach[0-9]' test.ping Targets can be explicitly specified in a list: salt -L 'foo,bar,baz,quo' test.ping Or Multiple target types can be combined in one command: salt -C 'G@os:Ubuntu and webser* or E@database.*' test.ping

function

A function is some functionality provided by a module. Salt ships with a large collection of available functions. List all available functions on your minions: salt '*' sys.doc Here are some examples: Show all currently available minions: salt '*' test.ping Run an arbitrary shell command: salt '*' cmd.run 'uname -a'
See also: the full list of modules

arguments

Space-delimited arguments to the function:
salt '*' cmd.exec_code python 'import sys; print sys.version'
Optional, keyword arguments are also supported:
salt '*' pip.install salt timeout=5 upgrade=True
They are always in the form of kwarg=argument.

Preseed Minion with Accepted Key

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

1. Generate the keys on the master:

root@saltmaster# salt-key --gen-keys=[key_name]

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

2. Add the public key to the accepted minion folder:

root@saltmaster# cp key_name.pub /etc/salt/pki/master/minions/[minion_id]

It is necessary that the public key file has the same name as your minion id. This is how Salt matches minions with their keys. Also note that the pki folder could be in a different location, depending on your OS or if specified in the master config file.

3. Distribute the minion keys.

There is no single method to get the keypair to your minion. If you are spooling up minions on EC2, you could pass them in using user_data or a cloud-init script. If you are handing them off to a team of developers for provisioning dev machines, you will need a secure file transfer.

Security Warning

Since the minion key is already accepted on the master, distributing the private key poses a potential security risk. A malicious party will have access to your entire state tree and other sensitive data.

4. Preseed the Minion with the keys

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

Salt Masterless Quickstart

Running a masterless salt-minion lets you use salt's configuration management for a single machine. It is also useful for testing out state trees before deploying to a production setup.
The only real difference in using a standalone minion is that instead of issuing commands with salt, we use the salt-call command, like this:
salt-call --local state.highstate

Bootstrap Salt Minion

First we need to install the salt minion. The salt-bootstrap script makes this incredibly easy for any OS with a Bourne shell. You can use it like this: wget -O - http://bootstrap.saltstack.org | sudo sh Or see the salt-bootstrap documentation for other one liners. Additionally, if you are using Vagrant to test out salt, the salty-vagrant tool will provision the VM for you.

Create State Tree

Now we build an example state tree. This is where the configuration is defined. For more in depth directions, see the tutorial.
1. Create the top.sls file
# /srv/salt/top.sls base: '*': - webserver
2. Create our webserver state tree
# /srv/salt/webserver.sls apache: # ID declaration pkg: # state declaration - installed # function declaration
The only thing left is to provision our minion using the highstate command. Salt-call also gives us an easy way to give us verbose output:
salt-call --local state.highstate -l debug
The --local flag tells the salt-minion to look for the state tree in the local file system. Normally the minion copies the state tree from the master and executes it from there.
That's it, good luck!

Standalone Minion

Since the Salt minion contains such extensive functionality it can be useful to run it standalone. A standalone minion can be used to do a number of things:
• Stand up a master server via States (Salting a Salt Master) • Use salt-call commands on a system without connectivity to a master • Masterless States, run states entirely from files local to the minion

Telling Salt Call to Run Masterless

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

Running States Masterless

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

How Do I Use Salt States?

Simplicity, Simplicity, Simplicity Many of the most powerful and useful engineering solutions are founded on simple principles. The Salt SLS system strives to do just that. K.I.S.S. The core of the Salt State system is the SLS, or the SaLt State file. The SLS is a representation of the state in which a system should be in, and is set up to contain this data simply. This is often called configuration management.

It is All Just Data

Before delving into the particulars, it will help to understand that the SLS is just a data structure under the hood. While understanding that the SLS is just a data structure is not at all critical to understand to make use Salt States, it should help bolster the understanding of where the real power is. SLS files are therefore, in reality, just dictionaries, lists, strings, and numbers. By using this approach Salt can be much more flexible. As someone writes more state files, it becomes clear exactly what is being written. The result is a system that is easy to understand, yet grows with the needs of the admin or developer. In the section titled "State Data Structures" a reference exists, explaining in depth how the data is laid out.

Default Data - YAML

By default Salt represents the SLS data in what is one of the simplest serialization formats available - YAML.
A typical SLS file will often look like this in YAML:
apache: pkg: - installed service: - running - require: - pkg: apache
This SLS data will ensure that the package named apache is installed, and that the apache service is running. The components can be explained in a simple way.
The first line is the ID for a set of data, and it is called the ID Declaration. This ID sets the name of the thing that needs to be manipulated.
The second and fourth lines are the start of the State Declarations, so they are using the pkg and service states respectively. The pkg state manages a software package to get installed via the system's native package manager, and the service state manages a system daemon. Below the pkg and service lines are the function to run. This function defines what state the named package and service should be in. Here the package is to be installed, and the service should be running.
Finally, on line 6, is the word require. This is called a Requisite Statement, and it makes sure that the Apache service is only started after the successful installation of the apache package.

Adding Configs and Users

When setting up a service like an Apache web server, many more components may need to be added. The Apache configuration file will most likely be managed, and a user and group may need to be set up.
apache: pkg: - installed service: - running - watch: - pkg: apache - file: /etc/httpd/conf/httpd.conf - user: apache user.present: - uid: 87 - gid: 87 - home: /var/www/html - shell: /bin/nologin - require: - group: apache group.present: - gid: 87 - require: - pkg: apache /etc/httpd/conf/httpd.conf: file.managed: - source: salt://apache/httpd.conf - user: root - group: root - mode: 644
This SLS data greatly extends the first example, and includes a config file, a user, a group and new requisite statement: watch.
Adding more states is easy, since the new user and group states are under the Apache ID, the user and group will be the Apache user and group. The require statements will make sure that the user will only be made after the group, and that the group will be made only after the Apache package is installed.
Next,the require statement under service was changed to watch, and is now watching 3 states instead of just one. The watch statement does the same thing as require, making sure that the other states run before running the state with a watch, but it adds an extra component. The watch statement will run the state's watcher function if any of the watched states changed anything. So if the package was updated, the config file changed, or the user uid modified, then the service state's watcher will be run. The service state's watcher just restarts the service, so in this case, a change in the config file will also trigger a restart of the respective service.

Moving Beyond a Single SLS

When setting up Salt States, more than one SLS will need to be used. The above examples were just in a single SLS file, but more than one SLS file can be combined to build out a State Tree. The above example also references a file with a strange source - salt://apache/httpd.conf. That file will need to be available as well.
The SLS files are laid out in a directory on the Salt master. Files are laid out as just files. A SLS is just a file and files to download are just files.
The Apache example would be laid out in the root of the Salt file server like this:
apache/init.sls apache/httpd.conf
So the httpd.conf is just a file in the apache directory, and is referenced directly.
But with more than a single SLS file, more components can be added to the toolkit, consider this SSH example:
ssh/init.sls:
openssh-client: pkg.installed /etc/ssh/ssh_config: file.managed: - user: root - group: root - mode: 644 - source: salt://ssh/ssh_config - require: - pkg: openssh-client
ssh/server.sls:
include: - ssh openssh-server: pkg.installed sshd: service.running: - require: - pkg: openssh-client - pkg: openssh-server - file: /etc/ssh/banner - file: /etc/ssh/sshd_config /etc/ssh/sshd_config: file.managed: - user: root - group: root - mode: 644 - source: salt://ssh/sshd_config - require: - pkg: openssh-server /etc/ssh/banner: file: - managed - user: root - group: root - mode: 644 - source: salt://ssh/banner - require: - pkg: openssh-server
Note You may notice that we use two similar ways of denoting that a file is managed by Salt. In the /etc/ssh/sshd_config state section above, we use the file.managed state declaration whereas with the /etc/ssh/banner state section, we use the file state declaration and add a managed attribute to that state declaration. Both ways produce an identical result; the first way -- using file.managed -- is merely a shortcut.
Now our State Tree looks like this:
apache/init.sls apache/httpd.conf ssh/init.sls ssh/server.sls ssh/banner ssh/ssh_config ssh/sshd_config
This example now introduces the include statement. The include statement includes another SLS file so that components found in it can be required, watched or as will soon be demonstrated - extended.
The include statement allows for states to be cross linked. When an SLS has an include statement it is literally extended to include the contents of the included SLS files.

Extending Included SLS Data

Sometimes SLS data needs to be extended. Perhaps the apache service needs to watch additional resources, or under certain circumstances a different file needs to be placed.
These examples will add more watchers to apache and change the ssh banner.
ssh/custom-server.sls:
include: - ssh.server extend: /etc/ssh/banner: file: - source: salt://ssh/custom-banner
python/mod_python.sls:
include: - apache extend: apache: service: - watch: - pkg: mod_python mod_python: pkg.installed
The custom-server.sls file uses the extend statement to overwrite where the banner is being downloaded from, and therefore changing what file is being used to configure the banner.
In the new mod_python SLS the mod_python package is added, but more importantly the apache service was extended to also watch the mod_python package.
Using extend with require or watch: The extend statement works differently for require or watch. It appends to, rather than replacing the requisite component.

Understanding the Render System

Since the SLS data is just plain old data, it does not need to be represented with YAML. Salt defaults to YAML because it is very straightforward and easy to learn and use. But the SLS files can be rendered from almost any imaginable medium, so long as a renderer module is provided.
The default rendering system is the yaml_jinja renderer. The yaml_jinja renderer will first pass the template through the Jinja2 templating system, and then through the YAML parser. The benefit here is that full programming constructs are available when creating SLS files.
Other renderers available are yaml_mako and yaml_wempy which each use the Mako or Wempy templating system respectively rather than the jinja templating system, and more notably, the pure Python or py renderer. The py renderer allows for SLS files to be written in pure Python, allowing for the utmost level of flexibility and power when preparing SLS data.

Getting to Know the Default - yaml_jinja

The default renderer - yaml_jinja, allows for the use of the jinja templating system. A guide to the Jinja templating system can be found here: http://jinja.pocoo.org/docs
When working with renderers a few very useful bits of data are passed in. In the case of templating engine based renderers, three critical components are available, salt, grains, and pillar. The salt object allows for any Salt function to be called from within the template, and grains allows for the Grains to be accessed from within the template. A few examples:
apache/init.sls:
apache: pkg.installed: {% if grains['os'] == 'RedHat'%} - name: httpd {% endif %} service.running: {% if grains['os'] == 'RedHat'%} - name: httpd {% endif %} - watch: - pkg: apache - file: /etc/httpd/conf/httpd.conf - user: apache user.present: - uid: 87 - gid: 87 - home: /var/www/html - shell: /bin/nologin - require: - group: apache group.present: - gid: 87 - require: - pkg: apache /etc/httpd/conf/httpd.conf: file.managed: - source: salt://apache/httpd.conf - user: root - group: root - mode: 644
This example is simple. If the os grain states that the operating system is Red Hat, then the name of the Apache package and service needs to be httpd.
A more aggressive way to use Jinja can be found here, in a module to set up a MooseFS distributed filesystem chunkserver:
moosefs/chunk.sls:
include: - moosefs {% for mnt in salt['cmd.run']('ls /dev/data/moose*').split() %} /mnt/moose{{"{{"}} mnt[-1] }}: mount.mounted: - device: {{"{{"}} mnt }} - fstype: xfs - mkmnt: True file.directory: - user: mfs - group: mfs - require: - user: mfs - group: mfs {% endfor %} '/etc/mfshdd.cfg': file.managed: - source: salt://moosefs/mfshdd.cfg - user: root - group: root - mode: 644 - template: jinja - require: - pkg: mfs-chunkserver '/etc/mfschunkserver.cfg': file.managed: - source: salt://moosefs/mfschunkserver.cfg - user: root - group: root - mode: 644 - template: jinja - require: - pkg: mfs-chunkserver mfs-chunkserver: pkg: - installed mfschunkserver: service: - running - require: {% for mnt in salt['cmd.run']('ls /dev/data/moose*') %} - mount: /mnt/moose{{"{{"}} mnt[-1] }} - file: /mnt/moose{{"{{"}} mnt[-1] }} {% endfor %} - file: /etc/mfschunkserver.cfg - file: /etc/mfshdd.cfg - file: /var/lib/mfs
This example shows much more of the available power provided by Jinja. Multiple for loops are used to dynamically detect available hard drives and set them up to be mounted, and the salt object is used multiple times to call shell commands to gather data.

Introducing the Python Renderer

Sometimes the chosen default renderer might not have enough logical power to accomplish the needed task. When this happens, the Python renderer can be used. Normally a YAML renderer should be used for the majority of SLS files, but a SLS file set to use another renderer can be easily added to the tree.
This example shows a very basic Python SLS file:
python/django.sls:
#!py def run(): ''' Install the django package ''' return {'include': ['python'], 'django': {'pkg': ['installed']}}
This is a very simple example, the first line has a SLS shebang line that tells Salt to not use the default renderer, but to use the py renderer. Then the run function is defined, the return value from the run function must be a Salt friendly data structure, or better known as a Salt HighState data structure.
This Python example would look like this if it were written in YAML:
include: - python django: pkg.installed
This clearly illustrates, that not only is using the YAML renderer a wise decision as the default, but that unbridled power can be obtained where needed by using a pure Python SLS.

Running and debugging salt states.

Once the rules in an SLS are ready, they need to be tested to ensure they work properly. To invoke the rules, simply execute salt '*' state.highstate on the command line. If you get back just the hostnames with a : after, but no return, chances are there is a problem with the one or more of the sls files. Use the salt-call command: salt-call state.highstate -l debug and examine the output for errors. This should help troubleshoot the issue. The minions can also be started in the foreground in debug mode. Start the minion in debug mode with: salt-minion -l debug.
Now onto the States tutorial, part 1.

States tutorial, part 1

The purpose of this tutorial is to demonstrate how quickly you can configure a system to be managed by Salt States. For detailed information about the state system please refer to the full states reference.
This tutorial will walk you through using Salt to configure a minion to run the Apache HTTP server and to ensure the server is running.
Before continuing make sure you have a working Salt installation by following the installation and the configuration instructions.
Stuck?
There are many ways to get help from the Salt community including our mailing list and our IRC channel #salt.

Setting up the Salt State Tree

States are stored in text files on the master and transfered to the minions on demand via the master's File Server. The collection of state files make up the State Tree.
To start using a central state system in Salt you must first set up the Salt File Server. Edit your master config file (file_roots) and uncomment the following lines:
file_roots: base: - /srv/salt
Note
If you are deploying on FreeBSD via ports, the file_roots path defaults to /usr/local/etc/salt/states.
Restart the Salt master in order to pick up this change: % pkill salt-master % salt-master -d

Preparing the Top File

On the master in the directory you uncommented in the previous step (/srv/salt by default), create a new file called top.sls and add the following:
base: '*': - webserver
The top file is separated into environments (discussed later). The default environment is base. Under the base environment a collection of minion matches is defined; for now simply specify all hosts (*).

Targeting minions

The expressions can use any of the targeting mechanisms used by Salt - minions can be matched by glob, pcre regular expression, or by grains. For example:

base:
  'os:Fedora':
    - match: grain
    - webserver

Create an sls module

In the same directory as your top file, create an empty file, called an SLS module, named webserver.sls. Type the following and save the file:
apache: # ID declaration pkg: # state declaration - installed # function declaration
The first line, called the ID declaration, is an arbitrary identifier. In this case it defines the name of the package to be installed. NOTE: the package name for the Apache httpd web server may differ on your OS or distro - for example, on Fedora it is httpd but on Debian/Ubuntu it is apache2.
The second line, called the state declaration, defines which of the Salt States we are using. In this example, we are using the pkg state to ensure that a given package is installed.
The third line, called the function declaration, defines which function in the pkg state module to call.

Renderers

States sls files can be written in many formats. Salt requires only a simple data structure and is not concerned with how that data structure is built. Templating languages and DSLs are a dime-a-dozen and everyone has a favorite.

Building the expected data structure is the job of Salt renderers and they are dead-simple to write.

In this tutorial we will be using YAML in Jinja2 templates, which is the default format. You can change the default by changing renderer in the master configuration file.

Install the package

Next, let's run the state we created. Open a terminal on the master and run:
% salt '*' state.highstate
Our master is instructing all targeted minions to run state.highstate. When a minion executes a highstate call it will download the top file and attempt to match the expressions. When it does match an expression the modules listed for it will be downloaded, compiled, and executed.
Once completed, the minion will report back with a summary of all actions taken and all changes made.

Troubleshooting Salt

In case you don't see the expected output, the following tips can help you narrow down the problem.

Turn up logging

Salt can be quite chatty when you change the logging setting to debug:

salt-minion -l debug

Run the minion in the foreground

By not starting the minion in daemon mode (-d) you can view any output from the minion as it works:

salt-minion &

Increase the default timeout value when running salt. For example, to change the default timeout to 60 seconds:
salt -t 60
For best results, combine all three:
salt-minion -l debug & # On the minion salt '*' state.highstate -t 60 # On the master

Next steps

This tutorial focused on getting a simple Salt States configuration working. Part 2 will build on this example to cover more advanced sls syntax and will explore more of the states that ship with Salt.

States tutorial, part 2

Note
This tutorial builds on the topic covered in part 1. It is recommended that you begin there.
In the last part of the Salt States tutorial we covered the basics of installing a package. We will now modify our webserver.sls file to have requirements, and use even more Salt States.

Call multiple States

You can specify multiple state declarations under an ID declaration. For example, a quick modification to our webserver.sls to also start Apache if it is not running:
apache: pkg: - installed service: - running
Try stopping Apache before running state.highstate once again and observe the output.

Expand the SLS module

As you have seen, SLS modules are appended with the file extension .sls and are referenced by name starting at the root of the state tree. An SLS module can be also defined as a directory. Demonstrate that now by creating a directory named webserver and moving and renaming webserver.sls to webserver/init.sls. Your state directory should now resemble:
|- top.sls `- webserver/ `- init.sls
Organizing SLS modules: You can place additional .sls files in a state file directory. This affords much cleaner organization of your state tree on the filesystem. For example, if we created a webserver/django.sls file that module would be referenced as webserver.django.
In addition, States provide powerful includes and extending functionality which we will cover in Part 3.

Require other states

We now have a working installation of Apache so let's add an HTML file to customize our website. It isn't exactly useful to have a website without a webserver so we don't want Salt to install our HTML file until Apache is installed and running. Include the following at the bottom of your webserver/init.sls file:
apache: pkg: - installed service: - running /var/www/index.html: # ID declaration file: # state declaration - managed # function - source: salt://webserver/index.html # function arg - require: # requisite declaration - pkg: apache # requisite reference
line 7 is the ID declaration. In this example it is the location we want to install our custom HTML file. (Note: the default location that Apache serves may differ from the above on your OS or distro. /srv/www could also be a likely place to look.)
Line 8 the state declaration. This example uses the Salt file state.
Line 9 is the function declaration. The managed function will download a file from the master and install it in the location specified.
Line 10 is a function arg declaration which, in this example, passes the source argument to the managed function.
Line 11 is a requisite declaration.
Line 12 is a requisite reference which refers to a state and an ID. In this example, it is referring to the ID declaration from our example in part 1. This declaration tells Salt not to install the HTML file until Apache is installed.
Next, create the index.html file and save it in the webserver directory:
<html> <head><title>Salt rocks</title></head> <body> <h1>This file brought to you by Salt</h1> </body> </html>
Last, call state.highstate again and the minion will fetch and execute the highstate as well as our HTML file from the master using Salt's File Server:
salt '*' state.highstate
Verify that Apache is now serving your custom HTML.

require vs. watch

There are two requisite declarations, "require" and "watch". Not every state supports "watch". The service state does support "watch" and will restart a service based on the watch condition.

For example, if you use Salt to install an Apache virtual host configuration file and want to restart Apache whenever that file is changed you could modify our Apache example from earlier as follows:

/etc/httpd/extra/httpd-vhosts.conf:
  file:
    - managed
    - source: salt://webserver/httpd-vhosts.conf

apache:
  pkg:
    - installed
  service:
    - running
    - watch:
      - file: /etc/httpd/extra/httpd-vhosts.conf

If the pkg and service names differ on your OS or distro of choice you can specify each one separately using a name declaration which explained in Part 3.

Next steps

In part 3 we will discuss how to use includes, extends and templating to make a more complete State Tree configuration.

States tutorial, part 3

Note
This tutorial builds on the topic covered in part1 and part 2. It is recommended that you begin there.
This part of the tutorial will cover more advanced templating and configuration techniques for sls files.

Templating SLS modules

SLS modules may require programming logic or inline execution. This is accomplished with module templating. The default module templating system used is Jinja2 and may be configured by changing the renderer value in the master config.
All states are passed through a templating system when they are initially read. To make use of the templating system, simply add some templating markup. An example of an sls module with templating markup may look like this:
{% for usr in 'moe','larry','curly' %} {{"{{"}} usr }}: user.present {% endfor %}
This templated sls file once generated will look like this:
moe: user.present larry: user.present curly: user.present

Using Grains in SLS modules

Often times a state will need to behave differently on different systems. Salt grains objects are made available in the template context. The grains can be used from within sls modules:
apache: pkg.installed: {% if grains['os'] == 'RedHat' %} - name: httpd {% elif grains['os'] == 'Ubuntu' %} - name: apache2 {% endif %}

Calling Salt modules from templates

All of the Salt modules loaded by the minion are available within the templating system. This allows data to be gathered in real time on the target system. It also allows for shell commands to be run easily from within the sls modules.
The Salt module functions are also made available in the template context as salt:
{% for usr in 'moe','larry','curly' %} {{"{{"}} usr }}: group: - present user: - present - gid: {{"{{"}} salt['file.group_to_gid'](usr) }} - require: - group: {{"{{"}} usr }} {% endfor %}
Below is an example that uses the network.hwaddr function to retrieve the MAC address for eth0:
salt['network.hwaddr']('eth0')

Advanced SLS module syntax

Lastly, we will cover some incredibly useful techniques for more complex State trees.

Include declaration

A previous example showed how to spread a Salt tree across several files. Similarly, requisite references span multiple files by using an include declaration. For example:
python/python-libs.sls:
python-dateutil: pkg.installed
python/django.sls:
include: - python-libs django: pkg.installed: - require: - pkg: python-dateutil

Extend declaration

You can modify previous declarations by using an extend declaration. For example the following modifies the Apache tree to also restart Apache when the vhosts file is changed:
apache/apache.sls:
apache: pkg.installed
apache/mywebsite.sls:
include: - apache extend: apache: service: - watch: - file: /etc/httpd/extra/httpd-vhosts.conf /etc/httpd/extra/httpd-vhosts.conf: file.managed: - source: salt://apache/httpd-vhosts.conf
Using extend with require or watch: The extend statement works differently for require or watch. It appends to, rather than replacing the requisite component.

Name declaration

You can override the ID declaration by using a name declaration. For example, the previous example is a bit more maintainable if rewritten as follows:
apache/mywebsite.sls:
include: - apache extend: apache: service: - watch: - file: mywebsite mywebsite: file.managed: - name: /etc/httpd/extra/httpd-vhosts.conf - source: salt://apache/httpd-vhosts.conf

Names declaration

Even more powerful is using a names declaration to override the ID declaration for multiple states at once. This often can remove the need for looping in a template. For example, the first example in this tutorial can be rewritten without the loop: stooges: user.present: - names: - moe - larry - curly

Continue learning

The best way to continue learning about Salt States is to read through the reference documentation and to look through examples of existing state trees. You can find examples in the salt-states repository and please send a pull-request on GitHub with any state trees that you build and want to share!
If you have any questions, suggestions, or just want to chat with other people who are using Salt we have an active community.

Access Control System

New in version 0.10.4.

Salt maintains a standard system used to open granular control to non administrative users to execute Salt commands. The access control system has been applied to all systems used to configure access to non administrative control interfaces in Salt.These interfaces include, the peer system, the external auth system and the client acl system.

The access control system mandated a standard configuration syntax used in all of the three aforementioned systems. While this adds functionality to the configuration in 0.10.4, it does not negate the old configuration.

Now specific functions can be opened up to specific minions from specific users in the case of external auth and client acls, and for specific minions in the case of the peer system.

The access controls are manifest using matchers in these configurations:

client_acl:
  fred:
    - web\*:
      - pkg.list_pkgs
      - test.*
      - apache.*

In the above example, fred is able to send commands only to minions which match the specifieed glob target. This can be expanded to include other functions for other minions based on standard targets.

external_auth:
  pam:
    dave:
      - mongo\*:
        - network.*
      - log\*:
        - network.*
        - pkg.*
      - 'G@os:RedHat':
        - kmod.*
      - test.ping

The above allows for all minions to be hit by test.ping by dave, and adds a few functions for hitting other minions.

External Authentication System

Salt 0.10.4 comes with a fantastic new way to open up running Salt commands to users. This system allows for Salt itself to pass through authentication to any authentication system (The Unix PAM system was the first) to determine if a user has permission to execute a Salt command.

The external authentication system allows for specific users to be granted access to execute specific functions on specific minions. Access is configured in the master configuration file, and uses the new access control system:

external_auth:
  pam:
    thatch:
      - 'web*':
        - test.*
        - network.*

So, the above allows the user thatch to execute functions in the test and network modules on the minions that match the web* target.

The external authentication system can then be used from the command line by any user on the same system as the master with the -a option:

$ salt -a pam web\* test.ping

The system will ask the user for the credentials required by the authentication system and then publish the command.

Tokens

With external authentication alone the authentication credentials will be required with every call to Salt. This can be alleviated with Salt tokens. The tokens are short term authorizations and can be easily created by just adding a capital T option when authenticating: $ salt -T -a pam web\* test.ping Now a token will be created that has a expiration of, by default, 12 hours. This token is stored in the active user's home directory and is now sent with all subsequent communications, so the authentication does not need to be declared again until the token expires.

Pillar Of Salt

Pillar is an interface for Salt designed to offer global values that can be distributed to all minions. Pillar data is managed in a similar way to the Salt State Tree.

Pillar was added to Salt in version 0.9.8

Note Storing sensitive data
Unlike state tree, pillar data is only available for the targetted minion specified by the matcher type. This makes it 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 the Salt file server the pillar_roots option in the master config is based on environments mapping 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.
The configuration for the pillar_roots in the master config is identical in behavior and function as the file_roots configuration:
pillar_roots: base: - /srv/pillar
This example configuration declares that the base environment will be located in the /srv/pillar directory. 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
This further example shows how to use other standard top matching types (grain matching is used in this example) to deliver specific salt pillar data to minions with different 'os' grains:
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 %}
Now this data can be used from within modules, renderers, State SLS files, and more via the shared pillar dict:
apache: pkg: - installed - name: {{"{{"}} pillar['apache'] }} git: pkg: - installed - name: {{"{{"}} pillar['git'] }}

Viewing Minion Pillar

Once the pillar is set up the data can be viewed on the minion via the pillar module, the pillar module comes with two functions, pillar.data and pillar.raw. pillar.data will return a freshly reloaded pillar and pillar.raw wil return the current pillar without a refresh:
# salt '*' pillar.data

Footnotes

[1]
Note that you cannot just list key/value-information in top.sls.

Refreshing Pillar Data

When pillar data is changed on the master the minions need to refresh the data locally. This is done with the saltutil.refresh_pillar function.
salt '*' saltutil.refresh_pillar
This function triggers the minion to refresh the pillar and will always return True

Targeting with Pillar

Pillar data can be used when targeting minions. This allows for ultimate control and flexibility when targeting minions. salt -I 'somekey:specialvalue' test.ping

Master Tops System

In 0.10.4 the external_nodes system was upgraded to allow for modular subsystems to be used to generate the top file data for a highstate run on the master.

The old external_nodes option still works, but will be removed in the future in favor of the new master_tops option which uses the modular system instead. The master tops system contains a number of subsystems that are loaded via the Salt loader interfaces like modules, states, returners, runners, etc.

Using the new master_tops option is simple:

master_tops:
  ext_nodes: cobbler-external-nodes

Job Management

New in version 0.9.7.

Since Salt executes jobs running on many systems, Salt needs to be able to manage jobs running on many systems. As of Salt 0.9.7, the capability was added for more advanced job management.

The Minion proc System

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

Functions in the saltutil Module

Salt 0.9.7 introduced a few new functions to the saltutil module for managing jobs. These functions are:
1.
running Returns the data of all running jobs that are found in the proc directory.
2.
find_job Returns specific data about a certain job based on job id.
3.
signal_job Allows for a given jid to be sent a signal.
4.
term_job Sends a termination signal (SIGTERM, 15) to the process controlling the specified job.
5.
kill_job Sends a kill signal (SIGKILL, 9) to the process controlling the specified job.
These functions make up the core of the back end used to manage jobs at the minion level.

The jobs Runner

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

active

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

lookup_jid

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

list_jobs

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

Salt Scheduling

In Salt versions greater than 0.12.0, the scheduling system allows incremental executions on minions or the master. The schedule system exposes the execution of any execution function on minions or any runner on the master.

To set up the scheduler on the master add the schedule option to the master config file.

To set up the scheduler on the minion add the schedule option to the minion config file or to the minion's pillar.

The schedule option defines jobs which execute at certain intervals. To set up a highstate to run on a minion every 60 minutes set this in the minion config or pillar:

schedule:
  highstate:
    function: state.highstate
    minutes: 60

Time intervals can be specified as seconds, minutes, hours, or days. Runner executions can also be specified on the master within the master configuration file:

schedule:
  overstate:
    function: state.over
    seconds: 35
    minutes: 30
    hours: 3

The above configuration will execute the state.over runner every 3 hours, 30 minutes and 35 seconds, or every 12,635 seconds.

The scheduler is also useful for tasks like gathering monitoring data about a minion, this schedule option will gather status data and send it to a mysql returner database:

schedule:
  uptime:
    function: status.uptime
    seconds: 60
    returner: mysql
  meminfo:
    function: status.meminfo
    minutes: 5
    returner: mysql

Since specifying the returner repeatedly can be tiresome, the schedule_returner option is available to specify one or a list of global returners to be used by the minions when scheduling.

Running The Salt Master As Unprivileged User

While the default setup runs the Salt Master as the root user, it is generally wise to run servers as an unprivileged user. In Salt 0.9.10 the management of the running user was greatly improved, the only change needed is to alter the option user in the master configuration file and all salt system components will be updated to function under the new user when the master is started.

If running a version older that 0.9.10 then a number of files need to be owned by the user intended to run the master:

# chown -R <user> /var/cache/salt
# chown -R <user> /var/log/salt
# chown -R <user> /etc/salt/pki

Troubleshooting

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

Running in the Foreground

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

What Ports do the Master and Minion Need Open?

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

Using salt-call

The salt-call command was originally developed for aiding in the development of new Salt modules. Since then, many applications have been developed for running any Salt module locally on a minion. These range from the original intent of salt-call, development assistance, to gathering more verbose output from calls like state.highstate.
When developing the State Tree it is generally recommended to invoke state.highstate with salt-call. This displays far more information about the highstate execution than calling it remotely. For even more verbosity, increase the loglevel with the same argument as salt-minion:
salt-call -l debug state.highstate

Too many open files

The salt-master needs at least 2 sockets per host that connects to it, one for the Publisher and one for response port. Thus, large installations may, upon scaling up the number of minions accessing a given master, encounter:
12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38 Too many open files sock != -1 (tcp_listener.cpp:335)
The solution to this would be to check the number of files allowed to be opened by the user running salt-master (root by default):
[root@salt-master ~]# ulimit -n 1024
And modify that value to be at least equal to the number of minions x 2. This setting can be changed in limits.conf as the nofile value(s), and activated upon new a login of the specified user.
So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum.

Salt Master Stops Responding

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

Salt and SELinux

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

Red Hat Enterprise Linux 5

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

Common YAML Gotchas

An extensive list of YAML idiosyncrasies has been compiled.

Live Python Debug Output

If the minion or master seems to be unresponsive, a SIGUSR1 can be passed to the processes to display where in the code they are running. If encountering a situation like this, this debug information can be invaluable. First make sure the master of minion are running in the foreground: # salt-master -l debug # salt-minion -l debug The pass the signal to the master or minion when it seems to be unresponsive: killall -SIGUSR1 salt-master killall -SIGUSR1 salt-minion When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon this information can be invaluable.

Yaml Idiosyncrasies

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

Spaces vs Tabs

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

Indentation

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

Nested Dicts (key=value)

When dicts: are more deeply nested, they no longer follow the same indentation logic. This is rarely something that comes up in Salt, since deeply nested options like these are discouraged when making State modules, but some do exist. A good example is the context and default options in the file.managed state:
/etc/http/conf/http.conf: file: - managed - source: salt://apache/http.conf - user: root - group: root - mode: 644 - template: jinja - context: custom_var: "override" - defaults: custom_var: "default value" other_var: 123
Notice that the spacing used is 2 spaces, and that when defining the context and defaults options there is a 4 space indent. If only a 2 space indent is used then the information will not be loaded correctly. If using double spacing is not desirable, then a deeply nested dict can be declared with curly braces:
/etc/http/conf/http.conf: file: - managed - source: salt://apache/http.conf - user: root - group: root - mode: 644 - template: jinja - context: { custom_var: "override" } - defaults: { custom_var: "default value", other_var: 123 }

Integers are Parsed as Integers

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

YAML does not like Double Short Decs

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

YAML support only plain ASCII

According to YAML specification, only ASCII characters can be used. Within double-quotes, special characters may be represented with C-style escape sequences starting with a backslash ( \ ). Examples: - micro: "\u00b5" - copyright: "\u00A9" - A: "\x41" - alpha: "\u0251" - Alef: "\u05d0" List of useable Unicode characters will help you to identify correct numbers. Python can also be used to discover the Unicode number for a character: repr(u"Text with wrong characters i need to figure out") This shell command can find wrong characters in your SLS files: find . -name '*.sls' -exec grep --color='auto' -P -n '[^\x00-\x7F]' \{} \;

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. https://groups.google.com/forum/#!forum/salt-users

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.

Salt development

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

The Red45 Blog

News and thoughts on Salt and related projects is often posted on Thomas' blog The Red45: http://red45.wordpress.com/

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

Developing Salt

There is a great need for contributions to salt and patches are welcome! The goal here is to make contributions clear, make sure there is a trail for where the code has come from, and most importantly, to give credit where credit is due! There are a number of ways to contribute to salt development.

Sending a Github pull request

This is the preferred method for contributions. Simply create a Github fork, commit changes to the fork, and then open up a pull request. The following is an example (from Open Comparison Contributing Docs ) of an efficient workflow for forking, cloning, branching, committing, and sending a pull request for a github repository. First, make a local clone of your github fork of the salt github repo and make edits and changes locally. Then, create a new branch on your clone by entering the following commands: git checkout -b fixed-broken-thing Switched to a new branch 'fixed-broken-thing' Choose a name for your branch that describes its purpose. Now commit your changes to this new branch with the following command: #add and commit all changes at once git commit -a -m 'description of my fixes for the broken thing' And then push your locally committed changes back up to GitHub: git push --set-upstream origin fixed-broken-thing Now go look at your fork of the salt repo on the GitHub website. The new branch will now be listed under the "Source" tab where it says "Switch Branches". Select the new branch from this list, and then click the "Pull request" button. Put in a descriptive comment, and include links to any project issues related to the pull request. The repo managers will be notified of your pull request and it will be reviewed. If a reviewer asks for changes, just make the changes locally in the same local feature branch, push them to GitHub, then add a comment to the discussion section of the pull request.
Note Travis-CI
To make reviewing pull requests easier for the maintainers, please enable Travis-CI on the fork. Salt is already configured, so simply follow the first 2 steps on the Travis-CI Getting Started Doc.

Keeping Salt Forks in Sync

Salt is advancing quickly. It is therefore critical to pull upstream changes from master into forks on a regular basis. Nothing is worse than putting in a days of hard work into a pull request only to have it rejected because it has diverged too far from master. To pull in upstream changes: # For ssh github git remote add upstream git@github.com:saltstack/salt.git git fetch upstream # For https github git remote add upstream https://github.com/saltstack/salt.git git fetch upstream To check the log to be sure that you actually want the changes, run this before merging: git log upstream/develop Then to accept the changes and merge into the current branch: git merge upstream/develop For more info, see Github Fork a Repo Guide or Open Comparison Contributing Docs

Posting patches to the mailing list

Patches will also be accepted by email. Format patches using git format-patch and send them to the Salt users mailing list. The contributor will then get credit for the patch, and the Salt community will have an archive of the patch and a place for discussion.

Installing Salt for development

Clone the repository using: git clone https://github.com/saltstack/salt

Note tags

git remote add upstream http://github.com/saltstack/salt

Fetching tags is done with the git 'fetch' utility:

git fetch --tags upstream

Create a new virtualenv:
virtualenv /path/to/your/virtualenv
On Arch Linux, where Python 3 is the default installation of Python, use the virtualenv2 command instead of virtualenv.

Note Using system Python modules in the virtualenv

Note Installing M2Crypto

swig and libssl-dev are required to build M2Crypto. To fix the error command 'swig' failed with exit status 1 while installing M2Crypto, try installing it with the following command:

env SWIG_FEATURES="-cpperraswarn -includeall -D__`uname -m`__ -I/usr/include/openssl" pip install M2Crypto

Debian and Ubuntu systems have modified openssl libraries and mandate that a patched version of M2Crypto be installed. This means that M2Crypto needs to be installed via apt:

apt-get install python-m2crypto

This also means that pulling in the M2Crypto installed using apt requires using --system-site-packages when creating the virtualenv.

Note Important note for those developing using RedHat variants

• RHEL and CentOS releases 6 and later • Fedora Linux releases 11 and later • Amazon Linux

Developers using one of these systems should create the salt virtualenv using the --system-site-packages option to ensure that the correct modules are available.

Note Installing dependencies on OS X.

You can install needed dependencies on OS X using homebrew or macports. See OS X Installation

Running a self-contained development version

During development it is easiest to be able to run the Salt master and minion that are installed in the virtualenv you created above, and also to have all the configuration, log, and cache files contained in the virtualenv as well. Copy the master and minion config files into your virtualenv: mkdir -p /path/to/your/virtualenv/etc/salt cp ./salt/conf/master /path/to/your/virtualenv/etc/salt/master cp ./salt/conf/minion /path/to/your/virtualenv/etc/salt/minion Edit the master config file:
1.
Uncomment and change the user: root value to your own user.
2.
Uncomment and change the root_dir: / value to point to /path/to/your/virtualenv.
3.
If you are running version 0.11.1 or older, uncomment and change the pidfile: /var/run/salt-master.pid value to point to /path/to/your/virtualenv/salt-master.pid.
4.
If you are also running a non-development version of Salt you will have to change the publish_port and ret_port values as well.
Edit the minion config file:
1.
Repeat the edits you made in the master config for the user and root_dir values as well as any port changes.
2.
If you are running version 0.11.1 or older, uncomment and change the pidfile: /var/run/salt-minion.pid value to point to /path/to/your/virtualenv/salt-minion.pid.
3.
Uncomment and change the master: salt value to point at localhost.
4.
Uncomment and change the id: value to something descriptive like "saltdev". This isn't strictly necessary but it will serve as a reminder of which Salt installation you are working with.

Note

Using salt-call with a Standalone Minion

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

Note File descriptor limits

Ensure that the system open file limit is raised to at least 2047:

# check your current limit
ulimit -n

# raise the limit. persists only until reboot
# use 'limit descriptors 2047' for c-shell
ulimit -n 2047

To set file descriptors on OSX, refer to the OS X Installation instructions.

Running the tests

You will need mock to run the tests:
pip install mock
If you are on Python < 2.7 then you will also need unittest2:
pip install unittest2
Finally you use setup.py to run the tests with the following command:
./setup.py test
For greater control while running the tests, please try:
./tests/runtests.py -h

Editing and previewing the documention

You need sphinx-build command to build the docs. In Debian/Ubuntu this is provided in the python-sphinx package. You can also install this directly to your virtual environment using pip:
pip install Sphinx
Change to salt documention directory, then:
cd doc; make html
• The docs then are built in the docs/_build/html/ folder. If you make changes and want to see the results, make html again.
• The docs use reStructuredText for markup. See a live demo at http://rst.ninjs.org/.
• The help information on each module or state is culled from the python code that runs for that piece. Find them in salt/modules/ or salt/states/.
• If you are developing using Arch Linux (or any other distribution for which Python 3 is the default Python installation), then sphinx-build may be named sphinx-build2 instead. If this is the case, then you will need to run the following make command:
make SPHINXBUILD=sphinx-build2 html

Salt Based Projects

A number of unofficial open source projects, based on Salt, or written to enhance Salt have been created.

Salt Sandbox

Created by Aaron Bull Schaefer, aka "elasticdog". https://github.com/elasticdog/salt-sandbox Salt Sandbox is a multi-VM Vagrant-based Salt development environment used for creating and testing new Salt state modules outside of your production environment. It's also a great way to learn firsthand about Salt and its remote execution capabilities. Salt Sandbox will set up three separate virtual machines:
• salt.example.com - the Salt master server • minion1.example.com - the first Salt minion machine • minion2.example.com - the second Salt minion machine
These VMs can be used in conjunction to segregate and test your modules based on node groups, top file environments, grain values, etc. You can even test modules on different Linux distributions or release versions to better match your production infrastructure.

Salt Event System

Salt 0.9.10 introduced the Salt Event System. This system is used to fire off events enabling third party applications or external processes to react to behavior within Salt.

The event system is comprised of a few components, the event sockets which publish events, and the event library which can listen to events and send events into the salt system.

Listening for Events

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.utils.event event = salt.utils.event.MasterEvent('/var/run/salt/master') data = event.get_event()
Events will also use a "tag". A "tag" allows for events to be filtered. By default all events will be returned, but if only authentication events are desired, then pass the tag "auth". Also, the get_event method has a default poll time assigned of 5 seconds, to change this time set the "wait" option. This example will only listen for auth events and will wait for 10 seconds instead of the default 5.
import salt.utils.event event = salt.utils.event.MasterEvent('/var/run/salt/master') data = event.get_event(wait=10, tag='auth')
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:
import salt.utils.event event = salt.utils.event.MasterEvent('/var/run/salt/master') for data in event.iter_events(tag='auth'): print(data)

Writing Tests

Salt uses a test platform to verify functionality of components in a simple way. Two testing systems exist to enable testing salt functions in somewhat real environments. The two subsystems available are integration tests and unit tests.

Salt uses the python standard library unittest2 system for testing.

Integration Tests

The integration tests start up a number of salt daemons to test functionality in a live environment. These daemons include 2 salt masters, 1 syndic and 2 minions. This allows for the syndic interface to be tested and master/minion communication to be verified. All of the integration tests are executed as live salt commands sent through the started daemons.
• Writing integration tests
Integration tests are particularly good at testing modules, states and shell commands.

Unit Tests

Direct unit tests are also available, these tests are good for internal functions.

Integration Tests

The Salt integration tests come with a number of classes and methods which allow for components to be easily tested. These classes are generally inherited from and provide specific methods for hooking into the running integration test environment created by the integration tests.

It is noteworthy that since integration tests validate against a running environment that they are generally the preferred means to write tests.

The integration system is all located under tests/integration in the Salt source tree.

Integration Classes

The integration classes are located in tests/integration/__init__.py and can be extended therein. There are three classes available to extend:

ModuleCase

Used to define executions run via the master to minions and to call single modules and states. The available methods are as follows:
run_function:: Run a single salt function and condition the return down to match the behavior of the raw function call. This will run the command and only return the results from a single minion to verify.
state_result:: Return the result data from a single state return
run_state:: Run the state.single command and return the state return structure

SyndicCase

Used to execute remote commands via a syndic, only used to verify the capabilities of the Syndic. The available methods are as follows:
run_function:: Run a single salt function and condition the return down to match the behavior of the raw function call. This will run the command and only return the results from a single minion to verify.

ShellCase

Shell out to the scripts which ship with Salt. The available methods are as follows:
run_script:: Execute a salt script with the given argument string
run_salt:: Execute the salt command, pass in the argument string as it would be passed on the command line.
run_run:: Execute the salt-run command, pass in the argument string as it would be passed on the command line.
run_run_plus:: Execute Salt run and the salt run function and return the data from each in a dict
run_key:: Execute the salt-key command, pass in the argument string as it would be passed on the command line.
run_cp:: Execute salt-cp, pass in the argument string as it would be passed on the command line.
run_call:: Execute salt-call, pass in the argument string as it would be passed on the command line.

Examples

Module Example via ModuleCase Class

Import the integration module, this module is already added to the python path by the test execution. Inherit from the integration.ModuleCase class. The tests that execute against salt modules should be placed in the tests/integration/modules directory so that they will be detected by the test system.
Now the workhorse method run_function can be used to test a module:
import os import integration class TestModuleTest(integration.ModuleCase): ''' Validate the test module ''' def test_ping(self): ''' test.ping ''' self.assertTrue(self.run_function('test.ping')) def test_echo(self): ''' test.echo ''' self.assertEqual(self.run_function('test.echo', ['text']), 'text')
ModuleCase can also be used to test states, when testing states place the test module in the tests/integration/states directory. The state_result and the run_state methods are the workhorse here:
import os import shutil import integration HFILE = os.path.join(integration.TMP, 'hosts') class HostTest(integration.ModuleCase): ''' Validate the host state ''' def setUp(self): shutil.copyfile(os.path.join(integration.FILES, 'hosts'), HFILE) super(HostTest, self).setUp() def tearDown(self): if os.path.exists(HFILE): os.remove(HFILE) super(HostTest, self).tearDown() def test_present(self): ''' host.present ''' name = 'spam.bacon' ip = '10.10.10.10' ret = self.run_state('host.present', name=name, ip=ip) result = self.state_result(ret) self.assertTrue(result) with open(HFILE) as fp_: output = fp_.read() self.assertIn('{0}\t\t{1}'.format(ip, name), output)
The above example also demonstrates using the integration files and the integration state tree. The variable integration.FILES will point to the directory used to store files that can be used or added to to help enable tests that require files. The location integration.TMP can also be used to store temporary files that the test system will clean up when the execution finishes.
The integration state tree can be found at tests/integration/files/file/base. This is where the referenced host.present sls file resides.

Shell Example via ShellCase

Validating the shell commands can be done via shell tests. Here are some examples:
import sys import shutil import tempfile import integration class KeyTest(integration.ShellCase): ''' Test salt-key script ''' _call_binary_ = 'salt-key' def test_list(self): ''' test salt-key -L ''' data = self.run_key('-L') expect = [ 'Unaccepted Keys:', 'Accepted Keys:', 'minion', 'sub_minion', 'Rejected:', ''] self.assertEqual(data, expect)
This example verifies that the salt-key command executes and returns as expected by making use of the run_key method.
All shell tests should be placed in the tests/integraion/shell directory.

Reactor System

Salt version 0.11.0 introduced the reactor system. The premise behind the reactor system is that with Salt's events and the ability to execute commands a logic engine could be put in place to allow events to trigger actions, or more accurately, reactions.

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 which is comprised of a maximum of 20 characters. Event tags allow for fast top level filtering of events. In addition to the tag, an event has a data structure. This data structure is a dict containing information about the event.

Mapping Events to Reactor SLS Files

The event tag and data are both critical when working with the reactor system. In the master configuration file under the reactor option, tags are associated with lists of reactor sls formulas (globs can be used for matching): reactor: - 'auth': - /srv/reactor/authreact1.sls - /srv/reactor/authreact2.sls - 'minion_start': - /srv/reactor/start.sls When an event with a tag of auth is fired the reactor will catch the event and render the two listed files. The rendered files are standard sls files, so by default they are yaml + jinja. The jinja is packed with a few data structures similar to state and pillar sls files. The data available is found in the tag and data variables. The tag variable is just the tag in the fired event and the data variable is the event's data dict. Here is a simple reactor sls: {% if data['id'] == 'mysql1' %} highstate_run: cmd.state.highstate: - 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 (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.highstate. Similarly, a runner can be called: {% if data['data']['overstate'] == 'refresh' %} overstate_run: runner.state.over {% endif %} This example will execute the state.overstate runner and initiate an overstate execution.

Understanding the Structure of Reactor Formulas

While the reactor system uses the same data structure as the state system, this data does not translate the same way to operations. In state formulas information is mapped to the state functions, but in the reactor system information is mapped to a number of available subsystems on the master. These systems are the LocalClient and the Runners. The state declaration field takes a reference to the function to call in each interface. So to trigger a salt-run call the state declaration field will start with runner, followed by the runner function to call. This means that a call to what would be on the command line salt-run manage.up will be runner.manage.up. An example of this in a reactor formula would look like this: manage_up: runner.manage.up If the runner takes arguments then they can be specified as well: overstate_dev_env: runner.state.over: - env: dev Executing remote commands maps to the LocalClient interface which is used by the salt command. This interface more specifically maps to the cmd_async method inside of the LocalClient class. This means that the arguments passed are being passed to the cmd_async method, not the remote method. The field starts with cmd to use the LocalClient subsystem. The result is that to execute a remote command it looks like this: clean_tmp: cmd.cmd.run: - tgt: '*' - arg: - rm -rf /tmp/* The arg option takes a list of arguments as they would be presented on the command line, so the above declaration is the same as running this salt command: salt \* cmd.run 'rm -rf /tmp/*'

Salt Coding Style

Salt is developed with a certain coding style, while the style is dominantly PEP-08 it is not completely PEP-08. It is also noteworthy that a few development techniques are also employed which should be adhered to. In the end, the code is made to be "Salty".

Most importantly though, we will accept code that violates the coding style and KINDLY ask the contributor to fix it, or go ahead and fix the code on behalf of the contributor. Coding style is NEVER grounds to reject code contributions, and is never grounds to talk down to another member of the community (There are no grounds to treat others without respect, especially people working to improve Salt)!!

Strings

Salt follows a few rules when formatting strings:

Single Quotes

In Salt, all strings use single quotes unless there is a good reason not to. This means that docstrings use single quotes, standard strings use single quotes etc.: def foo(): ''' A function that does things ''' name = 'A name' return name

Formatting Strings

All strings which require formatting should use the .format string method: data = 'some text' more = '{0} and then some'.format(data) Make sure to use indices or identifiers in the format brackets, since empty brackets are not supported by python 2.6. Please do NOT use printf formatting.

Docstring Conventions

Docstrings should always add a newline, docutils takes care of the new line and it makes the code cleaner and more vertical: GOOD: def bar(): ''' Here lies a docstring with a newline after the quotes and is the salty way to handle it! Vertical code is the way to go! ''' return BAD: def baz(): '''This is not ok!''' return

Imports

Salt code prefers importing modules and not explicit functions. This is both a style and functional preference. The functional preference originates around the fact that the module import system used by pluggable modules will include callable objects (functions) that exist in the direct module namespace. This is not only messy, but may unintentionally expose code python libs to the Salt interface and pose a security problem. To say this more directly with an example, this is GOOD: import os def minion_path(): path = os.path.join(self.opts['cachedir'], 'minions') return path This on the other hand is DISCOURAGED: from os.path import join def minion_path(): path = join(self.opts['cachedir'], 'minions') return path The time when this is changed is for importing exceptions, generally directly importing exceptions is preferred: This is a good way to import exceptions: from salt.exceptions import CommandExecutionError

Vertical is Better

When writing Salt code, vertical code is generally preferred. This is not a hard rule but more of a guideline. As PEP-08 specifies Salt code should not exceed 79 characters on a line, but it is preferred to separate code out into more newlines in some cases for better readability:
import os os.chmod( os.path.join(self.opts['sock_dir'], 'minion_event_pub.ipc'), 448 )
Where there are more line breaks, this is also apparent when constructing a function with many arguments, something very common in state functions for instance:
def managed(name, source=None, source_hash='', user=None, group=None, mode=None, template=None, makedirs=False, context=None, replace=True, defaults=None, env=None, backup='', **kwargs):

Code Churn

Many pull requests have been submitted that only churn code in the name of PEP-08. Code churn is a leading source of bugs and is strongly discouraged. While style fixes are encouraged they should be isolated to a single file per commit, and the changes should be legitimate, if there are any questions about whether a style change is legitimate please reference this document and the official PEP-08 (- http://www.python.org/dev/peps/pep-0008/) document before changing code. Many claims that a change is PEP-08 have been invalid, please double check before committing fixes.

Salt Stack Git Policy

The Salt Stack team follows a git policy to maintain stability and consistency with the repository. The git policy has been developed to encourage contributions and make contributing to Salt as easy as possible. Code contributors to Salt Stack projects DO NOT NEED TO READ THIS DOCUMENT, because all contributions come into Salt Stack via a single gateway to make it as easy as possible for contributors to give us code.

The primary rule of git management in Salt Stack is to make life easy on contributors and developers to send in code. Simplicity is always a goal!

New Code Entry

All new Salt Stack code is posted to the develop branch, this is the single point of entry. The only exception here is when a bugfix to develop cannot be cleanly merged into a release branch and the bugfix needs to be rewritten for the release branch.

Release Branching

Salt Stack maintains two types of releases, Feature Releases and Point Releases. A feature release is managed by incrementing the first or second release point number, so 0.10.5 -> 0.11.0 signifies a feature release and 0.11.0 -> 0.11.1 signifies a point release, also a hypothetical 0.42.7 -> 1.0.0 would also signify a feature release.

Feature Release Branching

Each feature release is maintained in a dedicated git branch derived from the last applicable release commit on develop. All file changes relevant to the feature release will be completed in the develop branch prior to the creation of the feature release branch. The feature release branch will be named after the relevant numbers to the feature release, which constitute the first two numbers. This means that the release branch for the 0.11.0 series is named 0.11. A feature release branch is created with the following command: # git checkout -b 0.11 # From the develop branch # git push origin 0.11

Point Releases

Each point release is derived from its parent release branch. Constructing point releases is a critical aspect of Salt development and is managed by members of the core development team. Point releases comprise bug and security fixes which are cherry picked from develop onto the aforementioned release branch. At the time when a core developer accepts a pull request a determination needs to be made if the commits in the pull request need to be backported to the release branch. Some simple criteria are used to make this determination:
• Is this commit fixing a bug? Backport • Does this commit change or add new features in any way? Don't backport • Is this a PEP8 or code cleanup commit? Don't backport • Does this commit fix a security issue? Backport
Determining when a point release is going to be made is up to the project leader (Thomas Hatch). Generally point releases are made every 1-2 weeks or if there is a security fix they can be made sooner. The point release is only designated by tagging the commit on the release branch with release number using the existing convention (version 0.11.1 is tagged with v0.11.1). From the tag point a new source tarball is generated and published to Pypi, and a release announcement is made.

Salt Development Guidelines

Dunder Dictionaries

Salt provides several special "dunder" dictionaries as a convenience for Salt development. These include __opts__, __context__, __salt__, and others. This document will describe each dictionary and detail where they exist and what information and/or functionality they provide.

__context__

__context__ exists in state modules and execution modules.
During a state run the __context__ dictionary persists across all states that are run and then is destroyed when the state ends.
When running an execution module __context__ persists across all module executions until the modules are refreshed; such as when saltutils.sync_all or state.highstate are executed.
A great place to see how to use __context__ is in the cp.py module in salt/modules/cp.py. The fileclient authenticates with the master when it is instantiated and then is used to copy files to the minion. Rather than create a new fileclient for each file that is to be copied down, one instance of the fileclient is instantiated in the __context__ dictionary and is reused for each file. Here is an example from salt/modules/cp.py:
if not 'cp.fileclient' in __context__: __context__['cp.fileclient'] = salt.fileclient.get_file_client(__opts__)
Note Because __context__ may or may not have been destroyed, always be sure to check for the existence of the key in __context__ and generate the key before using it.

Package Providers

This page contains guidelines for writing package providers.

Package Functions

One of the most important features of Salt is package management. There is no shortage of package managers, so in the interest of providing a consistent experience in pkg states, there are certain functions that should be present in a package provider. Note that these are subject to change as new features are added or existing features are enhanced.

list_pkgs

This function should declare an empty dict, and then add packages to it by calling pkg_resource.add_pkg, like so:
__salt__['pkg_resource.add_pkg'](ret, name, version)
The last thing that should be done before returning is to execute pkg_resource.sort_pkglist. This function does not presently do anything to the return dict, but will be used in future versions of Salt.
__salt__['pkg_resource.sort_pkglist'](ret)
list_pkgs returns a dictionary of installed packages, with the keys being the package names and the values being the version installed. Example return data:
{'foo': '1.2.3-4', 'bar': '5.6.7-8'}

available_version

Accepts an arbitrary number of arguments. Each argument is a package name. The return value for a package will be an empty string if the package is not found or if the package is up-to-date. The only case in which a non-empty string is returned is if the package is available for new installation (i.e. not already installed) or if there is an upgrade available. If only one argument was passed, this function return a string, otherwise a dict of name/version pairs is returned.

version

Like available_version, accepts an arbitrary number of arguments and returns a string if a single package name was passed, or a dict of name/value pairs if more than one was passed. The only difference is that the return values are the currently-installed versions of whatever packages are passed. If the package is not installed, an empty string is returned for that package.

upgrade_available

Deprecated and destined to be removed. For now, should just do the following: return __salt__['pkg.available_version'](name) != ''

install

The following arguments are required and should default to None:
1. name (for single-package pkg states) 2. pkgs (for multiple-package pkg states) 3. sources (for binary package file installation)
The first thing that this function should do is call pkg_resource.parse_targets (see below). This function will convert the SLS input into a more easily parsed data structure. pkg_resource.parse_targets may need to be modified to support your new package provider, as it does things like parsing package metadata which cannot be done for every package management system.
pkg_params, pkg_type = __salt__['pkg_resource.parse_targets'](name, pkgs, sources)
Two values will be returned to the install function. The first of them will be a dictionary. The keys of this dictionary will be package names, though the values will differ depending on what kind of installation is being done:
• If name was provided (and pkgs was not), then there will be a single key in the dictionary, and its value will be None. Once the data has been returned, if the version keyword argument was provided, then it should replace the None value in the dictionary.
• If pkgs was provided, then name is ignored, and the dictionary will contain one entry for each package in the pkgs list. The values in the dictionary will be None if a version was not specified for the package, and the desired version if specified. See the Multiple Package Installation Options section of the pkg.installed state for more info.
• If sources was provided, then name is ignored, and the dictionary values will be the path/URI for the package.
The second return value will be a string with two possbile values: repository or file. The install function can use this value (if necessary) to build the proper command to install the targeted package(s).
Both before and after the installing the target(s), you should run list_pkgs to obtain a list of the installed packages. You should then return the output of pkg_resource.find_changes:
return __salt__['pkg_resource.find_changes'](old, new)

remove

Removes the passed package and return a list of the packages removed.

Package Repo Functions

There are some functions provided by pkg which are specific to package repositories, and not to packages themselves. When writing modules for new package managers, these functions should be made available as stated below, in order to provide compatibility with the pkgrepo state.
All repo functions should accept a basedir option, which defines which directory repository configuration should be found in. The default for this is dictated by the repo manager that is being used, and rarely needs to be changed.
basedir = '/etc/yum.repos.d' __salt__['pkg.list_repos'](basedir)

list_repos

Lists the repositories that are currently configured on this system. __salt__['pkg.list_repos']() Returns a dictionary, in the following format: {'reponame': 'config_key_1': 'config value 1', 'config_key_2': 'config value 2', 'config_key_3': ['list item 1 (when appropriate)', 'list item 2 (when appropriate)]}

get_repo

Displays all local configuration for a specific repository. __salt__['pkg.get_repo'](repo='myrepo') The information is formatted in much the same way as list_repos, but is specific to only one repo. {'config_key_1': 'config value 1', 'config_key_2': 'config value 2', 'config_key_3': ['list item 1 (when appropriate)', 'list item 2 (when appropriate)]}

del_repo

Removes the local configuration for a specific repository. Requires a repo argument, which must match the locally configured name. This function returns a string, which informs the user as to whether or not the operation was a success. __salt__['pkg.del_repo'](repo='myrepo')

mod_repo

Modify the local configuration for one or more option for a conifigured repo. This is also the way to create new repository configuration on the local system; if a repo is specified which does not yet exist, it will be created. The options specified for this function are specific to the system; please refer to the documentation for your specific repo manager for specifics. __salt__['pkg.mod_repo'](repo='myrepo', url='http://myurl.com/repo')

Low-Package Functions

In general, the standard package functions as describes above will meet your needs. These functions use the system's native repo manager (for instance, yum or the apt tools). In most cases, the repo manager is actually separate from the package manager. For instance, yum is usually a front-end for rpm, and apt is usually a front-end for dpkg. When possible, the package functions that use those package managers directly should do so through the low package functions.
It is normal and sane for pkg to make calls to lowpkgs, but lowpkg must never make calls to pkg. This is affects functions which are required by both pkg and lowpkg, but the technique in pkg is more performant than what is available to lowpkg. When this is the case, the lowpkg function that requires that technique must still use the lowpkg version.

list_pkgs

Returns a dict of packages installed, including the package name and version. Can accept a list of packages; if none are spcified, then all installed packages will be listed. installed = __salt__['lowpkg.list_pkgs']('foo', 'bar') Example output: {'foo': '1.2.3-4', 'bar': '5.6.7-8'}

verify

Many (but not all) package management systems provide a way to verify that the files installed by the package manager have or have not changed. This function accepts a list of packages; if none are specified, all packages will be included. installed = __salt__['lowpkg.verify']('httpd') Example output: {'/etc/httpd/conf/httpd.conf': {'mismatch': ['size', 'md5sum', 'mtime'], 'type': 'config'}}

file_list

Lists all of the files installed by all packages specified. If not packages are specified, then all files for all known packages are returned. installed = __salt__['lowpkg.file_list']('httpd', 'apache') This function does not return which files belong to which packages; all files are returned as one giant list (hence the file_list function name. However, This information is still returned inside of a dict, so that it can provide any errors to the user in a sane manner. {'errors': ['package apache is not installed'], 'files': ['/etc/httpd', '/etc/httpd/conf', '/etc/httpd/conf.d', '...SNIP...']}

file_dict

Lists all of the files installed by all packages specified. If not packages are specified, then all files for all known packages are returned. installed = __salt__['lowpkg.file_dict']('httpd', 'apache', 'kernel') Unlike file_list, this function will break down which files belong to which packages. It will also return errors in the same manner as file_list. {'errors': ['package apache is not installed'], 'packages': {'httpd': ['/etc/httpd', '/etc/httpd/conf', '...SNIP...'], 'kernel': ['/boot/.vmlinuz-2.6.32-279.el6.x86_64.hmac', '/boot/System.map-2.6.32-279.el6.x86_64', '...SNIP...']}}

Introduction To Extending Salt

Salt is made to be used, and made to be extended. The primary goal of Salt is to provide a foundation which can be used to solve problems. And the goal of Salt is to not assume what those problems might be.

One of the greatest benefit of developing Salt has been the vast array of ways in which people have wanted to use it, while the original intention was as a communication layer for a cloud controller Salt has been extended to facilitate so much more.

Client API

The primary interface used to extend Salt, is to simply use it. Salt executions can be called via the Salt client api, making programming master side solutions with Salt is easy.

Adding Loadable Plugins

Salt is comprised of a core platform that loads many types of easy to write plugins. The idea is to enable all of the breaking points in the Salt processes to have a point of pluggable interaction. This means that all of the main features of Salt can be extended, modified or used. The breaking points and helping interfaces span from convenience master side executions to manipulating the flow of how data is handled by Salt.

Minion Execution Modules

The minion execution modules or just modules are the core to what Salt is and does. These modules are found in:
https://github.com/saltstack/salt/blob/develop/salt/modules
These modules are what is called by the Salt command line and the salt client API. Adding modules is done by simply adding additional Python modules to the modules directory and restarting the minion.

Grains

Salt grains, or "grains of truth" are bits of static information that are generated when the minion starts. This information is useful when determining what package manager to default to, or where certain configuration files are stored on the minion. The Salt grains are the interface used for auto detection and dynamic assignment of execution modules and types to specific Salt minions. The code used to generate the Salt grains can be found here: https://github.com/saltstack/salt/blob/develop/salt/grains

States

Salt supports state enforcement, this makes Salt a high speed and very efficient solution for system configuration management. States can be easily added to Salt by dropping a new state module in: https://github.com/saltstack/salt/blob/develop/salt/states

Renderers

Salt states are controlled by simple data structures, these structures can be abstracted in a number of ways. While the default is to be in a yaml file wrapped in a jinja template, any abstraction can be used. This means that any format that can be dreamed is possible, so long as a renderer is written for it. The existing renderers can be found here: https://github.com/saltstack/salt/blob/develop/salt/renderers

Returners

The Salt commands all produce a return value, that return value is sent to the Salt master by default, but it can be sent anywhere. The returner interface makes it programmatically possible for the information to be sent to anything from an SQL or NoSQL database, to a custom application made to use Salt. The existing returners can be found here: https://github.com/saltstack/salt/blob/develop/salt/returners

Runners

Sometimes a certain application can be made to execute and run from the existing Salt command line. This is where the Salt runners come into play. The Salt Runners what is called by the Salt-run command and are meant to act as a generic interface for encapsulating master side executions. Existing Salt runners are located here: https://github.com/saltstack/salt/blob/develop/salt/runners

Modules

Salt modules are the functions called by the salt command.

See also: Full list of builtin modules
Salt ships with many modules that cover a wide variety of tasks.

Modules Are Easy to Write!

Salt modules are amazingly simple to write. Just write a regular Python module or a regular Cython module and place it in the salt/modules directory. You can also place them in a directory called _modules/ within the file_roots specified by the master config file, and they will be synced to the minions when state.highstate is run, or by executing the saltutil.sync_modules or saltutil.sync_all functions.
Since Salt modules are just Python/Cython modules, there are no restraints on what you can put inside of a Salt module. 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.

Cross Calling Modules

All of the Salt modules are available to each other, and can be "cross called". This means that, when creating a module, functions in modules that already exist can be called.
The variable __salt__ is packed into the modules after they are loaded into the Salt minion. This variable is a Python dictionary of all of the Salt functions, laid out in the same way that they are made available to the Salt command.
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 Salt cmd module's run function and pass the argument bar.

Preloaded Modules Data

When interacting with modules often it is nice to be able to read information dynamically about the minion, or load in configuration parameters for a module. Salt allows for different types of data to be loaded into the modules by the minion, as of this writing Salt loads information gathered from the Salt Grains system and from the minion configuration file.

Grains Data

The Salt minion detects information about the system when started. This allows for modules to be written dynamically with respect to the underlying hardware and operating system. This information is referred to as Salt Grains, or "grains of salt". The Grains system was introduced to replace Facter, since relying on a Ruby application from a Python application was both slow and inefficient. Grains support replaces Facter in all Salt releases after 0.8
The values detected by the Salt Grains on the minion are available in a dict named __grains__ and can be accessed from within callable objects in the Python modules.
To see the contents of the grains dict for a given system in your deployment run the grains.items() function:
salt 'hostname' grains.items
To use the __grains__ dict simply call it as a Python dict from within your code, an excellent example is available in the Grains module: salt.modules.grains.

Module Configuration

Since parameters for configuring a module may be desired, Salt allows for configuration information stored in the main minion config file to be passed to the 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 strongly recommended that the values passed in the configuration file match the module. This means that a value intended for the test module should be named test.<value>.
Configuration also requires that default configuration parameters need to be loaded as well. This can be done simply by adding the __opts__ dict to the top level of the module.
The test 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.

Printout Configuration

Since module functions can return different data, and the way the data is printed can greatly change the presentation, Salt has a printout configuration.
When writing a module the __outputter__ dict can be declared in the module. The __outputter__ dict contains a mapping of function name to Salt Outputter.
__outputter__ = { 'run': 'txt' }
This will ensure that the text outputter is used.

Virtual Modules

Sometimes a module should be presented in a generic way. A good example of this can be found in the package manager modules. The package manager changes from one operating system to another, but the Salt module that interfaces with the package manager can be presented in a generic way.
The Salt modules for package managers all contain a __virtual__ function which is called to define what systems the module should be loaded on.
The __virtual__ function is used to return either a string or False. If False is returned then the module is not loaded, if a string is returned then the module is loaded with the name of the string.
This means that the package manager modules can be presented as the pkg module regardless of what the actual module is named.
The package manager modules are the best example of using the __virtual__ function: https://github.com/saltstack/salt/blob/develop/salt/modules/pacman.py https://github.com/saltstack/salt/blob/develop/salt/modules/yumpkg.py https://github.com/saltstack/salt/blob/develop/salt/modules/apt.py

Documentation

Salt modules are self documenting, the sys.doc() function will return the documentation for all available modules:
salt '*' sys.doc
This function simple prints out the docstrings found in the modules, when writing Salt modules, please follow the formating conventions for docstrings as they appear in the other modules.

Adding Documentation to Salt Modules

Since life is much better with documentation, it is strongly suggested that all Salt modules have documentation added. Any Salt modules submitted for inclusion in the main distribution of Salt will be required to have documentation. Documenting Salt modules is easy! Just 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.

Add Module metadata

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 maintaner 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 modules is known to run on.

How Functions are Read

In Salt, Python callable objects contained within a 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 class baz: def __init__(self, quo): pass

Objects NOT Loaded into the Salt Minion

def _foobar(baz): # Preceded with an _ return baz cheese = {} # Not a callable Python object

Examples of Salt Modules

The existing Salt modules should be fairly easy to read and understand, the goal of the main distribution's Salt modules is not only to build a set of functions for Salt, but to stand as examples for building out more Salt modules.
The existing modules can be found here: https://github.com/saltstack/salt/blob/develop/salt/modules
The most simple module is the test module, it contains the simplest Salt function, test.ping:
def ping(): ''' Just used to make sure the minion is up and responding Return True CLI Example:: salt '*' test.ping ''' return True

Full List Of Builtin Execution Modules

Virtual modules

salt.modules.pkg

pkg is a virtual module that is fulfilled by one of the following modules:
• salt.modules.apt
• salt.modules.ebuild
• salt.modules.freebsdpkg
• salt.modules.pacman
• salt.modules.yumpkg
• salt.modules.yumpkg5
• salt.modules.zypper
• salt.modules.brew
• salt.modules.win_pkg

salt.modules.sys

The regular salt modules execute in a separate context from the salt minion and manipulating the actual salt modules needs to happen in a higher level context within the minion process. This is where the sys pseudo module is used. The sys pseudo module comes with a few functions that return data about the available functions on the minion or allows for the minion modules to be refreshed. These functions are as follows:

salt.modules.sys.doc([module[, module.function]])

Display the inline documentation for all available modules, or for the specified module or function.

salt.modules.sys.reload_modules()

Instruct the minion to reload all available modules in memory. This function can be called if the modules need to be re-evaluated for availability or new modules have been made available to the minion.

salt.modules.sys.list_modules()

List all available (loaded) modules.

salt.modules.sys.list_functions()

List all known functions that are in available (loaded) modules.

salt.modules.aliases

Manage the information in the aliases file

salt.modules.aliases.get_target(alias)

Return the target associated with an alias

CLI Example:

salt '*' aliases.get_target <alias>

salt.modules.aliases.has_target(alias, target)

Return true if the alias/target is set

CLI Example:

salt '*' aliases.has_target <alias> <target>

salt.modules.aliases.list_aliases()

Return the aliases found in the aliases file in this format:

{'<alias>': '<target>'}

CLI Example:

salt '*' aliases.list_aliases

salt.modules.aliases.rm_alias(alias)

Remove an entry from the aliases file

CLI Example:

salt '*' aliases.rm_alias <alias>

salt.modules.aliases.set_target(alias, target)

Set the entry in the aliases file for the given alias, this will overwrite any previous entry for the given alias or create a new one if it does not exist.

CLI Example:

salt '*' aliases.set_target <alias> <target>

salt.modules.alternatives

Support for Alternatives system

codeauthor

Radek Rada <radek.rada@gmail.com>

copyright

license

Apache 2.0, see LICENSE for more details.

salt.modules.alternatives.check_installed(name, path)

Check if the alternatives link is set to desired path.

CLI Example:

salt '*' alternatives.check_installed name path

salt.modules.alternatives.display(name)

Display alternatives settings for defined command name.

CLI Example:

salt '*' alternatives.display <command name>

salt.modules.alternatives.install(name, link, path, priority)

Install symbolic links determining default commands.

CLI Example:

salt '*' alternatives.install name link path priority

salt.modules.alternatives.remove(name, path)

Remove symbolic links determining the default commands.

CLI Example:

salt '*' alternatives.remove name path

salt.modules.alternatives.show_current(name)

Display the current alternatives for the given name

CLI Example:

salt '*' alternatives.show_current emacs

salt.modules.apache

Support for Apache

salt.modules.apache.directives()

Return list of directives together with expected arguments and places where the directive is valid (apachectl -L)

CLI Example:

salt '*' apache.directives

salt.modules.apache.fullversion()

Return server version from apachectl -V

CLI Example:

salt '*' apache.fullversion

salt.modules.apache.modules()

Return list of static and shared modules from apachectl -M

CLI Example:

salt '*' apache.modules

salt.modules.apache.servermods()

Return list of modules compiled into the server (apachectl -l)

CLI Example:

salt '*' apache.servermods

salt.modules.apache.signal(signal=None)

Signals httpd to start, restart, or stop.

CLI Example:

salt '*' apache.signal restart

salt.modules.apache.version()

Return server version from apachectl -v

CLI Example:

salt '*' apache.version

salt.modules.apache.vhosts()

Show the settings as parsed from the config file (currently only shows the virtualhost settings). (apachectl -S) Because each additional virtual host adds to the execution time, this command may require a long timeout be specified.

CLI Example:

salt -t 10 '*' apache.vhosts

salt.modules.apt

Support for APT (Advanced Packaging Tool)

salt.modules.apt.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

salt.modules.apt.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.apt.del_repo(repo, refresh=False)

Delete a repo from the sources.list / sources.list.d

If the .list file is in the sources.list.d directory and the file that the repo exists in does not contain any other repo configuration, the file itself will be deleted.

The repo passed in must be a fully formed repository definition string.

CLI Examples:

salt '*' pkg.del_repo "myrepo definition"
salt '*' pkg.del_repo "myrepo definition" refresh=True

salt.modules.apt.file_dict(*packages)

List the files that belong to a package, grouped by package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.apt.file_list(*packages)

List the files that belong to a package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.apt.get_repo(repo)

Display a repo from the sources.list / sources.list.d

The repo passwd in needs to be a complete repo entry.

CLI Examples:

salt '*' pkg.get_repo "myrepo definition"

salt.modules.apt.install(name=None, refresh=False, fromrepo=None, skip_verify=False, debconf=None, pkgs=None, sources=None, **kwargs)

Install the passed package, add refresh=True to update the dpkg database.

name

The name of the package to be installed. Note that this parameter is ignored if either "pkgs" or "sources" is passed. Additionally, please note that this option can only be used to install packages from a software repository. To install a package file manually, use the "sources" option.

CLI Example::

salt '*' pkg.install <package name>

refresh

Whether or not to refresh the package database before installing.

fromrepo

Specify a package repository to install from (e.g., apt-get -t unstable install somepackage)

skip_verify

Skip the GPG verification check (e.g., --allow-unauthenticated, or --force-bad-verify for install from package file).

debconf

Provide the path to a debconf answers file, processed before installation.

version

Install a specific version of the package, e.g. 1.2.3~0ubuntu0. Ignored if "pkgs" or "sources" is passed.

Multiple Package Installation Options:

pkgs

A list of packages to install from a software repository. Must be passed as a python list.

CLI Example::

salt '*' pkg.install pkgs='["foo", "bar"]' salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-0ubuntu0"}]'

sources

A list of DEB packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

CLI Example::

salt '*' pkg.install sources='[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]'

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

salt.modules.apt.list_pkgs(regex_string='')

List the packages currently installed in a dict:

{'<package_name>': '<version>'}

External dependencies:

Virtual package resolution requires aptitude.
Without aptitude virtual packages will be reported as not installed.

CLI Example:

salt '*' pkg.list_pkgs
salt '*' pkg.list_pkgs httpd

salt.modules.apt.list_repos()

Lists all repos in the sources.list (and sources.lists.d) files

CLI Example:

salt '*' pkg.list_repos
salt '*' pkg.list_repos disabled=True

salt.modules.apt.list_upgrades(refresh=True)

List all available package upgrades.

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.apt.mod_repo(repo, refresh=False, **kwargs)

Modify one or more values for a repo. If the repo does not exist, it will be created, so long as the definition is well formed. For Ubuntu the "ppa:<project>/repo" format is acceptable. "ppa:" format can only be used to create a new repository.

The following options are available to modify a repo definition:

comps (a comma separated list of components for the repo, e.g. "main")
file (a file name to be used)
refresh (refresh the apt sources db when the mod is done)
keyserver (keyserver to get gpg key from)
keyid (key id to load with the keyserver argument)
key_url (URl to a gpg key to add to the apt gpg keyring)
consolidate (if true, will attempt to de-dup and consolidate sources)

CLI Examples:

salt '*' pkg.mod_repo 'myrepo definition' uri=http://new/uri
salt '*' pkg.mod_repo 'myrepo definition' comps=main,universe

salt.modules.apt.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0ubuntu1' '0.2.4.1-0ubuntu1'
salt '*' pkg.perform_cmp pkg1='0.2.4-0ubuntu1' pkg2='0.2.4.1-0ubuntu1'

salt.modules.apt.purge(pkg, **kwargs)

Remove a package via apt-get purge along with all configuration files and unused dependencies.

Returns a list containing the names of the removed packages

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.apt.refresh_db()

Updates the APT database to latest packages based upon repositories

Returns a dict, with the keys being package databases and the values being the result of the update attempt. Values can be one of the following:

True: Database updated successfully False: Problem updating database None: Database already up-to-date

CLI Example:

salt '*' pkg.refresh_db

salt.modules.apt.remove(pkg, **kwargs)

Remove a single package via apt-get remove

Returns a list containing the names of the removed packages.

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.apt.upgrade(refresh=True, **kwargs)

Upgrades all packages via apt-get dist-upgrade

Returns a list of dicts containing the package names, and the new and old versions:

[
    {'<package>':  {'old': '<old-version>',
                    'new': '<new-version>'}
    }',
    ...
]

CLI Example:

salt '*' pkg.upgrade

salt.modules.apt.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.apt.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

salt.modules.archive

A module to wrap archive calls

salt.modules.archive.gunzip(gzipfile, template=None)

Uses the gunzip command to unpack gzip files

CLI Example to create /tmp/sourcefile.txt:

salt '*' archive.gunzip /tmp/sourcefile.txt.gz

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. CLI Example:

salt '*' archive.gunzip template=jinja /tmp/{{"{{"}}grains.id}}.txt.gz

salt.modules.archive.gzip(sourcefile, template=None)

Uses the gzip command to create gzip files

CLI Example to create /tmp/sourcefile.txt.gz:

salt '*' archive.gzip /tmp/sourcefile.txt

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. CLI Example:

salt '*' archive.gzip template=jinja /tmp/{{"{{"}}grains.id}}.txt

salt.modules.archive.rar(rarfile, template=None, *sources)

Uses the rar command to create rar files Uses rar for Linux from http://www.rarlab.com/

CLI Example:

salt '*' archive.rar /tmp/rarfile.rar /tmp/sourcefile1 /tmp/sourcefile2

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' archive.rar template=jinja /tmp/rarfile.rar /tmp/sourcefile1 /tmp/{{"{{"}}grains.id}}.txt

salt.modules.archive.tar(options, tarfile, cwd=None, template=None, *sources)

Uses the tar command to pack, unpack, etc tar files

CLI Example:

salt '*' archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file_1 /tmp/file_2

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' archive.tar template=jinja cjvf /tmp/salt.tar.bz2 {{"{{"}}grains.saltpath}}

salt.modules.archive.unrar(rarfile, dest, template=None, *xfiles)

Uses the unrar command to unpack rar files Uses rar for Linux from http://www.rarlab.com/

CLI Example:

salt '*' archive.unrar /tmp/rarfile.rar /home/strongbad/ file_1 file_2

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' archive.unrar template=jinja /tmp/rarfile.rar /tmp/{{"{{"}}grains.id}}/ file_1 file_2

salt.modules.archive.unzip(zipfile, dest, template=None, *xfiles)

Uses the unzip command to unpack zip files

CLI Example:

salt '*' archive.unzip /tmp/zipfile.zip /home/strongbad/ file_1 file_2

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' archive.unzip template=jinja /tmp/zipfile.zip /tmp/{{"{{"}}grains.id}}/ file_1 file_2

salt.modules.archive.zip(zipfile, template=None, *sources)

Uses the zip command to create zip files

CLI Example:

salt '*' archive.zip /tmp/zipfile.zip /tmp/sourcefile1 /tmp/sourcefile2

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' archive.zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1 /tmp/{{"{{"}}grains.id}}.txt

salt.modules.at

Wrapper module for at(1) Also, a 'tag' feature has been added to more easily tag jobs.

salt.modules.at.at(*args, **kwargs)

Add a job to the queue.

The 'timespec' follows the format documented in the at(1) manpage.

CLI Example:

salt '*' at.at <timespec> <cmd> [tag=<tag>] [runas=<user>]
salt '*' at.at 12:05am '/sbin/reboot' tag=reboot
salt '*' at.at '3:05am +3 days' 'bin/myscript' tag=nightly runas=jim

salt.modules.at.atc(jobid)

Print the at(1) script that will run for the passed job id. This is mostly for debugging so the output will just be text.

CLI Example:

salt '*' at.atc <jobid>

salt.modules.at.atq(tag=None)

List all queued and running jobs or only those with an optional 'tag'.

CLI Example:

salt '*' at.atq
salt '*' at.atq [tag]
salt '*' at.atq [job number]

salt.modules.at.atrm(*args)

Remove jobs from the queue.

CLI Example:

salt '*' at.atrm <jobid> <jobid> .. <jobid>
salt '*' at.atrm all
salt '*' at.atrm all [tag]

salt.modules.augeas_cfg

Manages configuration files via augeas

depends

• Augeas Python adapter

salt.modules.augeas_cfg.get(path, value='')

Get a value for a specific augeas path

CLI Example:

salt '*' augeas.get /files/etc/hosts/1/ ipaddr

salt.modules.augeas_cfg.ls(path)

List the direct children of a node

CLI Example:

salt '*' augeas.ls /files/etc/passwd

salt.modules.augeas_cfg.match(path, value='')

Get matches for path expression

CLI Example:

salt '*' augeas.match /files/etc/services/service-name ssh

salt.modules.augeas_cfg.remove(path)

Get matches for path expression

CLI Example:

salt '*' augeas.remove /files/etc/sysctl.conf/net.ipv4.conf.all.log_martians

salt.modules.augeas_cfg.setvalue(*args)

Set a value for a specific augeas path

CLI Example:

salt '*' augeas.setvalue /files/etc/hosts/1/canonical localhost

This will set the first entry in /etc/hosts to localhost

CLI Example:

salt '*' augeas.setvalue /files/etc/hosts/01/ipaddr 192.168.1.1 \
                         /files/etc/hosts/01/canonical test

Adds a new host to /etc/hosts the ip address 192.168.1.1 and hostname test

CLI Example:

salt '*' augeas.setvalue prefix=/files/etc/sudoers/ \
         "spec[user = '%wheel']/user" "%wheel" \
         "spec[user = '%wheel']/host_group/host" 'ALL' \
         "spec[user = '%wheel']/host_group/command[1]" 'ALL' \
         "spec[user = '%wheel']/host_group/command[1]/tag" 'PASSWD' \
         "spec[user = '%wheel']/host_group/command[2]" '/usr/bin/apt-get' \
         "spec[user = '%wheel']/host_group/command[2]/tag" NOPASSWD

Ensures that the following line is present in /etc/sudoers:

%wheel ALL = PASSWD : ALL , NOPASSWD : /usr/bin/apt-get , /usr/bin/aptitude

salt.modules.augeas_cfg.tree(path)

Returns recursively the complete tree of a node

CLI Example:

salt '*' augeas.tree /files/etc/

salt.modules.bluez

Support for Bluetooth (using Bluez in Linux)

salt.modules.bluez.address()

Get the many addresses of the Bluetooth adapter

CLI Example:

salt '*' bluetooth.address

salt.modules.bluez.pair(address, key)

Pair the bluetooth adapter with a device

CLI Example:

salt '*' bluetooth.pair DE:AD:BE:EF:CA:FE 1234

Where DE:AD:BE:EF:CA:FE is the address of the device to pair with, and 1234 is the passphrase.

salt.modules.bluez.scan()

Scan for bluetooth devices in the area

CLI Example:

salt '*' bluetooth.scan

salt.modules.bluez.start()

Start the bluetooth service.

CLI Example:

salt '*' bluetooth.start

salt.modules.bluez.stop()

Stop the bluetooth service.

CLI Example:

salt '*' bluetooth.stop

salt.modules.bluez.unpair(address)

Unpair the bluetooth adapter from a device

CLI Example:

salt '*' bluetooth.unpair DE:AD:BE:EF:CA:FE

Where DE:AD:BE:EF:CA:FE is the address of the device to unpair.

salt.modules.bluez.version()

Return Bluez version from bluetoothd -v

CLI Example:

salt '*' bluetoothd.version

salt.modules.brew

Homebrew for Mac OS X

salt.modules.brew.available_version(*names)

Return the latest version of the named package available for upgrade or installation

Note that this currently not fully implemented but needs to return something to avoid a traceback when calling pkg.latest.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3>

salt.modules.brew.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.brew.install(name=None, pkgs=None, **kwargs)

Install the passed package(s) with brew install

name

The name of the formula to be installed. Note that this parameter is ignored if "pkgs" is passed.

CLI Example::

salt '*' pkg.install <package name>

Multiple Package Installation Options:

pkgs

A list of formulas to install. Must be passed as a python list.

CLI Example::

salt '*' pkg.install pkgs='["foo","bar"]'

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.install 'package package package'

salt.modules.brew.list_pkgs(*args)

List the packages currently installed in a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.brew.list_upgrades()

Check whether or not an upgrade is available for all packages

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.brew.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.brew.remove(pkgs, **kwargs)

Removes packages with brew uninstall

Return a list containing the removed packages:

CLI Example:

salt '*' pkg.remove <package,package,package>

salt.modules.brew.upgrade_available(pkg)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.brew.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3>

salt.modules.butterkvm

Specialized routines used by the butter cloud component
salt.modules.butterkvm.create(instance, vda, image, pin): Create a virtual machine, this is part of the butter vm system and assumes that the files prepared by butter are available via shared storage. AKA - don't call this from the command line!; instance

string The path to the instance directory for the given vm on shared storage

vda

The location where the virtual machine image needs to be placed

image

The image to move into place

pin

A "pin" data structure defining the myriad of possible vdb-vbz disk images to generate

CLI Example:

salt '*' butterkvm.create <instance dir> <root image location>\
    <Destination> <pin data>

salt.modules.butterkvm.full_butter_data(local_path)

Return the full virt info, but add butter data!

CLI Example:

salt '*' buttervm.full_butter_data <image_path>

salt.modules.butterkvm.libvirt_creds()

Returns the user and group that the disk images should be owned by

CLI Example:

salt '*' butterkvm.libvirt_creds

salt.modules.butterkvm.local_images(local_path)

return the virtual machine names for all of the images located in the butter cloud's local_path in a list:

['vm1.boo.com', 'vm2.foo.com']

CLI Example:

salt '*' buttervm.local_images <image_path>

salt.modules.cassandra

Cassandra NoSQL Database Module

depends

• pycassa Cassandra Python adapter

configuration

The location of the 'nodetool' command, host, and thrift port needs to be specified via pillar:

cassandra.nodetool: /usr/local/bin/nodetool
cassandra.host: localhost
cassandra.thrift_port: 9160

salt.modules.cassandra.column_families(keyspace=None)

Return existing column families for all keyspaces or just the provided one.

CLI Example:

salt '*' cassandra.column_families
salt '*' cassandra.column_families <keyspace>

salt.modules.cassandra.column_family_definition(keyspace=None, column_family=None)

Return a dictionary of column family definitions for the given keyspace/column_family

CLI Example:

salt '*' cassandra.column_family_definition <keyspace> <column_family>

salt.modules.cassandra.compactionstats()

Return compactionstats info

CLI Example:

salt '*' cassandra.compactionstats

salt.modules.cassandra.info()

Return cassandra node info

CLI Example:

salt '*' cassandra.info

salt.modules.cassandra.keyspaces()

Return existing keyspaces

CLI Example:

salt '*' cassandra.keyspaces

salt.modules.cassandra.netstats()

Return netstats info

CLI Example:

salt '*' cassandra.netstats

salt.modules.cassandra.ring()

Return cassandra ring info

CLI Example:

salt '*' cassandra.ring

salt.modules.cassandra.tpstats()

Return tpstats info

CLI Example:

salt '*' cassandra.tpstats

salt.modules.cassandra.version()

Return the cassandra version

CLI Example:

salt '*' cassandra.version

salt.modules.cmdmod

A module for shelling out Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions

salt.modules.cmdmod.exec_code(lang, code, cwd=None)

Pass in two strings, the first naming the executable language, aka - python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. The stdout and stderr will be returned

CLI Example:

salt '*' cmd.exec_code ruby 'puts "cheese"'

salt.modules.cmdmod.has_exec(cmd)

Returns true if the executable is available on the minion, false otherwise

CLI Example:

salt '*' cmd.has_exec cat

salt.modules.cmdmod.retcode(cmd, cwd=None, runas=None, shell='/bin/zsh', env=(), template=None)

Execute a shell command and return the command's return code.

CLI Example:

salt '*' cmd.retcode "file /bin/bash"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.retcode template=jinja "file {{"{{"}}grains.pythonpath[0]}}/python"

salt.modules.cmdmod.run(cmd, cwd=None, runas=None, shell='/bin/zsh', env=(), template=None, rstrip=True)

Execute the passed command and return the output as a string

CLI Example:

salt '*' cmd.run "ls -l | awk '/foo/{print $2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run template=jinja "ls -l /tmp/{{"{{"}}grains.id}} | awk '/foo/{print $2}'"

salt.modules.cmdmod.run_all(cmd, cwd=None, runas=None, shell='/bin/zsh', env=(), template=None, rstrip=True)

Execute the passed command and return a dict of return data

CLI Example:

salt '*' cmd.run_all "ls -l | awk '/foo/{print $2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run_all template=jinja "ls -l /tmp/{{"{{"}}grains.id}} | awk '/foo/{print $2}'"

salt.modules.cmdmod.run_stderr(cmd, cwd=None, runas=None, shell='/bin/zsh', env=(), template=None, rstrip=True)

Execute a command and only return the standard error

CLI Example:

salt '*' cmd.run_stderr "ls -l | awk '/foo/{print $2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run_stderr template=jinja "ls -l /tmp/{{"{{"}}grains.id}} | awk '/foo/{print $2}'"

salt.modules.cmdmod.run_stdout(cmd, cwd=None, runas=None, shell='/bin/zsh', env=(), template=None, rstrip=True)

Execute a command, and only return the standard out

CLI Example:

salt '*' cmd.run_stdout "ls -l | awk '/foo/{print $2}'"

The template arg can be set to 'jinja' or another supported template engine to render the command arguments before execution. For example:

salt '*' cmd.run_stdout template=jinja "ls -l /tmp/{{"{{"}}grains.id}} | awk '/foo/{print $2}'"

salt.modules.cmdmod.script(source, args=None, cwd=None, runas=None, shell='/bin/zsh', env='base', template='jinja', **kwargs)

Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an http/ftp server.

The script will be executed directly, so it can be written in any available programming language.

The script can also be formated as a template, the default is jinja. Arguments for the script can be specified as well.

CLI Example:

salt '*' cmd.script salt://scripts/runme.sh
salt '*' cmd.script salt://scripts/runme.sh 'arg1 arg2 "arg 3"'

salt.modules.cmdmod.script_retcode(source, cwd=None, runas=None, shell='/bin/zsh', env='base', template='jinja', **kwargs)

Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an http/ftp server.

The script will be executed directly, so it can be written in any available programming language.

The script can also be formated as a template, the default is jinja.

Only evaluate the script return code and do not block for terminal output

CLI Example:

salt '*' cmd.script_retcode salt://scripts/runme.sh

salt.modules.cmdmod.which(cmd)

Returns the path of an executable available on the minion, None otherwise

CLI Example:

salt '*' cmd.which cat

salt.modules.cmdmod.which_bin(cmds)

Returns the first command found in a list of commands

CLI Example:

salt '*' cmd.which_bin '[pip2, pip, pip-python]'

salt.modules.config

Return config information

salt.modules.config.backup_mode(backup='')

Return the backup mode

CLI Example:

salt '*' config.backup_mode

salt.modules.config.dot_vals(value)

Pass in a configuration value that should be preceded by the module name and a dot, this will return a list of all read key/value pairs

CLI Example:

salt '*' config.dot_vals host

salt.modules.config.manage_mode(mode)

Return a mode value, normalized to a string

CLI Example:

salt '*' config.manage_mode

salt.modules.config.option(value, default='', omit_opts=False, omit_master=False, omit_pillar=False)

Pass in a generic option and receive the value that will be assigned

CLI Example:

salt '*' config.option redis.host

salt.modules.config.valid_fileproto(uri)

Returns a boolean value based on whether or not the URI passed has a valid remote file protocol designation

CLI Example:

salt '*' config.valid_fileproto salt://path/to/file

salt.modules.cp

Minion side functions for salt-cp

salt.modules.cp.cache_dir(path, env='base', include_empty=False)

Download and cache everything under a directory from the master

CLI Example:

salt '*' cp.cache_dir salt://path/to/dir

salt.modules.cp.cache_file(path, env='base')

Used to cache a single file in the local salt-master file cache.

CLI Example:

salt '*' cp.cache_file salt://path/to/file

salt.modules.cp.cache_files(paths, env='base')

Used to gather many files from the master, the gathered files will be saved in the minion cachedir reflective to the paths retrieved from the master.

CLI Example:

salt '*' cp.cache_files salt://pathto/file1,salt://pathto/file1

salt.modules.cp.cache_local_file(path)

Cache a local file on the minion in the localfiles cache

CLI Example:

salt '*' cp.cache_local_file /etc/hosts

salt.modules.cp.cache_master(env='base')

Retrieve all of the files on the master and cache them locally

CLI Example:

salt '*' cp.cache_master

salt.modules.cp.get_dir(path, dest, env='base', template=None, gzip=None)

Used to recursively copy a directory from the salt master

CLI Example:

salt '*' cp.get_dir salt://path/to/dir/ /minion/dest

get_dir supports the same template and gzip arguments as get_file.

salt.modules.cp.get_file(path, dest, env='base', makedirs=False, template=None, gzip=None)

Used to get a single file from the salt master

CLI Example:

salt '*' cp.get_file salt://path/to/file /minion/dest

Template rendering can be enabled on both the source and destination file names like so:

salt '*' cp.get_file "salt://{{"{{"}}grains.os}}/vimrc" /etc/vimrc template=jinja

This example would instruct all Salt minions to download the vimrc from a directory with the same name as their os grain and copy it to /etc/vimrc

For larger files, the cp.get_file module also supports gzip compression. Because gzip is CPU-intensive, this should only be used in scenarios where the compression ratio is very high (e.g. pretty-printed JSON or YAML files).

Use the gzip named argument to enable it. Valid values are 1..9, where 1 is the lightest compression and 9 the heaviest. 1 uses the least CPU on the master (and minion), 9 uses the most.

salt.modules.cp.get_file_str(path, env='base')

Return the contents of a file from a url

CLI Example:

salt '*' cp.get_file_str salt://my/file

salt.modules.cp.get_template(path, dest, template='jinja', env='base', **kwargs)

Render a file as a template before setting it down

CLI Example:

salt '*' cp.get_template salt://path/to/template /minion/dest

salt.modules.cp.get_url(path, dest, env='base')

Used to get a single file from a URL.

CLI Example:

salt '*' cp.get_url salt://my/file /tmp/mine
salt '*' cp.get_url http://www.slashdot.org /tmp/index.html

salt.modules.cp.hash_file(path, env='base')

Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file.

CLI Example:

salt '*' cp.hash_file salt://path/to/file

salt.modules.cp.is_cached(path, env='base')

Return a boolean if the given path on the master has been cached on the minion

CLI Example:

salt '*' cp.is_cached salt://path/to/file

salt.modules.cp.list_master(env='base')

List all of the files stored on the master

CLI Example:

salt '*' cp.list_master

salt.modules.cp.list_master_dirs(env='base')

List all of the directories stored on the master

CLI Example:

salt '*' cp.list_master_dirs

salt.modules.cp.list_minion(env='base')

List all of the files cached on the minion

CLI Example:

salt '*' cp.list_minion

salt.modules.cp.list_states(env='base')

List all of the available state modules in an environment

CLI Example:

salt '*' cp.list_states

salt.modules.cp.recv(files, dest)

Used with salt-cp, pass the files dict, and the destination.

This function receives small fast copy files from the master via salt-cp

CLI Example:

This function does not work via the CLI

salt.modules.cron

Work with cron

salt.modules.cron.list_tab(user)

Return the contents of the specified user's crontab

CLI Example:

salt '*' cron.list_tab root

salt.modules.cron.ls(user)

Return the contents of the specified user's crontab

CLI Example:

salt '*' cron.list_tab root

salt.modules.cron.raw_cron(user)

Return the contents of the user's crontab

CLI Example:

salt '*' cron.raw_cron root

salt.modules.cron.rm(user, minute, hour, dom, month, dow, cmd)

Remove a cron job for a specified user.

CLI Example:

salt '*' cron.rm_job root \* \* \* \* 1 /usr/local/weekly

salt.modules.cron.rm_env(user, name)

Remove cron environment variable for a specified user.

CLI Example:

salt '*' cron.rm_env root MAILTO

salt.modules.cron.rm_job(user, minute, hour, dom, month, dow, cmd)

Remove a cron job for a specified user.

CLI Example:

salt '*' cron.rm_job root \* \* \* \* 1 /usr/local/weekly

salt.modules.cron.set_env(user, name, value=None)

Set up an environment variable in the crontab.

CLI Example:

salt '*' cron.set_env root MAILTO user@example.com

salt.modules.cron.set_job(user, minute, hour, dom, month, dow, cmd)

Sets a cron job up for a specified user.

CLI Example:

salt '*' cron.set_job root \* \* \* \* 1 /usr/local/weekly

salt.modules.cron.set_special(user, special, cmd)

Set up a special command in the crontab.

CLI Example:

salt '*' cron.set_special @hourly 'echo foobar'

salt.modules.cron.write_cron_file(user, path)

Writes the contents of a file to a user's crontab

CLI Example:

salt '*' cron.write_cron_file root /tmp/new_cron

salt.modules.daemontools

daemontools service module. This module will create daemontools type service watcher. This module is states.service compatible so it can be used to maintain service state via provider interface:

• provider: daemontools

salt.modules.daemontools.full_restart(name)

Calls daemontools.restart() function

CLI Example:

salt '*' daemontools.full_restart <service name>

salt.modules.daemontools.get_all()

Return a list of all available services

CLI Example:

salt '*' daemontools.get_all

salt.modules.daemontools.reload(name)

Wrapper for term()

CLI Example:

salt '*' daemontools.reload <service name>

salt.modules.daemontools.restart(name)

Restart service via daemontools. This will stop/start service

CLI Example:

salt '*' daemontools.restart <service name>

salt.modules.daemontools.start(name, enable=None, sig=None)

Starts service via daemontools

CLI Example:

salt '*' daemontools.start <service name>

salt.modules.daemontools.status(name, sig=None)

Return the status for a service via daemontools, return pid if running

CLI Example:

salt '*' daemontools.status <service name>

salt.modules.daemontools.stop(name, enable=None, sig=None)

Stops service via daemontools

CLI Example:

salt '*' daemontools.stop <service name>

salt.modules.daemontools.term(name)

Send a TERM to service via daemontools

CLI Example:

salt '*' daemontools.term <service name>

salt.modules.data

Manage a local persistent data structure that can hold any arbitrary data specific to the minion

salt.modules.data.clear()

Clear out all of the data in the minion datastore, this function is destructive!

CLI Example:

salt '*' data.clear

salt.modules.data.dump(new_data)

Replace the entire datastore with a passed data structure

CLI Example:

salt '*' data.dump '{'eggs': 'spam'}'

salt.modules.data.getval(key)

Get a value from the minion datastore

CLI Example:

salt '*' data.getval <key>

salt.modules.data.getvals(*keys)

Get values from the minion datastore

CLI Example:

salt '*' data.getvals <key> [<key> ...]

salt.modules.data.load()

Return all of the data in the minion datastore

CLI Example:

salt '*' data.load

salt.modules.data.update(key, value)

Update a key with a value in the minion datastore

CLI Example:

salt '*' data.update <key> <value>

salt.modules.debconfmod

Support for Debconf

salt.modules.debconfmod.get_selections(fetchempty=True)

Answers to debconf questions for all packages in the following format:

{'package': [['question', 'type', 'value'], ...]}

CLI Example:

salt '*' debconf.get_selections

salt.modules.debconfmod.set(package, question, type, value, *extra)

Set answers to debconf questions for a package.

CLI Example:

salt '*' debconf.set <package> <question> <type> <value> [<value> ...]

salt.modules.debconfmod.set_file(path)

Set answers to debconf questions from a file.

CLI Example:

salt '*' debconf.set_file salt://pathto/pkg.selections

salt.modules.debconfmod.show(name)

Answers to debconf questions for a package in the following format:

[['question', 'type', 'value'], ...]

If debconf doesn't know about a package, we return None.

CLI Example:

salt '*' debconf.show <package name>

salt.modules.debian_service

Service support for Debian systems - uses update-rc.d and service to modify the system

salt.modules.debian_service.disable(name, **kwargs)

Disable the named service to start at boot

CLI Example:

salt '*' service.disable <service name>

salt.modules.debian_service.disabled(name)

Return True if the named servioce is enabled, false otherwise

CLI Example:

salt '*' service.disabled <service name>

salt.modules.debian_service.enable(name, **kwargs)

Enable the named service to start at boot

CLI Example:

salt '*' service.enable <service name>

salt.modules.debian_service.enabled(name)

Return True if the named servioce is enabled, false otherwise

CLI Example:

salt '*' service.enabled <service name>

salt.modules.debian_service.force_reload(name)

Force-reload the named service

CLI Example:

salt '*' service.force_reload <service name>

salt.modules.debian_service.get_all()

Return all available boot services

CLI Example:

salt '*' service.get_all

salt.modules.debian_service.get_disabled()

Return a set of services that are installed but disabled

CLI Example:

salt '*' service.get_disabled

salt.modules.debian_service.get_enabled()

Return a list of service that are enabled on boot

CLI Example:

salt '*' service.get_enabled

salt.modules.debian_service.reload(name)

Reload the named service

CLI Example:

salt '*' service.reload <service name>

salt.modules.debian_service.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.debian_service.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.debian_service.status(name, sig=None)

Return the status for a service, pass a signature to use to find the service via ps

CLI Example:

salt '*' service.status <service name>

salt.modules.debian_service.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.disk

Module for gathering disk information

salt.modules.disk.inodeusage(args=None)

Return inode usage information for volumes mounted on this minion

CLI Example:

salt '*' disk.inodeusage

salt.modules.disk.usage(args=None)

Return usage information for volumes mounted on this minion

CLI Example:

salt '*' disk.usage

salt.modules.djangomod

Manage Django sites

salt.modules.djangomod.collectstatic(settings_module, bin_env=None, no_post_process=False, ignore=None, dry_run=False, clear=False, link=False, no_default_ignore=False, pythonpath=None)

Collect static files from each of your applications into a single location that can easily be served in production.

CLI Example:

salt '*' django.collectstatic settings.py

salt.modules.djangomod.command(settings_module, command, bin_env=None, pythonpath=None, *args, **kwargs)

Run arbitrary django management command

CLI Example:

salt '*' django.command <settings_module> <command>

salt.modules.djangomod.createsuperuser(settings_module, username, email, bin_env=None, database=None, pythonpath=None)

Create a super user for the database. This function defaults to use the --noinput flag which prevents the creation of a password for the superuser.

CLI Example:

salt '*' django.createsuperuser settings.py user user@example.com

salt.modules.djangomod.loaddata(settings_module, fixtures, bin_env=None, database=None, pythonpath=None)

Load fixture data

Fixtures:

comma separated list of fixtures to load

CLI Example:

salt '*' django.loaddata settings.py <comma delimited list of fixtures>

salt.modules.djangomod.syncdb(settings_module, bin_env=None, migrate=False, database=None, pythonpath=None, noinput=True)

Run syncdb

Execute the Django-Admin syncdb command, if South is available on the minion the migrate option can be passed as True calling the migrations to run after the syncdb completes

CLI Example:

salt '*' django.syncdb settings.py

salt.modules.ebuild

Support for Portage

optdepends

• portage Python adapter

For now all package names MUST include the package category, i.e. 'vim' will not work, 'app-editors/vim' will.

salt.modules.ebuild.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

salt.modules.ebuild.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.ebuild.depclean(pkg=None, slot=None)

Portage has a function to remove unused dependencies. If a package is provided, it will only removed the package if no other package depends on it.

slot

Restrict the remove to a specific slot. Ignored if pkg is None

Return a list containing the removed packages:

CLI Example:

salt '*' pkg.depclean <package name>

salt.modules.ebuild.install(name=None, refresh=False, pkgs=None, sources=None, slot=None, **kwargs)

Install the passed package(s), add refresh=True to sync the portage tree before package is installed.

name

The name of the package to be installed. Note that this parameter is ignored if either "pkgs" or "sources" is passed. Additionally, please note that this option can only be used to emerge a package from the portage tree. To install a tbz2 package manually, use the "sources" option described below.

CLI Example::

salt '*' pkg.install <package name>

refresh

Whether or not to sync the portage tree before installing.

version

Install a specific version of the package, e.g. 1.0.9-r1. Ignored if "pkgs" or "sources" is passed.

slot

Similar to version, but specifies a valid slot to be installed. It will install the latest available version in the specified slot. Ignored if "pkgs" or "sources" or "version" is passed.

CLI Example::

salt '*' pkg.install sys-devel/gcc slot='4.4'

Multiple Package Installation Options:

pkgs

A list of packages to install from the portage tree. Must be passed as a python list.

CLI Example::

salt '*' pkg.install pkgs='["foo","bar"]'

sources

A list of tbz2 packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

CLI Example::

salt '*' pkg.install sources='[{"foo": "salt://foo.tbz2"},{"bar": "salt://bar.tbz2"}]'

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

salt.modules.ebuild.list_pkgs()

List the packages currently installed in a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.ebuild.list_upgrades(refresh=True)

List all available package upgrades.

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.ebuild.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.ebuild.porttree_matches(name)

Returns a list containing the matches for a given package name from the portage tree. Note that the specific version of the package will not be provided for packages that have several versions in the portage tree, but rather the name of the package (i.e. "dev-python/paramiko").

salt.modules.ebuild.purge(pkg, **kwargs)

Portage does not have a purge, this function calls remove followed by depclean to emulate a purge process

Return a list containing the removed packages:

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.ebuild.refresh_db()

Updates the portage tree (emerge --sync). Uses eix-sync if available.

CLI Example:

salt '*' pkg.refresh_db

salt.modules.ebuild.remove(pkg, slot=None, **kwargs)

Remove a single package via emerge --unmerge

slot

Restrict the remove to a specific slot.

Return a list containing the names of the removed packages:

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.ebuild.update(pkg, slot=None, refresh=False)

Updates the passed package (emerge --update package)

slot

Restrict the update to a particular slot. It will update to the latest version within the slot.

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.update <package name>

salt.modules.ebuild.upgrade(refresh=True)

Run a full system upgrade (emerge --update world)

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

salt.modules.ebuild.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.ebuild.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

salt.modules.eix

Support for Eix

salt.modules.eix.sync()

Sync portage/overlay trees and update the eix database

CLI Example:

salt '*' eix.sync

salt.modules.eix.update()

Update the eix database

CLI Example:

salt '*' eix.update

salt.modules.event

Fire events on the minion, events can be fired up to the master

salt.modules.event.fire(data, tag)

Fire an event on the local minion event bus

CLI Example:

salt '*' event.fire 'stuff to be in the event' 'tag'

salt.modules.event.fire_master(data, tag)

Fire an event off on the master server

CLI Example:

salt '*' event.fire_master 'stuff to be in the event' 'tag'

salt.modules.extfs

Module for managing ext2/3/4 file systems

salt.modules.extfs.attributes(device, args=None)

Return attributes from dumpe2fs for a specified device

CLI Example:

salt '*' extfs.attributes /dev/sda1

salt.modules.extfs.blocks(device, args=None)

Return block and inode info from dumpe2fs for a specified device

CLI Example:

salt '*' extfs.blocks /dev/sda1

salt.modules.extfs.dump(device, args=None)

Return all contents of dumpe2fs for a specified device

CLI Example:

salt '*' extfs.dump /dev/sda1

salt.modules.extfs.mkfs(device, fs_type, **kwargs)

Create a file system on the specified device

CLI Example:

salt '*' extfs.mkfs /dev/sda1 fs_type=ext4 opts='acl,noexec'

Valid options are:

block_size: 1024, 2048 or 4096
check: check for bad blocks
direct: use direct IO
ext_opts: extended file system options (comma-separated)
fragment_size: size of fragments
force: setting force to True will cause mke2fs to specify the -F option
       twice (it is already set once); this is truly dangerous
blocks_per_group: number of blocks in a block group
number_of_groups: ext4 option for a virtual block group
bytes_per_inode: set the bytes/inode ratio
inode_size: size of the inode
journal: set to True to create a journal (default on ext3/4)
journal_opts: options for the fs journal (comma separated)
blocks_file: read bad blocks from file
label: label to apply to the file system
reserved: percentage of blocks reserved for super-user
last_dir: last mounted directory
test: set to True to not actually create the file system (mke2fs -n)
number_of_inodes: override default number of inodes
creator_os: override "creator operating system" field
opts: mount options (comma separated)
revision: set the filesystem revision (default 1)
super: write superblock and group descriptors only
fs_type: set the filesystem type (REQUIRED)
usage_type: how the filesystem is going to be used
uuid: set the UUID for the file system

see man 8 mke2fs for a more complete description of these options

salt.modules.extfs.tune(device, **kwargs)

Set attributes for the specified device (using tune2fs)

CLI Example:

salt '*' extfs.tune /dev/sda1 force=True label=wildstallyns opts='acl,noexec'

Valid options are:

max: max mount count
count: mount count
error: error behavior
extended_opts: extended options (comma separated)
force: force, even if there are errors (set to True)
group: group name or gid that can use the reserved blocks
interval: interval between checks
journal: set to True to create a journal (default on ext3/4)
journal_opts: options for the fs journal (comma separated)
label: label to apply to the file system
reserved: percentage of blocks reserved for super-user
last_dir: last mounted directory
opts: mount options (comma separated)
feature: set or clear a feature (comma separated)
mmp_check: mmp check interval
reserved: reserved blocks count
quota_opts: quota options (comma separated)
time: time last checked
user: user or uid who can use the reserved blocks
uuid: set the UUID for the file system

see man 8 tune2fs for a more complete description of these options

salt.modules.file

Manage information about files on the minion, set/read user, group, and mode data

salt.modules.file.append(path, *args)

Append text to the end of a file

CLI Example:

salt '*' file.append /etc/motd \
        "With all thine offerings thou shalt offer salt."\
        "Salt is what makes things taste bad when it isn't in them."

New in version 0.9.5.

salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, env)

Check for the changes in the file metadata.

CLI Example:

salt '*' file.check_file_meta /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' base

salt.modules.file.check_hash(path, hash)

Check if a file matches the given hash string

Returns true if the hash matched, otherwise false. Raises ValueError if the hash was not formatted correctly.

path

A file path

hash

A string in the form <hash_type>=<hash_value>. For example: md5=e138491e9d5b97023cea823fe17bac22

CLI Example:

salt '*' file.check_hash /etc/fstab md5=<md5sum>

salt.modules.file.check_managed(name, source, source_hash, user, group, mode, template, makedirs, context, defaults, env, **kwargs)

Check to see what changes need to be made for a file

CLI Example:

salt '*' file.check_managed /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root, root, '755' jinja True None None base

salt.modules.file.check_perms(name, ret, user, group, mode)

Check the permissions on files and chown if needed

Note: 'mode' here is expected to be either a string or an integer,

in which case it will be converted into a base-10 string.

What this means is that in your YAML salt file, you can specify mode as an integer(eg, 644) or as a string(eg, '644'). But, to specify mode 0777, for example, it must be specified as the string, '0777' otherwise, 0777 will be parsed as an octal and you'd get 511 instead.

CLI Example:

salt '*' file.check_perms /etc/sudoers '{}' root root 400

salt.modules.file.chgrp(path, group)

Change the group of a file

CLI Example:

salt '*' file.chgrp /etc/passwd root

salt.modules.file.chown(path, user, group)

Chown a file, pass the file the desired user and group

CLI Example:

salt '*' file.chown /etc/passwd root root

salt.modules.file.comment(path, regex, char='#', backup='.bak')

Comment out specified lines in a file

path

The full path to the file to be edited

regex

char

# The character to be inserted at the beginning of a line in order to comment it out

backup

.bak The file will be backed up before edit with this file extension

Warning

This backup will be overwritten each time sed / comment / uncomment is called. Meaning the backup will only be useful after the first invocation.

CLI Example:

salt '*' file.comment /etc/modules pcspkr

New in version 0.9.5.

salt.modules.file.contains(path, text)

Return True if the file at path contains text

CLI Example:

salt '*' file.contains /etc/crontab 'mymaintenance.sh'

New in version 0.9.5.

salt.modules.file.contains_glob(path, glob)

Return True if the given glob matches a string in the named file

CLI Example:

salt '*' file.contains_glob /etc/foobar '*cheese*'

salt.modules.file.contains_regex(path, regex, lchar='')

Return True if the given regular expression matches anything in the text of a given file

CLI Example:

salt '*' file.contains_regex /etc/crontab '^maint'

salt.modules.file.directory_exists(path)

Tests to see if path is a valid directory. Returns True/False.

CLI Example:

salt '*' file.directory_exists /etc

salt.modules.file.file_exists(path)

Tests to see if path is a valid file. Returns True/False.

CLI Example:

salt '*' file.file_exists /etc/passwd

salt.modules.file.find(path, **kwargs)

Approximate the Unix find(1) command and return a list of paths that meet the specified critera.

The options include match criteria:

name    = path-glob                 # case sensitive
iname   = path-glob                 # case insensitive
regex   = path-regex                # case sensitive
iregex  = path-regex                # case insensitive
type    = file-types                # match any listed type
user    = users                     # match any listed user
group   = groups                    # match any listed group
size    = [+-]number[size-unit]     # default unit = byte
mtime   = interval                  # modified since date
grep    = regex                     # search file contents

and/or actions:

delete [= file-types]               # default type = 'f'
exec    = command [arg ...]         # where {} is replaced by pathname
print  [= print-opts]

The default action is 'print=path'.

file-glob:

*                = match zero or more chars
?                = match any char
[abc]            = match a, b, or c
[!abc] or [^abc] = match anything except a, b, and c
[x-y]            = match chars x through y
[!x-y] or [^x-y] = match anything except chars x through y
{a,b,c}          = match a or b or c

path-regex: a Python re (regular expression) pattern to match pathnames

file-types: a string of one or more of the following:

a: all file types
b: block device
c: character device
d: directory
p: FIFO (named pipe)
f: plain file
l: symlink
s: socket

users: a space and/or comma separated list of user names and/or uids

groups: a space and/or comma separated list of group names and/or gids

size-unit:

b: bytes
k: kilobytes
m: megabytes
g: gigabytes
t: terabytes

interval:

[<num>w] [<num>[d]] [<num>h] [<num>m] [<num>s]

where:
    w: week
    d: day
    h: hour
    m: minute
    s: second

print-opts: a comma and/or space separated list of one or more of the following:

group: group name
md5:   MD5 digest of file contents
mode:  file permissions (as integer)
mtime: last modification time (as time_t)
name:  file basename
path:  file absolute path
size:  file size in bytes
type:  file type
user:  user name

CLI Examples:

salt '*' file.find / type=f name=\*.bak size=+10m
salt '*' file.find /var mtime=+30d size=+10m print=path,size,mtime
salt '*' file.find /var/log name=\*.[0-9] mtime=+30d size=+10m delete

salt.modules.file.get_diff(minionfile, masterfile, env='base')

Return unified diff of file compared to file on master

CLI Example:

salt \* file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc

salt.modules.file.get_gid(path)

Return the id of the group that owns a given file

CLI Example:

salt '*' file.get_gid /etc/passwd

salt.modules.file.get_group(path)

Return the group that owns a given file

CLI Example:

salt '*' file.get_group /etc/passwd

salt.modules.file.get_hash(path, form='md5', chunk_size=4096)

Get the hash sum of a file

This is better than get_sum for the following reasons:

• It does not read the entire file into memory.

• It does not return a string on error. The returned value of

get_sum cannot really be trusted since it is vulnerable to collisions: get_sum(..., 'xyz') == 'Hash xyz not supported'

CLI Example:

salt '*' file.get_hash /etc/shadow

salt.modules.file.get_managed(name, template, source, source_hash, user, group, mode, env, context, defaults, **kwargs)

Return the managed file data for file.managed

CLI Example:

salt '*' file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' base None None

salt.modules.file.get_mode(path)

Return the mode of a file

CLI Example:

salt '*' file.get_mode /etc/passwd

salt.modules.file.get_selinux_context(path)

Get an SELinux context from a given path

CLI Example:

salt '*' file.get_selinux_context /etc/hosts

salt.modules.file.get_sum(path, form='md5')

Return the sum for the given file, default is md5, sha1, sha224, sha256, sha384, sha512 are supported

CLI Example:

salt '*' file.get_sum /etc/passwd sha512

salt.modules.file.get_uid(path)

Return the id of the user that owns a given file

CLI Example:

salt '*' file.get_uid /etc/passwd

salt.modules.file.get_user(path)

Return the user that owns a given file

CLI Example:

salt '*' file.get_user /etc/passwd

salt.modules.file.gid_to_group(gid)

Convert the group id to the group name on this system

CLI Example:

salt '*' file.gid_to_group 0

salt.modules.file.group_to_gid(group)

Convert the group to the gid on this system

CLI Example:

salt '*' file.group_to_gid root

salt.modules.file.makedirs(path, user=None, group=None, mode=None)

Ensure that the directory containing this path is available.

CLI Example:

salt '*' file.makedirs /opt/code

salt.modules.file.makedirs_perms(name, user=None, group=None, mode='0755')

Taken and modified from os.makedirs to set user, group and mode for each directory created.

CLI Example:

salt '*' file.makedirs_perms /opt/code

salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, env, backup)

Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary).

CLI Example:

salt '*' file.manage_file /etc/httpd/conf.d/httpd.conf '{}' salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' root root '755' base ''

salt.modules.file.patch(originalfile, patchfile, options='', dry_run=False)

Apply a patch to a file

Equivalent to:

patch <options> <originalfile> <patchfile>

originalfile

The full path to the file or directory to be patched

patchfile

A patch file to apply to originalfile

options

Options to pass to patch.

CLI Example:

salt '*' file.patch /opt/file.txt /tmp/file.txt.patch

New in version 0.10.4.

salt.modules.file.remove(path)

Remove the named file

CLI Example:

salt '*' file.remove /tmp/foo

salt.modules.file.restorecon(path, recursive=False)

Reset the SELinux context on a given path

CLI Example:

salt '*' file.restorecon /home/user/.ssh/authorized_keys

salt.modules.file.sed(path, before, after, limit='', backup='.bak', options='-r -e', flags='g', escape_all=False)

Make a simple edit to a file

Equivalent to:

sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"

path

The full path to the file to be edited

before

A pattern to find in order to replace with after

after

Text that will replace before

limit

'' An initial pattern to search for before searching for before

backup

.bak The file will be backed up before edit with this file extension; WARNING: each time sed/comment/uncomment is called will overwrite this backup

options

-r -e Options to pass to sed

flags

g Flags to modify the sed search; e.g., i for case-insensitve pattern matching

Forward slashes and single quotes will be escaped automatically in the before and after patterns.

CLI Example:

salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'

New in version 0.9.5.

salt.modules.file.set_mode(path, mode)

Set the mode of a file

CLI Example:

salt '*' file.set_mode /etc/passwd 0644

salt.modules.file.set_selinux_context(path, user=None, role=None, type=None, range=None)

Set a specific SELinux label on a given path

CLI Example:

salt '*' file.set_selinux_context path <role> <type> <range>

salt.modules.file.source_list(source, source_hash, env)

Check the source list and return the source to use

CLI Example::

salt '*' file.source_list salt://http/httpd.conf '{hash_type: 'md5', 'hsum': <md5sum>}' base

salt.modules.file.stats(path, hash_type='md5', follow_symlink=False)

Return a dict containing the stats for a given file

CLI Example:

salt '*' file.stats /etc/passwd

salt.modules.file.touch(name, atime=None, mtime=None)

Just like 'nix's "touch" command, create a file if it doesn't exist or simply update the atime and mtime if it already does.

atime:

Access time in Unix epoch time

mtime:

Last modification in Unix epoch time

CLI Example:

salt '*' file.touch /var/log/emptyfile

New in version 0.9.5.

salt.modules.file.uid_to_user(uid)

Convert a uid to a user name

CLI Example:

salt '*' file.uid_to_user 0

salt.modules.file.uncomment(path, regex, char='#', backup='.bak')

Uncomment specified commented lines in a file

path

The full path to the file to be edited

regex

A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading ^ character will be stripped for convenience (for easily switching between comment() and uncomment()).

char

# The character to remove in order to uncomment a line; if a single whitespace character follows the comment it will also be removed

backup

.bak The file will be backed up before edit with this file extension; WARNING: each time sed/comment/uncomment is called will overwrite this backup

CLI Example:

salt '*' file.uncomment /etc/hosts.deny 'ALL: PARANOID'

New in version 0.9.5.

salt.modules.file.user_to_uid(user)

Convert user name to a uid

CLI Example:

salt '*' file.user_to_uid root

salt.modules.freebsdjail

The jail module for FreeBSD

salt.modules.freebsdjail.fstab(jail)

Display contents of a fstab(5) file defined in specified jail's configuration. If no file is defined, return False.

CLI Example:

salt '*' jail.fstab <jail name>

salt.modules.freebsdjail.get_enabled()

Return which jails are set to be run

salt.modules.freebsdjail.is_enabled()

See if jail service is actually enabled on boot

salt.modules.freebsdjail.restart(jail='')

Restart the specified jail or all, if none specified

CLI Example:

salt '*' jail.restart [<jail name>]

salt.modules.freebsdjail.show_config(jail)

Display specified jail's configuration

CLI Example:

salt '*' jail.show_config <jail name>

salt.modules.freebsdjail.start(jail='')

Start the specified jail or all, if none specified

CLI Example:

salt '*' jail.start [<jail name>]

salt.modules.freebsdjail.status(jail)

See if specified jail is currently running

CLI Example:

salt '*' jail.status <jail name>

salt.modules.freebsdjail.stop(jail='')

Stop the specified jail or all, if none specified

CLI Example:

salt '*' jail.stop [<jail name>]

salt.modules.freebsdjail.sysctl()

Dump all jail related kernel states (sysctl)

salt.modules.freebsdkmod

Module to manage FreeBSD kernel modules

salt.modules.freebsdkmod.available()

Return a list of all available kernel modules

CLI Example:

salt '*' kmod.available

salt.modules.freebsdkmod.check_available(mod)

Check to see if the specified kernel module is available

CLI Example:

salt '*' kmod.check_available kvm

salt.modules.freebsdkmod.load(mod)

Load the specified kernel module

CLI Example:

salt '*' kmod.load kvm

salt.modules.freebsdkmod.lsmod()

Return a dict containing information about currently loaded modules

CLI Example:

salt '*' kmod.lsmod

salt.modules.freebsdkmod.remove(mod)

Remove the specified kernel module

CLI Example:

salt '*' kmod.remove kvm

salt.modules.freebsdpkg

Package support for FreeBSD

salt.modules.freebsdpkg.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

salt.modules.freebsdpkg.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.freebsdpkg.file_dict(*packages)

List the files that belong to a package, grouped by package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.freebsdpkg.file_list(*packages)

List the files that belong to a package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.freebsdpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs)

Install the passed package

name

The name of the package to be installed.

refresh

Whether or not to refresh the package database before installing.

fromrepo

Specify a package repository to install from.

Multiple Package Installation Options:

pkgs

A list of packages to install from a software repository. Must be passed as a python list.

CLI Example:

salt '*' pkg.install pkgs='["foo","bar"]'

sources

A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

CLI Example:

salt '*' pkg.install sources='[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]'

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.install <package name>

salt.modules.freebsdpkg.list_pkgs()

List the packages currently installed as a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.freebsdpkg.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.freebsdpkg.purge(name, **kwargs)

Remove a single package with pkg_delete

Returns a list containing the removed packages.

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.freebsdpkg.refresh_db()

Use pkg update to get latest repo.txz when using pkgng, else update the ports tree with portsnap otherwise. If the ports tree does not exist it will be downloaded and set up.

CLI Example:

salt '*' pkg.refresh_db

salt.modules.freebsdpkg.rehash()

Recomputes internal hash table for the PATH variable. Use whenever a new command is created during the current session.

CLI Example:

salt '*' pkg.rehash

salt.modules.freebsdpkg.remove(name=None, pkgs=None, **kwargs)

Remove a single package.

name

None The name of the package to be deleted.

pkgs

None A list of packages to delete. Must be passed as a python list.

CLI Example:

salt '*' pkg.remove pkgs='["foo","bar"]'

Returns a list containing the removed packages.

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.freebsdpkg.search(pkg_name)

Use pkg search if pkg is being used.

CLI Example:

salt '*' pkg.search 'mysql-server'

salt.modules.freebsdpkg.upgrade()

Run pkg upgrade, if pkgng used. Otherwise do nothing

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

salt.modules.freebsdpkg.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

salt.modules.freebsdservice

The service module for FreeBSD

salt.modules.freebsdservice.disable(name, config='/etc/rc.conf', **kwargs)

Disable the named service to start at boot

CLI Example:

salt '*' service.disable <service name>

salt.modules.freebsdservice.disabled(name)

Return True if the named servioce is enabled, false otherwise

CLI Example:

salt '*' service.disabled <service name>

salt.modules.freebsdservice.enable(name, config='/etc/rc.conf', **kwargs)

Enable the named service to start at boot

CLI Example:

salt '*' service.enable <service name>

salt.modules.freebsdservice.enabled(name)

Return True if the named servioce is enabled, false otherwise

CLI Example:

salt '*' service.enabled <service name>

salt.modules.freebsdservice.get_all()

Return a list of all available services

CLI Example:

salt '*' service.get_all

salt.modules.freebsdservice.get_disabled()

Return what services are available but not enabled to start at boot

CLI Example:

salt '*' service.get_disabled

salt.modules.freebsdservice.get_enabled()

Return what services are set to run on boot

CLI Example:

salt '*' service.get_enabled

salt.modules.freebsdservice.reload(name)

Restart the named service

CLI Example:

salt '*' service.reload <service name>

salt.modules.freebsdservice.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.freebsdservice.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.freebsdservice.status(name, sig=None)

Return the status for a service (True or False).

name

Name of service.

sig

None Signature. If sig is passed use as service name instead of name argument.

CLI Example:

salt '*' service.status <service name>

salt.modules.freebsdservice.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.freebsd_sysctl

Module for viewing and modifying sysctl parameters

salt.modules.freebsd_sysctl.assign(name, value)

Assign a single sysctl parameter for this minion

CLI Example:

salt '*' sysctl.assign net.inet.icmp.icmplim 50

salt.modules.freebsd_sysctl.get(name)

Return a single sysctl parameter for this minion

CLI Example:

salt '*' sysctl.get hw.physmem

salt.modules.freebsd_sysctl.persist(name, value, config='/etc/sysctl.conf')

Assign and persist a simple sysctl parameter for this minion

CLI Example:

salt '*' sysctl.persist net.inet.icmp.icmplim 50
salt '*' sysctl.persist coretemp_load NO config=/boot/loader.conf

salt.modules.freebsd_sysctl.show()

Return a list of sysctl parameters for this minion

CLI Example:

salt '*' sysctl.show

salt.modules.gem

Manage ruby gems.

salt.modules.gem.install(gems, ruby=None, runas=None, version=None, rdoc=False, ri=False)

Installs one or several gems.

gems

The gems to install.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

version

None Specify the version to install for the gem. Doesn't play nice with multiple gems at once

rdoc

False Generate RDoc documentation for the gem(s).

False Generate RI documentation for the gem(s).

CLI Example:

salt '*' gem.install vagrant

salt.modules.gem.list(prefix='', ruby=None, runas=None)

List locally installed gems.

prefix :

Only list gems when the name matches this prefix.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

CLI Example:

gem.list

salt.modules.gem.sources_add(source_uri, ruby=None, runas=None)

Add a gem source.

source_uri

The source URI to add.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

CLI Example:

salt '*' gem.sources_add http://rubygems.org/

salt.modules.gem.sources_list(ruby=None, runas=None)

List the configured gem sources.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

CLI Example:

salt '*' gem.sources_list

salt.modules.gem.sources_remove(source_uri, ruby=None, runas=None)

Remove a gem source.

source_uri

The source URI to remove.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

CLI Example:

salt '*' gem.sources_remove http://rubygems.org/

salt.modules.gem.uninstall(gems, ruby=None, runas=None)

Uninstall one or several gems.

gems

The gems to uninstall.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

CLI Example:

salt '*' gem.uninstall vagrant

salt.modules.gem.update(gems, ruby=None, runas=None)

Update one or several gems.

gems

The gems to update.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

CLI Example:

salt '*' gem.update vagrant

salt.modules.gem.update_system(version='', ruby=None, runas=None)

Update rubygems.

version

(newest) The version of rubygems to install.

ruby

None If RVM is installed, the ruby version and gemset to use.

runas

None The user to run gem as.

CLI Example:

salt '*' gem.update_system

salt.modules.gentoolkitmod

Support for Gentoolkit
salt.modules.gentoolkitmod.eclean_dist(destructive=False, package_names=False, size_limit=0, time_limit=0, fetch_restricted=False, exclude_file='/etc/eclean/distfiles.exclude'): Clean obsolete portage sources; destructive

Only keep minimum for reinstallation

package_names

Protect all versions of installed packages. Only meaningful if used with destructive=True

size_limit <size>

Don't delete distfiles bigger than <size>. <size> is a size specification: "10M" is "ten megabytes", "200K" is "two hundreds kilobytes", etc. Units are: G, M, K and B.

time_limit <time>

Don't delete distfiles files modified since <time> <time> is an amount of time: "1y" is "one year", "2w" is "two weeks", etc. Units are: y (years), m (months), w (weeks), d (days) and h (hours).

fetch_restricted

Protect fetch-restricted files. Only meaningful if used with destructive=True

exclude_file

Path to exclusion file. Default is /etc/eclean/distfiles.exclude This is the same default eclean-dist uses. Use None if this file exists and you want to ignore.

Return a dict containing the cleaned, saved, and deprecated dists:

{'cleaned': {<dist file>: <size>},
 'deprecated': {<package>: <dist file>},
 'saved': {<package>: <dist file>},
 'total_cleaned': <size>}

CLI Example::

salt '*' gentoolkit.eclean_dist destructive=True

salt.modules.gentoolkitmod.eclean_pkg(destructive=False, package_names=False, time_limit=0, exclude_file='/etc/eclean/packages.exclude'): Clean obsolete binary packages; destructive

Only keep minimum for reinstallation

package_names

Protect all versions of installed packages. Only meaningful if used with destructive=True

time_limit <time>

Don't delete distfiles files modified since <time> <time> is an amount of time: "1y" is "one year", "2w" is "two weeks", etc. Units are: y (years), m (months), w (weeks), d (days) and h (hours).

exclude_file

Path to exclusion file. Default is /etc/eclean/packages.exclude This is the same default eclean-pkg uses. Use None if this file exists and you want to ignore.

Return a dict containing the cleaned binary packages:

{'cleaned': {<dist file>: <size>},
 'total_cleaned': <size>}

CLI Example::

salt '*' gentoolkit.eclean_pkg destructive=True

salt.modules.gentoolkitmod.glsa_check_list(glsa_list): List the status of Gentoo Linux Security Advisories; glsa_list

can contain an arbitrary number of GLSA ids, filenames containing GLSAs or the special identifiers 'all' and 'affected'

Returns a dict containing glsa ids with a description, status, and CVEs:

{<glsa id>: {'description': <glsa description>,
    'status': <glsa status>,
    'CVEs': [<list of CVEs>]}}

CLI Example:

salt '*' gentoolkit.glsa_check_list 'affected'

salt.modules.gentoolkitmod.revdep_rebuild(lib=None)

Fix up broken reverse dependencies

lib

Search for reverse dependencies for a particular library rather than every library on the system. It can be a full path to a library or basic regular expression.

CLI Example:

salt '*' gentoolkit.revdep_rebuild

salt.modules.gentoo_service

Top level package command wrapper, used to translate the os detected by the grains to the correct service manager

salt.modules.gentoo_service.disable(name, **kwargs)

Disable the named service to start at boot

CLI Example:

salt '*' service.disable <service name>

salt.modules.gentoo_service.disabled(name)

Return True if the named servioce is enabled, false otherwise

CLI Example:

salt '*' service.disabled <service name>

salt.modules.gentoo_service.enable(name, **kwargs)

Enable the named service to start at boot

CLI Example:

salt '*' service.enable <service name>

salt.modules.gentoo_service.enabled(name)

Return True if the named servioce is enabled, false otherwise

CLI Example:

salt '*' service.enabled <service name>

salt.modules.gentoo_service.get_all()

Return all available boot services

CLI Example:

salt '*' service.get_all

salt.modules.gentoo_service.get_disabled()

Return a set of services that are installed but disabled

CLI Example:

salt '*' service.get_disabled

salt.modules.gentoo_service.get_enabled()

Return a list of service that are enabled on boot

CLI Example:

salt '*' service.get_enabled

salt.modules.gentoo_service.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.gentoo_service.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.gentoo_service.status(name, sig=None)

Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps

CLI Example:

salt '*' service.status <service name> [service signature]

salt.modules.gentoo_service.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.git

Support for the Git SCM

salt.modules.git.archive(cwd, output, rev='HEAD', fmt=None, prefix=None, user=None)

Export a tarball from the repository

cwd

The path to the Git repository

output

The path to the archive tarball

rev: HEAD

The revision to create an archive from

fmt: None

Format of the resulting archive, zip and tar are commonly used

prefix

None Prepend <prefix>/ to every filename in the archive

user

None Run git as a user other than what the minion runs as

If prefix is not specified it defaults to the basename of the repo directory.

CLI Example:

salt '*' git.archive /path/to/repo /path/to/archive.tar.gz

salt.modules.git.checkout(cwd, rev, force=False, opts=None, user=None)

Checkout a given revision

cwd

The path to the Git repository

rev

The remote branch or revision to checkout

force

False Force a checkout even if there might be overwritten changes

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Examples:

salt '*' git.checkout /path/to/repo somebranch user=jeff

salt '*' git.checkout /path/to/repo opts='testbranch -- conf/file1 file2'

salt '*' git.checkout /path/to/repo rev=origin/mybranch opts=--track

salt.modules.git.clone(cwd, repository, opts=None, user=None)

Clone a new repository

cwd

The path to the Git repository

repository

The git uri of the repository

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.clone /path/to/repo git://github.com/saltstack/salt.git

salt '*' git.clone /path/to/repo.git\
        git://github.com/saltstack/salt.git '--bare --origin github'

salt.modules.git.describe(cwd, rev='HEAD', user=None)

Returns the git describe string (or the SHA hash if there are no tags) for the given revision

cwd

The path to the Git repository

rev: HEAD

The revision to describe

user

None Run git as a user other than what the minion runs as

CLI Examples:

salt '*' git.describe /path/to/repo

salt '*' git.describe /path/to/repo develop

salt.modules.git.fetch(cwd, opts=None, user=None)

Perform a fetch on the given repository

cwd

The path to the Git repository

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.fetch /path/to/repo '--all'

salt '*' git.fetch cwd=/path/to/repo opts='--all' user=johnny

salt.modules.git.init(cwd, opts=None, user=None)

Initialize a new git repository

cwd

The path to the Git repository

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.init /path/to/repo.git opts='--bare'

salt.modules.git.merge(cwd, branch='@{upstream}', opts=None, user=None)

Merge a given branch

cwd

The path to the Git repository

branch

@{upstream} The remote branch or revision to merge into the current branch

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.fetch /path/to/repo
salt '*' git.merge /path/to/repo @{upstream}

salt.modules.git.pull(cwd, opts=None, user=None)

Perform a pull on the given repository

cwd

The path to the Git repository

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.pull /path/to/repo opts='--rebase origin master'

salt.modules.git.rebase(cwd, rev='master', opts=None, user=None)

Rebase the current branch

cwd

The path to the Git repository

rev

master The revision to rebase onto the current branch

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.rebase /path/to/repo master

That is the same as: git rebase master

salt.modules.git.revision(cwd, rev='HEAD', short=False, user=None)

Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc)

cwd

The path to the Git repository

rev: HEAD

The revision

short: False

Return an abbreviated SHA1 git hash

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.revision /path/to/repo mybranch

salt.modules.git.submodule(cwd, init=True, opts=None, user=None)

Initialize git submodules

cwd

The path to the Git repository

init

True Ensure that new submodules are initialized

opts

None Any additional options to add to the command line

user

None Run git as a user other than what the minion runs as

CLI Example:

salt '*' git.submodule /path/to/repo.git/sub/repo

salt.modules.glance

Module for handling openstack glance calls.

optdepends

• glanceclient Python adapter

configuration

This module is not usable until the following are specified either in a pillar or in the minion's config file:

keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.insecure: False   #(optional)
keystone.auth_url: 'http://127.0.0.1:5000/v2.0/'

salt.modules.glance.image_create(**kwargs)

Create an image (glance image-create)

CLI Example:

salt '*' glance.image_create name=f16-jeos is_public=true                  disk_format=qcow2 container_format=ovf                  copy_from=http://berrange.fedorapeople.org/images/2012-02-29/f16-x86_64-openstack-sda.qcow2

For all possible values, run:

glance help image-create

salt.modules.glance.image_delete(id=None, name=None)

Delete an image (glance image-delete)

CLI Examples:

salt '*' glance.image_delete c2eb2eb0-53e1-4a80-b990-8ec887eae7df
salt '*' glance.image_delete id=c2eb2eb0-53e1-4a80-b990-8ec887eae7df
salt '*' glance.image_delete name=f16-jeos

salt.modules.glance.image_list(id=None)

Return a list of available images (glance image-list)

CLI Example:

salt '*' glance.image_list

salt.modules.glance.image_show(id=None, name=None)

Return details about a specific image (glance image-show)

CLI Example:

salt '*' glance.image_get

salt.modules.grains

Control aspects of the grains data

salt.modules.grains.item(*args, **kargs)

Return a single component of the grains data

CLI Example:

salt '*' grains.item os

Return multiple components of the grains data

CLI Example:

salt '*' grains.item os osrelease oscodename

Sanitized CLI Example:

salt '*' grains.item host sanitize=True

salt.modules.grains.items(sanitize=False)

Return the grains data

CLI Example:

salt '*' grains.items

Sanitized CLI output:

salt '*' grains.items sanitize=True

salt.modules.grains.ls()

Return a list of all available grains

CLI Example:

salt '*' grains.ls

salt.modules.grains.setval(key, val)

Set a grains value in the grains config file

CLI Example:

salt '*' grains.setval key val

salt.modules.groupadd

Manage groups on Linux and OpenBSD

salt.modules.groupadd.add(name, gid=None, system=False)

Add the specified group

CLI Example:

salt '*' group.add foo 3456

salt.modules.groupadd.chgid(name, gid)

Change the gid for a named group

CLI Example:

salt '*' group.chgid foo 4376

salt.modules.groupadd.delete(name)

Remove the named group

CLI Example:

salt '*' group.delete foo

salt.modules.groupadd.getent()

Return info on all groups

CLI Example:

salt '*' group.getent

salt.modules.groupadd.info(name)

Return information about a group

CLI Example:

salt '*' group.info foo

salt.modules.grub_legacy

Support for GRUB Legacy

salt.modules.grub_legacy.conf()

Parse GRUB conf file

CLI Example:

salt '*' grub.conf

salt.modules.grub_legacy.version()

Return server version from grub --version

CLI Example:

salt '*' grub.version

salt.modules.hg

Support for the Mercurial SCM

salt.modules.hg.archive(cwd, output, rev='tip', fmt=None, prefix=None, user=None)

Export a tarball from the repository

cwd

The path to the Mercurial repository

output

The path to the archive tarball

rev: tip

The revision to create an archive from

fmt: None

Format of the resulting archive. Mercurial supports: tar, tbz2, tgz, zip, uzip, and files formats.

prefix

None Prepend <prefix>/ to every filename in the archive

user

None Run hg as a user other than what the minion runs as

If prefix is not specified it defaults to the basename of the repo directory.

CLI Example:

salt '*' hg.archive /path/to/repo output=/tmp/archive.tgz fmt=tgz

salt.modules.hg.clone(cwd, repository, opts=None, user=None)

Clone a new repository

cwd

The path to the Mercurial repository

repository

The hg uri of the repository

opts

None Any additional options to add to the command line

user

None Run hg as a user other than what the minion runs as

CLI Example:

salt '*' hg.clone /path/to/repo https://bitbucket.org/birkenfeld/sphinx

salt.modules.hg.describe(cwd, rev='tip', user=None)

Mimick git describe and return an identifier for the given revision

cwd

The path to the Mercurial repository

rev: tip

The path to the archive tarball

user

None Run hg as a user other than what the minion runs as

CLI Example:

salt '*' hg.describe /path/to/repo

salt.modules.hg.pull(cwd, opts=None, user=None)

Perform a pull on the given repository

cwd

The path to the Mercurial repository

opts

None Any additional options to add to the command line

user

None Run hg as a user other than what the minion runs as

CLI Example:

salt '*' hg.pull /path/to/repo '-u'

salt.modules.hg.revision(cwd, rev='tip', short=False, user=None)

Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc)

cwd

The path to the Mercurial repository

rev: tip

The revision

short: False

Return an abbreviated commit hash

user

None Run hg as a user other than what the minion runs as

CLI Example:

salt '*' hg.revision /path/to/repo mybranch

salt.modules.hg.update(cwd, rev, force=False, user=None)

Update to a given revision

cwd

The path to the Mercurial repository

rev

The revision to update to

force

False Force an update

user

None Run hg as a user other than what the minion runs as

CLI Example:

salt devserver1 hg.update /path/to/repo somebranch

salt.modules.hosts

Manage the information in the hosts file

salt.modules.hosts.add_host(ip, alias)

Add a host to an existing entry, if the entry is not in place then create it with the given host

CLI Example:

salt '*' hosts.add_host <ip> <alias>

salt.modules.hosts.get_alias(ip)

Return the list of aliases associated with an ip

CLI Example:

salt '*' hosts.get_alias <ip addr>

salt.modules.hosts.get_ip(host)

Return the ip associated with the named host

CLI Example:

salt '*' hosts.get_ip <hostname>

salt.modules.hosts.has_pair(ip, alias)

Return true if the alias is set

CLI Example:

salt '*' hosts.has_pair <ip> <alias>

salt.modules.hosts.list_hosts()

Return the hosts found in the hosts file in this format:

{'<ip addr>': ['alias1', 'alias2', ...]}

CLI Example:

salt '*' hosts.list_hosts

salt.modules.hosts.rm_host(ip, alias)

Remove a host entry from the hosts file

CLI Example:

salt '*' hosts.rm_host <ip> <alias>

salt.modules.hosts.set_host(ip, alias)

Set the host entry in the hosts file for the given ip, this will overwrite any previous entry for the given ip

CLI Example:

salt '*' hosts.set_host <ip> <alias>

salt.modules.iptables

Support for iptables
salt.modules.iptables.append(table='filter', chain=None, rule=None): Append a rule to the specified table/chain.; This function accepts a rule in a standard iptables command format,

starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it.

CLI Example:

salt '*' iptables.append filter INPUT '-m state --state RELATED,ESTABLISHED -j ACCEPT'

salt.modules.iptables.delete(table, chain, position=None, rule=None)

Delete a rule from the specified table/chain, specifying either the rule

in its entirety, or the rule's position in the chain.

This function accepts a rule in a standard iptables command format,

starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it.

CLI Examples:

salt '*' iptables.delete filter INPUT position=3
salt '*' iptables.delete filter INPUT rule='-m state --state RELATED,ESTABLISHED -j ACCEPT'

salt.modules.iptables.flush(table='filter')

Flush all chains in the specified table.

CLI Example:

salt '*' iptables.flush filter

salt.modules.iptables.get_policy(table='filter', chain=None)

Return the current policy for the specified table/chain

CLI Example:

salt '*' iptables.get_policy filter INPUT

salt.modules.iptables.get_rules()

Return a data structure of the current, in-memory rules

CLI Example:

salt '*' iptables.get_rules

salt.modules.iptables.get_saved_policy(table='filter', chain=None, conf_file=None)

Return the current policy for the specified table/chain

CLI Examples:

salt '*' iptables.get_saved_policy filter INPUT
salt '*' iptables.get_saved_policy filter INPUT conf_file=/etc/iptables.saved

salt.modules.iptables.get_saved_rules(conf_file=None)

Return a data structure of the rules in the conf file

CLI Example:

salt '*' iptables.get_saved_rules

salt.modules.iptables.insert(table='filter', chain=None, position=None, rule=None)

Insert a rule into the specified table/chain, at the specified position.

This function accepts a rule in a standard iptables command format,

starting with the chain. Trying to force users to adapt to a new method of creating rules would be irritating at best, and we already have a parser that can handle it.

CLI Examples:

salt '*' iptables.insert filter INPUT rule='-m state --state RELATED,ESTABLISHED -j ACCEPT'
salt '*' iptables.insert filter INPUT position=3 rule='-m state --state RELATED,ESTABLISHED -j ACCEPT'

salt.modules.iptables.save(filename=None)

Save the current in-memory rules to disk

CLI Example:

salt '*' iptables.save /etc/sysconfig/iptables

salt.modules.iptables.set_policy(table='filter', chain=None, policy=None)

Set the current policy for the specified table/chain

CLI Example:

salt '*' iptables.set_policy filter INPUT ACCEPT

salt.modules.iptables.version()

Return version from iptables --version

CLI Example:

salt '*' iptables.version

salt.modules.keyboard

Module for managing keyboards on posix-like systems.

salt.modules.keyboard.get_sys()

Get current system keyboard setting

CLI Example:

salt '*' keyboard.get_sys

salt.modules.keyboard.get_x()

Get current X keyboard setting

CLI Example:

salt '*' keyboard.get_x

salt.modules.keyboard.set_sys(layout)

Set current system keyboard setting

CLI Example:

salt '*' keyboard.set_sys dvorak

salt.modules.keyboard.set_x(layout)

Set current X keyboard setting

CLI Example:

salt '*' keyboard.set_x dvorak

salt.modules.keystone

Module for handling openstack keystone calls.

optdepends

• keystoneclient Python adapter

configuration

This module is not usable until the following are specified either in a pillar or in the minion's config file:

keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.insecure: False   #(optional)
keystone.auth_url: 'http://127.0.0.1:5000/v2.0/'

OR (for token based authentication)

keystone.token: 'ADMIN'
keystone.endpoint: 'http://127.0.0.1:35357/v2.0'

salt.modules.keystone.auth()

Set up keystone credentials

Only intended to be used within Keystone-enabled modules

salt.modules.keystone.ec2_credentials_get(id=None, name=None, access=None)

Return ec2_credentials for a user (keystone ec2-credentials-get)

CLI Examples:

salt '*' keystone.ec2_credentials_get c965f79c4f864eaaa9c3b41904e67082 access=722787eb540849158668370dc627ec5f
salt '*' keystone.ec2_credentials_get id=c965f79c4f864eaaa9c3b41904e67082 access=722787eb540849158668370dc627ec5f
salt '*' keystone.ec2_credentials_get name=nova access=722787eb540849158668370dc627ec5f

salt.modules.keystone.ec2_credentials_list(id=None, name=None)

Return a list of ec2_credentials for a specific user (keystone ec2-credentials-list)

CLI Examples:

salt '*' keystone.ec2_credentials_list 298ce377245c4ec9b70e1c639c89e654
salt '*' keystone.ec2_credentials_list id=298ce377245c4ec9b70e1c639c89e654
salt '*' keystone.ec2_credentials_list name=jack

salt.modules.keystone.endpoint_get(service)

Return a specific endpoint (keystone endpoint-get)

CLI Example:

salt '*' keystone.endpoint_get ec2

salt.modules.keystone.endpoint_list()

Return a list of available endpoints (keystone endpoints-list)

CLI Example:

salt '*' keystone.endpoint_list

salt.modules.keystone.role_get(id=None, name=None)

Return a specific roles (keystone role-get)

CLI Examples:

salt '*' keystone.role_get c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.role_get id=c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.role_get name=nova

salt.modules.keystone.role_list()

Return a list of available roles (keystone role-list)

CLI Example:

salt '*' keystone.role_list

salt.modules.keystone.service_get(id=None, name=None)

Return a specific services (keystone service-get)

CLI Examples:

salt '*' keystone.service_get c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.service_get id=c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.service_get name=nova

salt.modules.keystone.service_list()

Return a list of available services (keystone services-list)

CLI Example:

salt '*' keystone.service_list

salt.modules.keystone.tenant_get(id=None, name=None)

Return a specific tenants (keystone tenant-get)

CLI Examples:

salt '*' keystone.tenant_get c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.tenant_get id=c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.tenant_get name=nova

salt.modules.keystone.tenant_list()

Return a list of available tenants (keystone tenants-list)

CLI Example:

salt '*' keystone.tenant_list

salt.modules.keystone.token_get()

Return the configured tokens (keystone token-get)

CLI Example:

salt '*' keystone.token_get c965f79c4f864eaaa9c3b41904e67082

salt.modules.keystone.user_create(name, password, email, tenant_id=None, enabled=True)

Create a user (keystone user-create)

CLI Examples:

salt '*' keystone.user_create name=jack password=zero email=jack@halloweentown.org tenant_id=a28a7b5a999a455f84b1f5210264375e enabled=True

salt.modules.keystone.user_delete(id=None, name=None)

Delete a user (keystone user-delete)

CLI Examples:

salt '*' keystone.user_delete c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.user_delete id=c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.user_delete name=nova

salt.modules.keystone.user_get(id=None, name=None)

Return a specific users (keystone user-get)

CLI Examples:

salt '*' keystone.user_get c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.user_get id=c965f79c4f864eaaa9c3b41904e67082
salt '*' keystone.user_get name=nova

salt.modules.keystone.user_list()

Return a list of available users (keystone user-list)

CLI Example:

salt '*' keystone.user_list

salt.modules.keystone.user_password_update(id=None, name=None, password=None)

Update a user's password (keystone user-password-update)

CLI Examples:

salt '*' keystone.user_delete c965f79c4f864eaaa9c3b41904e67082 password=12345
salt '*' keystone.user_delete id=c965f79c4f864eaaa9c3b41904e67082 password=12345
salt '*' keystone.user_delete name=nova pasword=12345

salt.modules.keystone.user_role_list(user_id=None, tenant_id=None, user_name=None, tenant_name=None)

Return a list of available user_roles (keystone user_roles-list)

CLI Examples:

salt '*' keystone.user_role_list             user_id=298ce377245c4ec9b70e1c639c89e654             tenant_id=7167a092ece84bae8cead4bf9d15bb3b
salt '*' keystone.user_role_list user_name=admin tenant_name=admin

salt.modules.keystone.user_update(id=None, name=None, email=None, enabled=None)

Update a user's information (keystone user-update) The following fields may be updated: name, email, enabled. Because the name is one of the fields, a valid user id is required.

CLI Examples:

salt '*' keystone.user_update id=c965f79c4f864eaaa9c3b41904e67082 name=newname
salt '*' keystone.user_update c965f79c4f864eaaa9c3b41904e67082 name=newname email=newemail@domain.com

salt.modules.kmod

Module to manage Linux kernel modules

salt.modules.kmod.available()

Return a list of all available kernel modules

CLI Example:

salt '*' kmod.available

salt.modules.kmod.check_available(mod)

Check to see if the specified kernel module is available

CLI Example:

salt '*' kmod.check_available kvm

salt.modules.kmod.load(mod, persist=False)

Load the specified kernel module

mod

Name of module to add

persist

Write module to /etc/modules to make it load on system reboot

CLI Example:

salt '*' kmod.load kvm

salt.modules.kmod.lsmod()

Return a dict containing information about currently loaded modules

CLI Example:

salt '*' kmod.lsmod

salt.modules.kmod.mod_list(only_persist=False)

Return a list of the loaded module names

CLI Example:

salt '*' kmod.mod_list

salt.modules.kmod.remove(mod, persist=False, comment=True)

Remove the specified kernel module

mod

Name of module to remove

persist

Also remove module from /etc/modules

comment

If persist is set don't remove line from /etc/modules but only comment it

CLI Example:

salt '*' kmod.remove kvm

salt.modules.kvm_hyper

Provide the hyper module for kvm hypervisors. This is the interface used to interact with kvm on behalf of the salt-virt interface

depends

• libvirt Python module

salt.modules.kvm_hyper.freecpu()

Return an int representing the number of unallocated cpus on this hypervisor

CLI Example:

salt '*' hyper.freecpu

salt.modules.kvm_hyper.freemem()

Return an int representing the amount of memory that has not been given to virtual machines on this node

CLI Example:

salt '*' hyper.freemem

salt.modules.kvm_hyper.get_conf(name)

Returns the xml for a given vm

CLI Example:

salt '*' hyper.get_conf <vm name>

salt.modules.kvm_hyper.get_disks(name)

Return the disks of a named virt

CLI Example:

salt '*' hyper.get_disks <vm name>

salt.modules.kvm_hyper.halt(name)

Hard power down a virtual machine

CLI Example:

salt '*' hyper.halt webserver

salt.modules.kvm_hyper.hyper_info()

Return a dict with information about this hypervisor

CLI Example:

salt '*' hyper.hyper_info

salt.modules.kvm_hyper.hyper_type()

Return that type of hypervisor this is

CLI Example:

salt '*' hyper.hyper_type

salt.modules.kvm_hyper.init(name, cpus, mem, image, storage_dir, network=None, desc='', opts=None)

Create a KVM virtual machine based on these passed options, the virtual machine will be started upon creation

CLI Example:

salt '*' hyper.init webserver 2 2048 salt://fedora/f16.img:virt /srv/vm/images

salt.modules.kvm_hyper.list_virts()

Return a list of virtual machine names on the minion

CLI Example:

salt '*' hyper.list_virts

salt.modules.kvm_hyper.pause(name)

Pause the named virtual machine

CLI Example:

salt '*' hyper.pause webserver

salt.modules.kvm_hyper.purge(name)

Hard power down and purge a virtual machine, this will destroy a vm and all associated vm data

CLI Example:

salt '*' hyper.purge webserver

salt.modules.kvm_hyper.resume(name)

Resume the named virtual machine

CLI Example:

salt '*' hyper.resume webserver

salt.modules.kvm_hyper.set_autostart(name, state='on')

Set the named virtual machine to autostart when the hypervisor boots

CLI Example:

salt '*' hyper.set_autostart webserver

salt.modules.kvm_hyper.start(config)

Start an already defined virtual machine that has been shut down

CLI Example:

salt '*' hyper.start webserver

salt.modules.kvm_hyper.virt_info()

Return detailed information about the vms on this hyper in a dict:

{'cpu': <int>,
'maxMem': <int>,
'mem': <int>,
'state': '<state>',
'cputime' <int>}

CLI Example:

salt '*' hyper.virt_info

salt.modules.launchctl

Module for the management of MacOS systems that use launchd/launchctl

depends

• plistlib Python module

salt.modules.launchctl.get_all()

Return all installed services

CLI Example:

salt '*' service.get_all

salt.modules.launchctl.get_launchctl_data(job_label, runas=None)

salt.modules.launchctl.restart(job_label, runas=None)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.launchctl.start(job_label, runas=None)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.launchctl.status(job_label, runas=None)

Return the status for a service, returns a bool whether the service is running.

CLI Example:

salt '*' service.status <service name>

salt.modules.launchctl.stop(job_label, runas=None)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.layman

Support for Layman

salt.modules.layman.add(overlay)

Add the given overlay from the caced remote list to your locally installed overlays. Specify 'ALL' to add all overlays from the remote list.

Return a list of the new overlay(s) added:

CLI Example:

salt '*' layman.add <overlay name>

salt.modules.layman.delete(overlay)

Remove the given overlay from the your locally installed overlays. Specify 'ALL' to remove all overlays.

Return a list of the overlays(s) that were removed:

CLI Example:

salt '*' layman.delete <overlay name>

salt.modules.layman.list_local()

List the locally installed overlays.

Return a list of installed overlays:

CLI Example:

salt '*' layman.list_local

salt.modules.layman.sync(overlay='ALL')

Update the specified overlay. Use 'ALL' to synchronize all overlays. This is the default if no overlay is specified.

overlay

Name of the overlay to sync. (Defaults to 'ALL')

CLI Example:

salt '*' layman.sync

salt.modules.ldapmod

Module to provide LDAP commands via salt.

depends

• ldap Python module

configuration

In order to connect to LDAP, certain configuration is required in the minion config on the LDAP server. The minimum configuration items that must be set are:

ldap.basedn: dc=acme,dc=com (example values, adjust to suit)

If your LDAP server requires authentication then you must also set:

ldap.binddn: admin
ldap.bindpw: password

In addition, the following optional values may be set:

ldap.server: localhost (default=localhost, see warning below)
ldap.port: 389 (default=389, standard port)
ldap.tls: False (default=False, no TLS)
ldap.scope: 2 (default=2, ldap.SCOPE_SUBTREE)
ldap.attrs: [saltAttr] (default=None, return all attributes)

Warning

At the moment this module only recommends connection to LDAP services listening on 'localhost'. This is deliberate to avoid the potentially dangerous situation of multiple minions sending identical update commands to the same LDAP server. It's easy enough to override this behaviour, but badness may ensue - you have been warned.

salt.modules.ldapmod.search(filter, dn=None, scope=None, attrs=None, **kwargs)

Run an arbitrary LDAP query and return the results.

CLI Examples:

salt 'ldaphost' ldap.search "filter=cn=myhost"

returns:

'myhost': { 'count': 1,
        'results': [['cn=myhost,ou=hosts,o=acme,c=gb',
            {'saltKeyValue': ['ntpserver=ntp.acme.local', 'foo=myfoo'],
             'saltState': ['foo', 'bar']}]],
        'time': {'human': '1.2ms', 'raw': '0.00123'}}}

Search and connection options can be overridden by specifying the relevant option as key=value pairs, for example:

salt 'ldaphost' ldap.search filter=cn=myhost dn=ou=hosts,o=acme,c=gb
scope=1 attrs='' server='localhost' port='7393' tls=True bindpw='ssh'

salt.modules.linux_acl

Support for Linux File Access Control Lists

salt.modules.linux_acl.delfacl(acl_type, acl_name, *args)

Remove specific FACL from the specified file(s) CLI Examples:

salt '*' acl.delfacl user myuser /tmp/house/kitchen
salt '*' acl.delfacl default:group mygroup /tmp/house/kitchen
salt '*' acl.delfacl d:u myuser /tmp/house/kitchen
salt '*' acl.delfacl g myuser /tmp/house/kitchen /tmp/house/livingroom

salt.modules.linux_acl.getfacl(*args)

Return (extremely verbose) map of FACLs on specified file(s) CLI Examples:

salt '*' acl.getfacl /tmp/house/kitchen
salt '*' acl.getfacl /tmp/house/kitchen /tmp/house/livingroom

salt.modules.linux_acl.modfacl(acl_type, acl_name, perms, *args)

Add or modify a FACL for the specified file(s) CLI Examples:

salt '*' acl.addfacl user myuser rwx /tmp/house/kitchen
salt '*' acl.addfacl default:group mygroup rx /tmp/house/kitchen
salt '*' acl.addfacl d:u myuser 7 /tmp/house/kitchen
salt '*' acl.addfacl g mygroup 0 /tmp/house/kitchen /tmp/house/livingroom

salt.modules.linux_acl.version()

Return facl version from getfacl --version

CLI Example:

salt '*' acl.version

salt.modules.linux_acl.wipefacls(*args)

Remove all FACLs from the specified file(s) CLI Examples:

salt '*' acl.wipefacls /tmp/house/kitchen
salt '*' acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom

salt.modules.linux_lvm

Support for Linux LVM2

salt.modules.linux_lvm.fullversion()

Return all version info from lvm version

CLI Example:

salt '*' lvm.fullversion

salt.modules.linux_lvm.lvcreate(lvname, vgname, size=None, extents=None, pv='')

Create a new logical volume, with option for which physical volume to be used

CLI Examples:

salt '*' lvm.lvcreate new_volume_name vg_name size=10G
salt '*' lvm.lvcreate new_volume_name vg_name extents=100 /dev/sdb

salt.modules.linux_lvm.lvdisplay(lvname='')

Return information about the logical volume(s) CLI Examples:

salt '*' lvm.lvdisplay
salt '*' lvm.lvdisplay /dev/vg_myserver/root

salt.modules.linux_lvm.lvremove(lvname, vgname)

Remove a given existing logical volume from a named existing volume group

CLI Example:

salt '*' lvm.lvremove lvname vgname force=True

salt.modules.linux_lvm.pvcreate(devices, **kwargs)

Set a physical device to be used as an LVM physical volume

CLI Examples:

salt mymachine lvm.pvcreate /dev/sdb1,/dev/sdb2
salt mymachine lvm.pvcreate /dev/sdb1 dataalignmentoffset=7s

salt.modules.linux_lvm.pvdisplay(pvname='')

Return information about the physical volume(s) CLI Examples:

salt '*' lvm.pvdisplay
salt '*' lvm.pvdisplay /dev/md0

salt.modules.linux_lvm.version()

Return LVM version from lvm version

CLI Example:

salt '*' lvm.version

salt.modules.linux_lvm.vgcreate(vgname, devices, **kwargs)

Create an LVM volume group

CLI Examples:

salt mymachine lvm.vgcreate my_vg /dev/sdb1,/dev/sdb2
salt mymachine lvm.vgcreate my_vg /dev/sdb1 clustered=y

salt.modules.linux_lvm.vgdisplay(vgname='')

Return information about the volume group(s) CLI Examples:

salt '*' lvm.vgdisplay
salt '*' lvm.vgdisplay nova-volumes

salt.modules.linux_lvm.vgremove(vgname)

Remove an LVM volume group

CLI Examples:

salt mymachine lvm.vgremove vgname
salt mymachine lvm.vgremove vgname force=True

salt.modules.linux_sysctl

Module for viewing and modifying sysctl parameters

salt.modules.linux_sysctl.assign(name, value)

Assign a single sysctl parameter for this minion

CLI Example:

salt '*' sysctl.assign net.ipv4.ip_forward 1

salt.modules.linux_sysctl.get(name)

Return a single sysctl parameter for this minion

CLI Example:

salt '*' sysctl.get net.ipv4.ip_forward

salt.modules.linux_sysctl.persist(name, value, config='/etc/sysctl.conf')

Assign and persist a simple sysctl parameter for this minion

CLI Example:

salt '*' sysctl.persist net.ipv4.ip_forward 1

salt.modules.linux_sysctl.show()

Return a list of sysctl parameters for this minion

CLI Example:

salt '*' sysctl.show

salt.modules.locale

Module for managing locales on posix-like systems.

salt.modules.locale.get_locale()

Get the current system locale

CLI Example:

salt '*' locale.get_locale

salt.modules.locale.list_avail()

Lists available (compiled) locales

CLI Example:

salt '*' locale.list_avail

salt.modules.locale.set_locale(locale)

Sets the current system locale

CLI Example:

salt '*' locale.set_locale 'en_US.UTF-8'

salt.modules.makeconf

Support for modifying make.conf under Gentoo

salt.modules.makeconf.append_cflags(value)

Add to or create a new CFLAGS in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.append_cflags '\-pipe'

salt.modules.makeconf.append_cxxflags(value)

Add to or create a new CXXFLAGS in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.append_cxxflags '\-pipe'

salt.modules.makeconf.append_emerge_default_opts(value)

Add to or create a new EMERGE_DEFAULT_OPTS in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.append_emerge_default_opts '\-\-jobs'

salt.modules.makeconf.append_gentoo_mirrors(value)

Add to or create a new GENTOO_MIRRORS in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.append_gentoo_mirrors 'http://distfiles.gentoo.org'

salt.modules.makeconf.append_makeopts(value)

Add to or create a new MAKEOPTS in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.append_makeopts '\-j3'

salt.modules.makeconf.append_var(var, value)

Add to or create a new variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.append_var 'LINGUAS' 'en'

salt.modules.makeconf.cflags_contains(value)

Verify if CFLAGS variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.cflags_contains '\-pipe'

salt.modules.makeconf.chost_contains(value)

Verify if CHOST variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.chost_contains 'x86_64-pc-linux-gnu'

salt.modules.makeconf.cxxflags_contains(value)

Verify if CXXFLAGS variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.cxxflags_contains '\-pipe'

salt.modules.makeconf.emerge_default_opts_contains(value)

Verify if EMERGE_DEFAULT_OPTS variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.emerge_default_opts_contains '\-\-jobs'

salt.modules.makeconf.gentoo_mirrors_contains(value)

Verify if GENTOO_MIRRORS variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.gentoo_mirrors_contains 'http://distfiles.gentoo.org'

salt.modules.makeconf.get_cflags()

Get the value of CFLAGS variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_cflags

salt.modules.makeconf.get_chost()

Get the value of CHOST variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_chost

salt.modules.makeconf.get_cxxflags()

Get the value of CXXFLAGS variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_cxxflags

salt.modules.makeconf.get_emerge_default_opts()

Get the value of EMERGE_DEFAULT_OPTS variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_emerge_default_opts

salt.modules.makeconf.get_gentoo_mirrors()

Get the value of GENTOO_MIRRORS variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_gentoo_mirrors

salt.modules.makeconf.get_makeopts()

Get the value of MAKEOPTS variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_makeopts

salt.modules.makeconf.get_sync()

Get the value of SYNC variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_sync

salt.modules.makeconf.get_var(var)

Get the value of a variable in the make.conf

Return the value of the variable or None if the variable is not in the make.conf

CLI Example:

salt '*' makeconf.get_var 'LINGUAS'

salt.modules.makeconf.makeopts_contains(value)

Verify if MAKEOPTS variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.makeopts_contains '\-j3'

salt.modules.makeconf.remove_var(var)

Remove a variable from the make.conf

Return a dict containing the new value for the variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.remove_var 'LINGUAS'

salt.modules.makeconf.set_cflags(value)

Set the CFLAGS variable

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_cflags '\-march=native \-O2 \-pipe'

salt.modules.makeconf.set_chost(value)

Set the CHOST variable

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_chost 'x86_64-pc-linux-gnu'

salt.modules.makeconf.set_cxxflags(value)

Set the CXXFLAGS variable

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_cxxflags '\-march=native \-O2 \-pipe'

salt.modules.makeconf.set_emerge_default_opts(value)

Set the EMERGE_DEFAULT_OPTS variable

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_emerge_default_opts '\-\-jobs'

salt.modules.makeconf.set_gentoo_mirrors(value)

Set the GENTOO_MIRRORS variable

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_gentoo_mirrors 'http://distfiles.gentoo.org'

salt.modules.makeconf.set_makeopts(value)

Set the MAKEOPTS variable

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_makeopts '\-j3'

salt.modules.makeconf.set_sync(value)

Set the SYNC variable

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_sync 'rsync://rsync.namerica.gentoo.org/gentoo-portage'

salt.modules.makeconf.set_var(var, value)

Set a variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.set_var 'LINGUAS' 'en'

salt.modules.makeconf.sync_contains(value)

Verify if SYNC variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.sync_contains 'rsync://rsync.namerica.gentoo.org/gentoo-portage'

salt.modules.makeconf.trim_cflags(value)

Remove a value from CFLAGS variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.trim_cflags '\-pipe'

salt.modules.makeconf.trim_cxxflags(value)

Remove a value from CXXFLAGS variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.trim_cxxflags '\-pipe'

salt.modules.makeconf.trim_emerge_default_opts(value)

Remove a value from EMERGE_DEFAULT_OPTS variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.trim_emerge_default_opts '\-\-jobs'

salt.modules.makeconf.trim_gentoo_mirrors(value)

Remove a value from GENTOO_MIRRORS variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.trim_gentoo_mirrors 'http://distfiles.gentoo.org'

salt.modules.makeconf.trim_makeopts(value)

Remove a value from MAKEOPTS variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.trim_makeopts '\-j3'

salt.modules.makeconf.trim_var(var, value)

Remove a value from a variable in the make.conf

Return a dict containing the new value for variable:

{'<variable>': {'old': '<old-value>',
                'new': '<new-value>'}}

CLI Example:

salt '*' makeconf.trim_var 'LINGUAS' 'en'

salt.modules.makeconf.var_contains(var, value)

Verify if variable contains a value in make.conf

Return True if value is set for var

CLI Example:

salt '*' makeconf.var_contains 'LINGUAS' 'en'

salt.modules.mdadm

Salt module to manage RAID arrays with mdadm

salt.modules.mdadm.detail(device='/dev/md0')

Show detail for a specified RAID device

CLI Example:

salt '*' raid.detail '/dev/md0'

salt.modules.mdadm.list()

List the RAID devices.

CLI Example:

salt '*' raid.list

salt.modules.mongodb

Module to provide MongoDB functionality to Salt

configuration

This module uses PyMongo, and accepts configuration details as parameters as well as configuration settings:

mongodb.host: 'localhost'
mongodb.port: '27017'
mongodb.user: ''
mongodb.password: ''

This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar.

salt.modules.mongodb.db_exists(name, user=None, password=None, host=None, port=None, database='admin')

Checks if a database exists in Mongodb

salt.modules.mongodb.db_list(user=None, password=None, host=None, port=None)

List all Mongodb databases

salt.modules.mongodb.db_remove(name, user=None, password=None, host=None, port=None)

Remove a Mongodb database

salt.modules.mongodb.user_create(name, passwd, user=None, password=None, host=None, port=None, database='admin')

Create a Mongodb user

salt.modules.mongodb.user_exists(name, user=None, password=None, host=None, port=None, database='admin')

Checks if a user exists in Mongodb

salt.modules.mongodb.user_list(user=None, password=None, host=None, port=None, database='admin')

List users of a Mongodb database

salt.modules.mongodb.user_remove(name, user=None, password=None, host=None, port=None, database='admin')

Remove a Mongodb user

salt.modules.monit

Monit service module. This module will create a monit type service watcher.

salt.modules.monit.restart(name)

Restart service via monit

CLI Example:

salt '*' monit.restart <service name>

salt.modules.monit.start(name)

CLI Example:: salt '*' monit.start <service name>

salt.modules.monit.stop(name)

Stops service via monit

CLI Example:

salt '*' monit.stop <service name>

salt.modules.moosefs

Module for gathering and managing information about MooseFS

salt.modules.moosefs.dirinfo(path, opts=None)

Return information on a directory located on the Moose

CLI Example:

salt '*' moosefs.dirinfo /path/to/dir/ [-[n][h|H]]

salt.modules.moosefs.fileinfo(path)

Return information on a file located on the Moose

CLI Example:

salt '*' moosefs.fileinfo /path/to/dir/

salt.modules.moosefs.getgoal(path, opts=None)

Return goal(s) for a file or directory

CLI Example:

salt '*' moosefs.getgoal /path/to/file [-[n][h|H]]
salt '*' moosefs.getgoal /path/to/dir/ [-[n][h|H][r]]

salt.modules.moosefs.mounts()

Return a list of current MooseFS mounts

CLI Example:

salt '*' moosefs.mounts

salt.modules.mount

Salt module to manage unix mounts and the fstab file

salt.modules.mount.active()

List the active mounts.

CLI Example:

salt '*' mount.active

salt.modules.mount.fstab(config='/etc/fstab')

List the contents of the fstab

CLI Example:

salt '*' mount.fstab

salt.modules.mount.is_fuse_exec(cmd)

Returns true if the command passed is a fuse mountable application.

CLI Example:

salt '*' mount.is_fuse_exec sshfs

salt.modules.mount.mount(name, device, mkmnt=False, fstype='', opts='defaults')

Mount a device

CLI Example:

salt '*' mount.mount /mnt/foo /dev/sdz1 True

salt.modules.mount.remount(name, device, mkmnt=False, fstype='', opts='defaults')

Attempt to remount a device, if the device is not already mounted, mount is called

CLI Example:

salt '*' mount.remount /mnt/foo /dev/sdz1 True

salt.modules.mount.rm_fstab(name, config='/etc/fstab')

Remove the mount point from the fstab

CLI Example:

salt '*' mount.rm_fstab /mnt/foo

salt.modules.mount.set_fstab(name, device, fstype, opts='defaults', dump=0, pass_num=0, config='/etc/fstab')

Verify that this mount is represented in the fstab, change the mount to match the data passed, or add the mount if it is not present.

CLI Example:

salt '*' mount.set_fstab /mnt/foo /dev/sdz1 ext4

salt.modules.mount.umount(name)

Attempt to unmount a device by specifying the directory it is mounted on

CLI Example:

salt '*' mount.umount /mnt/foo

salt.modules.mysql

Module to provide MySQL compatibility to salt.

depends

• MySQLdb Python module

configuration

In order to connect to MySQL, certain configuration is required in /etc/salt/minion on the relevant minions. Some sample configs might look like:

mysql.host: 'localhost'
mysql.port: 3306
mysql.user: 'root'
mysql.pass: ''
mysql.db: 'mysql'
mysql.unix_socket: '/tmp/mysql.sock'

You can also use a defaults file:

mysql.default_file: '/etc/mysql/debian.cnf'

salt.modules.mysql.db_check(name, table=None)

Repairs the full database or just a given table

CLI Example:

salt '*' mysql.db_check dbname

salt.modules.mysql.db_create(name)

Adds a databases to the MySQL server.

CLI Example:

salt '*' mysql.db_create 'dbname'

salt.modules.mysql.db_exists(name)

Checks if a database exists on the MySQL server.

CLI Example:

salt '*' mysql.db_exists 'dbname'

salt.modules.mysql.db_list()

Return a list of databases of a MySQL server using the output from the SHOW DATABASES query.

CLI Example:

salt '*' mysql.db_list

salt.modules.mysql.db_optimize(name, table=None)

Optimizes the full database or just a given table

CLI Example:

salt '*' mysql.db_optimize dbname

salt.modules.mysql.db_remove(name)

Removes a databases from the MySQL server.

CLI Example:

salt '*' mysql.db_remove 'dbname'

salt.modules.mysql.db_repair(name, table=None)

Repairs the full database or just a given table

CLI Example:

salt '*' mysql.db_repair dbname

salt.modules.mysql.db_tables(name)

Shows the tables in the given MySQL database (if exists)

CLI Example:

salt '*' mysql.db_tables 'database'

salt.modules.mysql.free_slave()

Frees a slave from its master. This is a WIP, do not use.

CLI Example:

salt \* mysql.free_slave

salt.modules.mysql.get_master_status()

Retrieves the master status from the mimion.

Returns:

{'host.domain.com': {'Binlog_Do_DB': '',

'Binlog_Ignore_DB': '', 'File': 'mysql-bin.000021', 'Position': 107}}

CLI Example:

salt '*' mysql.get_master_status

salt.modules.mysql.get_slave_status()

Retrieves the slave status from the minion.

Returns:

{'host.domain.com': {'Connect_Retry': 60,
               'Exec_Master_Log_Pos': 107,
               'Last_Errno': 0,
               'Last_Error': '',
               'Last_IO_Errno': 0,
               'Last_IO_Error': '',
               'Last_SQL_Errno': 0,
               'Last_SQL_Error': '',
               'Master_Host': 'comet.scion-eng.com',
               'Master_Log_File': 'mysql-bin.000021',
               'Master_Port': 3306,
               'Master_SSL_Allowed': 'No',
               'Master_SSL_CA_File': '',
               'Master_SSL_CA_Path': '',
               'Master_SSL_Cert': '',
               'Master_SSL_Cipher': '',
               'Master_SSL_Key': '',
               'Master_SSL_Verify_Server_Cert': 'No',
               'Master_Server_Id': 1,
               'Master_User': 'replu',
               'Read_Master_Log_Pos': 107,
               'Relay_Log_File': 'klo-relay-bin.000071',
               'Relay_Log_Pos': 253,
               'Relay_Log_Space': 553,
               'Relay_Master_Log_File': 'mysql-bin.000021',
               'Replicate_Do_DB': '',
               'Replicate_Do_Table': '',
               'Replicate_Ignore_DB': '',
               'Replicate_Ignore_Server_Ids': '',
               'Replicate_Ignore_Table': '',
               'Replicate_Wild_Do_Table': '',
               'Replicate_Wild_Ignore_Table': '',
               'Seconds_Behind_Master': 0,
               'Skip_Counter': 0,
               'Slave_IO_Running': 'Yes',
               'Slave_IO_State': 'Waiting for master to send event',
               'Slave_SQL_Running': 'Yes',
               'Until_Condition': 'None',
               'Until_Log_File': '',
               'Until_Log_Pos': 0}}

CLI Example:

salt '*' mysql.get_slave_status

salt.modules.mysql.grant_add(grant, database, user, host='localhost', grant_option=False, escape=True)

Adds a grant to the MySQL server.

For database, make sure you specify database.table or database.*

CLI Example:

salt '*' mysql.grant_add 'SELECT,INSERT,UPDATE,...' 'database.*' 'frank' 'localhost'

salt.modules.mysql.grant_exists(grant, database, user, host='localhost', grant_option=False, escape=True)

Checks to see if a grant exists in the database

CLI Example:

salt \* mysql.grant_exists 'SELECT,INSERT,UPDATE,...' 'database.*' 'frank' 'localhost'

salt.modules.mysql.grant_revoke(grant, database, user, host='localhost', grant_option=False, escape=True)

Removes a grant from the MySQL server.

CLI Example:

salt '*' mysql.grant_revoke 'SELECT,INSERT,UPDATE' 'database.*' 'frank' 'localhost'

salt.modules.mysql.processlist()

Retrieves the processlist from the MySQL server via "SHOW FULL PROCESSLIST".

Returns: a list of dicts, with each dict representing a process:

{'Command': 'Query',

'Host': 'localhost', 'Id': 39, 'Info': 'SHOW FULL PROCESSLIST', 'Rows_examined': 0, 'Rows_read': 1, 'Rows_sent': 0, 'State': None, 'Time': 0, 'User': 'root', 'db': 'mysql'}

CLI Example:

salt '*' mysql.processlist

salt.modules.mysql.query(database, query)

Run an arbitrary SQL query and return the results or the number of affected rows.

CLI Examples:

salt '*' mysql.query mydb "UPDATE mytable set myfield=1 limit 1"
returns: {'query time': {'human': '39.0ms', 'raw': '0.03899'},
'rows affected': 1L}

salt '*' mysql.query mydb "SELECT id,name,cash from users limit 3"
returns: {'columns': ('id', 'name', 'cash'),
    'query time': {'human': '1.0ms', 'raw': '0.001'},
    'results': ((1L, 'User 1', Decimal('110.000000')),
                (2L, 'User 2', Decimal('215.636756')),
                (3L, 'User 3', Decimal('0.040000'))),
    'rows returned': 3L}

salt '*' mysql.query mydb "INSERT into users values (null,'user 4', 5)"
returns: {'query time': {'human': '25.6ms', 'raw': '0.02563'},
   'rows affected': 1L}

salt '*' mysql.query mydb "DELETE from users where id = 4 limit 1"
returns: {'query time': {'human': '39.0ms', 'raw': '0.03899'},
    'rows affected': 1L}

Jinja Example:

Run a query on "mydb" and use row 0, column 0's data.
{{"{{"}} salt['mysql.query']("mydb","SELECT info from mytable limit 1")['results'][0][0] }}

salt.modules.mysql.slave_lag()

Return the number of seconds that a slave SQL server is lagging behind the master, if the host is not a slave it will return -1. If the server is configured to be a slave for replication but slave IO is not running then -2 will be returned.

CLI Example:

salt '*' mysql.slave_lag

salt.modules.mysql.status()

Return the status of a MySQL server using the output from the SHOW STATUS query.

CLI Example:

salt '*' mysql.status

salt.modules.mysql.user_chpass(user, host='localhost', password=None, password_hash=None)

Change password for MySQL user

CLI Examples:

salt '*' mysql.user_chpass frank localhost newpassword

salt '*' mysql.user_chpass frank localhost password_hash='hash'

salt.modules.mysql.user_create(user, host='localhost', password=None, password_hash=None)

Creates a MySQL user.

CLI Examples:

salt '*' mysql.user_create 'username' 'hostname' 'password'

salt '*' mysql.user_create 'username' 'hostname' password_hash='hash'

salt.modules.mysql.user_exists(user, host='localhost')

Checks if a user exists on the MySQL server.

CLI Example:

salt '*' mysql.user_exists 'username' 'hostname'

salt.modules.mysql.user_grants(user, host='localhost')

Shows the grants for the given MySQL user (if it exists)

CLI Example:

salt '*' mysql.user_grants 'frank' 'localhost'

salt.modules.mysql.user_info(user, host='localhost')

Get full info on a MySQL user

CLI Example:

salt '*' mysql.user_info root localhost

salt.modules.mysql.user_list()

Return a list of users on a MySQL server

CLI Example:

salt '*' mysql.user_list

salt.modules.mysql.user_remove(user, host='localhost')

Delete MySQL user

CLI Example:

salt '*' mysql.user_remove frank localhost

salt.modules.mysql.version()

Return the version of a MySQL server using the output from the SELECT VERSION() query.

CLI Example:

salt '*' mysql.version

salt.modules.network

Module for gathering and managing network information

salt.modules.network.dig(host)

Performs a DNS lookup with dig

CLI Example:

salt '*' network.dig archlinux.org

salt.modules.network.hwaddr(iface)

Return the hardware address (a.k.a. MAC address) for a given interface

CLI Example:

salt '*' network.hwaddr eth0

salt.modules.network.in_subnet(cidr)

Returns True if host is within specified subnet, otherwise False

CLI Example:

salt '*' network.in_subnet 10.0.0.0/16

salt.modules.network.interfaces()

Return a dictionary of information about all the interfaces on the minion

CLI Example:

salt '*' network.interfaces

salt.modules.network.ip_addrs(interface=None, include_loopback=False)

Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is ignored, unless 'include_loopback=True' is indicated. If 'interface' is provided, then only IP addresses from that interface will be returned.

CLI Example:

salt '*' network.ip_addrs

salt.modules.network.ip_addrs6(interface=None, include_loopback=False)

Returns a list of IPv6 addresses assigned to the host. ::1 is ignored, unless 'include_loopback=True' is indicated. If 'interface' is provided, then only IP addresses from that interface will be returned.

CLI Example:

salt '*' network.ip_addrs6

salt.modules.network.netstat()

Return information on open ports and states

CLI Example:

salt '*' network.netstat

salt.modules.network.ping(host)

Performs a ping to a host

CLI Example:

salt '*' network.ping archlinux.org

salt.modules.network.subnets()

Returns a list of subnets to which the host belongs

CLI Example:

salt '*' network.subnets

salt.modules.network.traceroute(host)

Performs a traceroute to a 3rd party host

CLI Example:

salt '*' network.traceroute archlinux.org

salt.modules.nginx

Support for nginx

salt.modules.nginx.signal(signal=None)

Signals nginx to start, restart, or stop.

CLI Example:

salt '*' nginx.signal reload

salt.modules.nginx.version()

Return server version from nginx -v

CLI Example:

salt '*' nginx.version

salt.modules.nova

Module for handling openstack nova calls.

depends

• novaclient Python module

configuration

This module is not usable until the user, password, tenant and auth url are specified either in a pillar or in the minion's config file. For example:

keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: 'http://127.0.0.1:5000/v2.0/'

salt.modules.nova.flavor_create(name, id=0, ram=0, disk=0, vcpus=1)

Add a flavor to nova (nova flavor-create). The following parameters are required:

<name> Name of the new flavor (must be first) <id> Unique integer ID for the new flavor <ram> Memory size in MB <disk> Disk size in GB <vcpus> Number of vcpus

CLI Example:

salt '*' nova.flavor_create myflavor id=6 ram=4096 disk=10 vcpus=1

salt.modules.nova.flavor_delete(id)

Delete a flavor from nova by id (nova flavor-delete)

CLI Example:

salt '*' nova.flavor_delete 7'

salt.modules.nova.flavor_list()

Return a list of available flavors (nova flavor-list)

CLI Example:

salt '*' nova.flavor_list

salt.modules.nova.image_list(name=None)

Return a list of available images (nova images-list + nova image-show) If a name is provided, only that image will be displayed.

CLI Examples:

salt '*' nova.image_list
salt '*' nova.image_list myimage

salt.modules.nova.image_meta_delete(id=None, name=None, keys=None)

Delete a key=value pair from the metadata for an image (nova image-meta set)

CLI Examples:

salt '*' nova.image_meta_delete id=6f52b2ff-0b31-4d84-8fd1-af45b84824f6 keys=cheese
salt '*' nova.image_meta_delete name=myimage keys=salad,beans

salt.modules.nova.image_meta_set(id=None, name=None, **kwargs)

Sets a key=value pair in the metadata for an image (nova image-meta set)

CLI Examples:

salt '*' nova.image_meta_set id=6f52b2ff-0b31-4d84-8fd1-af45b84824f6 cheese=gruyere
salt '*' nova.image_meta_set name=myimage salad=pasta beans=baked

salt.modules.nova.keypair_add(name, pubfile=None, pubkey=None)

Add a keypair to nova (nova keypair-add)

CLI Examples:

salt '*' nova.keypair_add mykey pubfile='/home/myuser/.ssh/id_rsa.pub'
salt '*' nova.keypair_add mykey pubkey='ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAuGj4A7HcPLPl/etc== myuser@mybox'

salt.modules.nova.keypair_delete(name)

Add a keypair to nova (nova keypair-delete)

CLI Example:

salt '*' nova.keypair_delete mykey'

salt.modules.nova.keypair_list()

Return a list of available keypairs (nova keypair-list)

CLI Example:

salt '*' nova.keypair_list

salt.modules.nova.list()

To maintain the feel of the nova command line, this function simply calls the server_list function.

salt.modules.nova.secgroup_create(name, description)

Add a secgroup to nova (nova secgroup-create)

CLI Example:

salt '*' nova.secgroup_create mygroup 'This is my security group'

salt.modules.nova.secgroup_delete(name)

Delete a secgroup to nova (nova secgroup-delete)

CLI Example:

salt '*' nova.secgroup_delete mygroup

salt.modules.nova.secgroup_list()

Return a list of available security groups (nova items-list)

CLI Example:

salt '*' nova.secgroup_list

salt.modules.nova.server_list()

Return detailed information for an active server

CLI Example:

salt '*' nova.show

salt.modules.nova.server_show(server_id)

Return detailed information for an active server

CLI Example:

salt '*' nova.show

salt.modules.nova.show(server_id)

To maintain the feel of the nova command line, this function simply calls the server_show function.

salt.modules.nzbget

Support for nzbget

salt.modules.nzbget.list(user=None)

Return list of active downloads using nzbget -L. Default user is root.

CLI Example:

salt '*' nzbget.list larry

salt.modules.nzbget.pause(user=None)

Pause nzbget daemon using -P option. Default user is root.

CLI Example:

salt '*' nzbget.pause shemp

salt.modules.nzbget.serverversion()

Return server version from nzbget -V. Default user is root.

CLI Example:

salt '*' nzbget.serverversion moe

salt.modules.nzbget.start(user=None)

Start nzbget as a daemon using -D option Default user is root.

CLI Example:

salt '*' nzbget.start

salt.modules.nzbget.stop(user=None)

Stop nzbget daemon using -Q option. Default user is root.

CLI Example:

salt '*' nzbget.stop curly

salt.modules.nzbget.unpause(user=None)

Unpause nzbget daemon using -U option. Default user is root.

CLI Example:

salt '*' nzbget.unpause shemp

salt.modules.nzbget.version()

Return version from nzbget -v.

CLI Example:

salt '*' nzbget.version

salt.modules.openbsdpkg

Package support for OpenBSD

salt.modules.openbsdpkg.available_version(name)

The available version of the package in the repository

CLI Example:

salt '*' pkg.available_version <package name>

salt.modules.openbsdpkg.compare(version1='', version2='')

Compare two version strings. Return -1 if version1 < version2, 0 if version1 == version2, and 1 if version1 > version2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '0.2.4.1-0'

salt.modules.openbsdpkg.install(name=None, pkgs=None, sources=None, **kwargs)

Install the passed package

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example, Install one package:

salt '*' pkg.install <package name>

CLI Example, Install more than one package:

salt '*' pkg.install pkgs='["<package name>", "<package name>"]'

CLI Example, Install more than one package from a alternate source (e.g. salt file-server, http, ftp, local filesystem):

salt '*' pkg.install sources='[{"<pkg name>": "salt://pkgs/<pkg filename>"}]'

salt.modules.openbsdpkg.list_pkgs()

List the packages currently installed as a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.openbsdpkg.purge(name, **kwargs)

Remove a single package with pkg_delete

Returns a list containing the removed packages.

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.openbsdpkg.remove(name, **kwargs)

Remove a single package with pkg_delete

Returns a list containing the removed packages.

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.openbsdpkg.version(name)

Returns a version if the package is installed, else returns an empty string

CLI Example:

salt '*' pkg.version <package name>

salt.modules.openbsdservice

The service module for OpenBSD

salt.modules.openbsdservice.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.openbsdservice.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.openbsdservice.status(name, sig=None)

Return the status for a service, returns a bool whether the service is running.

CLI Example:

salt '*' service.status <service name>

salt.modules.openbsdservice.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.osxdesktop

Mac OS X implementations of various commands in the "desktop" interface

salt.modules.osxdesktop.get_output_volume()

Get the output volume (range 0 to 100)

CLI Example:

salt '*' desktop.get_output_volume

salt.modules.osxdesktop.lock()

Lock the desktop session

CLI Example:

salt '*' desktop.lock

salt.modules.osxdesktop.say(*words)

Say some words.

CLI Example:

salt '*' desktop.say <word0> <word1> ... <wordN>

salt.modules.osxdesktop.screensaver()

Launch the screensaver

CLI Example:

salt '*' desktop.screensaver

salt.modules.osxdesktop.set_output_volume(volume)

Set the volume of sound (range 0 to 100)

CLI Example:

salt '*' desktop.set_output_volume <volume>

salt.modules.pacman

A module to wrap pacman calls, since Arch is the best (- https://wiki.archlinux.org/index.php/Arch_is_the_best)

salt.modules.pacman.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

salt.modules.pacman.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.pacman.file_dict(*packages)

List the files that belong to a package, grouped by package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.pacman.file_list(*packages)

List the files that belong to a package. Not specifying any packages will return a list of _every_ file on the system's package database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.pacman.install(name=None, refresh=True, pkgs=None, sources=None, **kwargs)

Install the passed package, add refresh=True to install with an -Sy.

name

CLI Example::

salt '*' pkg.install <package name>

refresh

Whether or not to refresh the package database before installing.

Multiple Package Installation Options:

pkgs

A list of packages to install from a software repository. Must be passed as a python list. A specific version number can be specified by using a single-element dict representing the package and its version. As with the version parameter above, comparison operators can be used to target a specific version of a package.

CLI Examples::

salt '*' pkg.install pkgs='["foo", "bar"]' salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-4"}]' salt '*' pkg.install pkgs='["foo", {"bar": "<1.2.3-4"}]'

sources

A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

CLI Example::

salt '*' pkg.install sources='[{"foo": "salt://foo.pkg.tar.xz"},{"bar": "salt://bar.pkg.tar.xz"}]'

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

salt.modules.pacman.list_pkgs()

List the packages currently installed as a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.pacman.list_upgrades()

List all available package upgrades on this system

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.pacman.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.pacman.purge(name, **kwargs)

Recursively remove a package and all dependencies which were installed with it, this will call a pacman -Rsc

Return a list containing the removed packages.

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.pacman.refresh_db()

Just run a pacman -Sy, return a dict:

{'<database name>': Bool}

CLI Example:

salt '*' pkg.refresh_db

salt.modules.pacman.remove(name, **kwargs)

Remove a single package with pacman -R

Return a list containing the removed packages.

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.pacman.upgrade()

Run a full system upgrade, a pacman -Syu

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

salt.modules.pacman.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.pacman.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

salt.modules.pam

Support for pam

salt.modules.pam.read_file(file_name)

This is just a test function, to make sure parsing works

CLI Example:

salt '*' pam.read_file /etc/pam.d/login

salt.modules.parted

Module for managing partitions on posix-like systems. Some functions may not be available, depending on your version of parted. Check man 8 parted for more information, or the online docs at: http://www.gnu.org/software/parted/manual/html_chapter/parted_2.html In light of parted not directly supporting partition IDs, some of this module has been written to utilize sfdisk instead. For further information, please reference the man page for sfdisk: man 8 sfdisk

salt.modules.parted.align_check(device, part_type, partition)

partition.align_check device part_type partition

Check if partition satisfies the alignment constraint of part_type. Type must be "minimal" or "optimal".

CLI Example:

salt '*' partition.align_check /dev/sda minimal 1

salt.modules.parted.check(device, minor)

partition.check device minor

Checks if the file system on partition <minor> has any errors.

CLI Example:

salt '*' partition.check 1

salt.modules.parted.cp(device, from_minor, to_minor)

partition.check device from_minor to_minor

Copies the file system on the partition <from-minor> to partition

<to-minor>, deleting the original contents of the destination partition.

CLI Example:

salt '*' partition.cp /dev/sda 2 3

salt.modules.parted.get_id(device, minor)

Prints the system ID for the partition. Some typical values are:

 b: FAT32 (vfat)
 7: HPFS/NTFS
82: Linux Swap
83: Linux
8e: Linux LVM
fd: Linux RAID Auto

CLI Example:

salt '*' partition.get_id /dev/sda 1

salt.modules.parted.mkfs(device, minor, fs_type)

partition.mkfs device minor fs_type

Makes a file system <fs_type> on partition <minor>, destroying all data

that resides on that partition. <fs_type> must be one of "ext2", "fat32", "fat16", "linux-swap" or "reiserfs" (if libreiserfs is installed)

CLI Example:

salt '*' partition.mkfs 2 fat32

salt.modules.parted.mklabel(device, label_type)

partition.mklabel device label_type

Create a new disklabel (partition table) of label_type. Type should be one of "aix", "amiga", "bsd", "dvh", "gpt", "loop", "mac", "msdos", "pc98", or "sun".

CLI Example:

salt '*' partition.mklabel /dev/sda msdos

salt.modules.parted.mkpart(device, part_type, fs_type, start, end)

partition.mkpart device part_type fs_type start end

Make a part_type partition for filesystem fs_type, beginning at start and

ending at end (by default in megabytes). part_type should be one of "primary", "logical", or "extended".

CLI Example:

salt '*' partition.mkpart /dev/sda primary fat32 0 639

salt.modules.parted.mkpartfs(device, part_type, fs_type, start, end)

partition.mkpartfs device part_type fs_type start end

Make a <part_type> partition with a new filesystem of <fs_type>, beginning

at <start> and ending at <end> (by default in megabytes). <part_type> should be one of "primary", "logical", or "extended". <fs_type> must be one of "ext2", "fat32", "fat16", "linux-swap" or "reiserfs" (if libreiserfs is installed)

CLI Example:

salt '*' partition.mkpartfs /dev/sda logical ext2 440 670

salt.modules.parted.name(device, partition, name)

partition.name device partition name

Set the name of partition to name. This option works only on Mac, PC98,

and GPT disklabels. The name can be placed in quotes, if necessary.

CLI Example:

salt '*' partition.name /dev/sda 1 'My Documents'

salt.modules.parted.part_list(device, unit=None)

Ask the kernel to update its local partition data

CLI Examples:

salt '*' partition.partlist /dev/sda
salt '*' partition.partlist /dev/sda unit=s
salt '*' partition.partlist /dev/sda unit=kB

salt.modules.parted.probe(device='')

Ask the kernel to update its local partition data

CLI Examples:

salt '*' partition.probe
salt '*' partition.probe /dev/sda

salt.modules.parted.rescue(device, start, end)

partition.rescue device start end

Rescue a lost partition that was located somewhere between start and end.

If a partition is found, parted will ask if you want to create an entry for it in the partition table.

CLI Example:

salt '*' partition.rescue /dev/sda 0 8056

salt.modules.parted.resize(device, minor, start, end)

partition.resize device minor, start, end

Resizes the partition with number <minor>. The partition will start <start>

from the beginning of the disk, and end <end> from the beginning of the disk. resize never changes the minor number. Extended partitions can be resized, so long as the new extended partition completely contains all logical partitions.

CLI Example:

salt '*' partition.resize /dev/sda 3 200 850

salt.modules.parted.rm(device, minor)

partition.rm device minor

Removes the partition with number <minor>.

CLI Example:

salt '*' partition.rm /dev/sda 5

salt.modules.parted.set(device, minor, flag, state)

partition.set device minor flag state

Changes a flag on the partition with number <minor>. A flag can be either

"on" or "off". Some or all of these flags will be available, depending on what disk label you are using.

CLI Example:

salt '*' partition.set /dev/sda 1 boot on

salt.modules.parted.set_id(device, minor, system_id)

Sets the system ID for the partition. Some typical values are:

 b: FAT32 (vfat)
 7: HPFS/NTFS
82: Linux Swap
83: Linux
8e: Linux LVM
fd: Linux RAID Auto

CLI Example:

salt '*' partition.set_id /dev/sda 1 83

salt.modules.parted.toggle(device, partition, flag)

partition.toggle device partition flag

Toggle the state of <flag> on <partition>

CLI Example:

salt '*' partition.name /dev/sda 1 boot

salt.modules.pecl

Manage PHP pecl extensions.

salt.modules.pecl.install(pecls)

Installs one or several pecl extensions.

pecls

The pecl extensions to install.

CLI Example:

salt '*' pecl.install fuse

salt.modules.pecl.list()

List installed pecl extensions.

CLI Example:

salt '*' pecl.list

salt.modules.pecl.uninstall(pecls)

Uninstall one or several pecl extensions.

pecls

The pecl extensions to uninstall.

CLI Example:

salt '*' pecl.uninstall fuse

salt.modules.pecl.update(pecls)

Update one or several pecl exntesions.

pecls

The pecl extensions to update.

CLI Example:

salt '*' pecl.update fuse

salt.modules.pillar

Extract the pillar data for this minion

salt.modules.pillar.data()

Returns the pillar derived from the configured pillar source. The pillar source is derived from the file_client option in the minion config

CLI Example:

salt '*' pillar.data

salt.modules.pillar.raw()

Return the raw pillar data that is available in the module. This will show the pillar as it is loaded as the __pillar__ dict.

CLI Example:

salt '*' pillar.raw

salt.modules.pip

Install Python packages with pip to either the system or a virtualenv
salt.modules.pip.freeze(bin_env=None, runas=None, cwd=None): Return a list of installed packages either globally or in the specified virtualenv; bin_env

path to pip bin or path to virtualenv. If doing an uninstall from the system python and want to use a specific pip bin (pip-2.7, pip-2.6, etc..) just specify the pip bin you want. If uninstalling from a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/)

runas

User to run pip as

cwd

Current working directory to run pip from

CLI Example:

salt '*' pip.freeze /home/code/path/to/virtualenv/

salt.modules.pip.install(pkgs=None, requirements=None, env=None, bin_env=None, log=None, proxy=None, timeout=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, no_deps=False, no_install=False, no_download=False, install_options=None, runas=None, cwd=None, __env__='base')

Install packages with pip

Install packages individually or from a pip requirements file. Install packages globally or to a virtualenv.

pkgs

comma separated list of packages to install

requirements

path to requirements

bin_env

path to pip bin or path to virtualenv. If doing a system install, and want to use a specific pip bin (pip-2.7, pip-2.6, etc..) just specify the pip bin you want. If installing into a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/)

env

deprecated, use bin_env now

log

Log file where a complete (maximum verbosity) record will be kept

proxy

Specify a proxy in the form user:passwd@proxy.server:port. Note that the user:password@ is optional and required only if you are behind an authenticated proxy. If you provide user@proxy.server:port then you will be prompted for a password.

timeout

Set the socket timeout (default 15 seconds)

editable

install something editable(ie git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed)

find_links

URL to look for packages at

index_url

Base URL of Python Package Index

extra_index_url

Extra URLs of package indexes to use in addition to index_url

no_index

Ignore package index

mirrors

Specific mirror URLs to query (automatically adds --use-mirrors)

build

Unpack packages into build dir

target

Install packages into target dir

download

Download packages into download instead of installing them

download_cache

Cache downloaded packages in download_cache dir

source

Check out editable packages into source dir

upgrade

Upgrade all packages to the newest available version

force_reinstall

When upgrading, reinstall all packages even if they are already up-to-date.

ignore_installed

Ignore the installed packages (reinstalling instead)

no_deps

Ignore package dependencies

no_install

Download and unpack all packages, but don't actually install them

no_download

Don't download any packages, just install the ones already downloaded (completes an install run with --no-install)

install_options

Extra arguments to be supplied to the setup.py install command (use like --install-option="--install- scripts=/usr/local/bin"). Use multiple --install- option options to pass multiple options to setup.py install. If you are using an option with a directory path, be sure to use absolute path.

runas

User to run pip as

cwd

Current working directory to run pip from

CLI Example:

salt '*' pip.install <package name>,<package2 name>

salt '*' pip.install requirements=/path/to/requirements.txt

salt '*' pip.install <package name> bin_env=/path/to/virtualenv

salt '*' pip.install <package name> bin_env=/path/to/pip_bin

Comlicated CLI example:

salt '*' pip.install markdown,django editable=git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed upgrade=True no_deps=True

salt.modules.pip.list(prefix='', bin_env=None, runas=None, cwd=None)

Filter list of installed apps from freeze and check to see if prefix exists in the list of packages installed.

CLI Example:

salt '*' pip.list salt

salt.modules.pip.uninstall(pkgs=None, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, runas=None, cwd=None, __env__='base')

Uninstall packages with pip

Uninstall packages individually or from a pip requirements file. Uninstall packages globally or from a virtualenv.

pkgs

comma separated list of packages to install

requirements

path to requirements

bin_env

log

Log file where a complete (maximum verbosity) record will be kept

proxy

timeout

Set the socket timeout (default 15 seconds)

runas

User to run pip as

cwd

Current working directory to run pip from

CLI Example:

salt '*' pip.uninstall <package name>,<package2 name>

salt '*' pip.uninstall requirements=/path/to/requirements.txt

salt '*' pip.uninstall <package name> bin_env=/path/to/virtualenv

salt '*' pip.uninstall <package name> bin_env=/path/to/pip_bin

salt.modules.pkgng

Support for pkgng

salt.modules.pkgng.add(pkg_path)

Install a package from either a local source or remote one

CLI Example:

salt '*' pkgng.add /tmp/package.txz

salt.modules.pkgng.audit()

Audits installed packages against known vulnerabilities

CLI Example:

salt '*' pkgng.audit

salt.modules.pkgng.autoremove(dryrun=False)

Delete packages which were automatically installed as dependencies and are not required anymore

CLI Example:

    salt '*' pkgng.autoremove

dryrun
    Dry-run mode. The list of changes to packages is always printed,
    but no changes are actually made.

   CLI Example::

       salt '*' pkgng.autoremove dryrun=True

salt.modules.pkgng.available_version(pkg_name)

The available version of the package in the repository

CLI Example:

salt '*' pkgng.available_version <package name>

salt.modules.pkgng.backup(file_name)

Export installed packages into yaml+mtree file

CLI Example:

salt '*' pkgng.backup /tmp/pkg

salt.modules.pkgng.check(depends=False, recompute=False, checksum=False)

Sanity checks installed packages

depends

Check for and install missing dependencies.

CLI Example:

salt '*' pkgng.check recompute=True

recompute

Recompute sizes and checksums of installed packages.

CLI Example:

salt '*' pkgng.check depends=True

checksum

Find invalid checksums for installed packages.

CLI Example:

salt '*' pkgng.check checksum=True

salt.modules.pkgng.clean()

Cleans the local cache of fetched remote packages

CLI Example:

salt '*' pkgng.clean

salt.modules.pkgng.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.pkgng.delete(pkg_name, all_installed=False, force=False, glob=False, dryrun=False, recurse=False, regex=False, pcre=False)

Delete a package from the database and system

CLI Example:

salt '*' pkgng.delete <package name>

all_installed
    Deletes all installed packages from the system and empties the
    database. USE WITH CAUTION!

   CLI Example::

       salt '*' pkgng.delete all all_installed=True force=True

force
    Forces packages to be removed despite leaving unresolved
    dependencies.

   CLI Example::

       salt '*' pkgng.delete <package name> force=True

glob
    Treat the package names as shell glob patterns.

   CLI Example::

       salt '*' pkgng.delete <package name> glob=True

dryrun
    Dry run mode. The list of packages to delete is always printed, but
    no packages are actually deleted.

   CLI Example::

       salt '*' pkgng.delete <package name> dryrun=True

recurse
    Delete all packages that require the listed package as well.

   CLI Example::

       salt '*' pkgng.delete <package name> recurse=True

regex
    Treat the package names as regular expressions.

   CLI Example::

       salt '*' pkgng.delete <regular expression> regex=True

pcre
    Treat the package names as extended regular expressions.

   CLI Example::

       salt '*' pkgng.delete <extended regular expression> pcre=True

salt.modules.pkgng.fetch(pkg_name, all=False, quiet=False, reponame=None, glob=True, regex=False, pcre=False, local=False, depends=False)

Fetches remote packages

CLI Example:

salt '*' pkgng.fetch <package name>

all
    Fetch all packages.

   CLI Example::

       salt '*' pkgng.fetch <package name> all=True

quiet
    Quiet mode. Show less output.

   CLI Example::

       salt '*' pkgng.fetch <package name> quiet=True

reponame
    Fetches packages from the given reponame if multiple repo support
    is enabled. See pkg.conf(5).

   CLI Example::

       salt '*' pkgng.fetch <package name> reponame=repo

glob
    Treat pkg_name as a shell glob pattern.

   CLI Example::

       salt '*' pkgng.fetch <package name> glob=True

regex
    Treat pkg_name as a regular expression.

   CLI Example::

       salt '*' pkgng.fetch <regular expression> regex=True

pcre
    Treat pkg_name is an extended regular expression.

   CLI Example::

       salt '*' pkgng.fetch <extended regular expression> pcre=True

local
    Skip updating the repository catalogues with pkg-update(8). Use the
    local cache only.

   CLI Example::

       salt '*' pkgng.fetch <package name> local=True

depends
    Fetch the package and its dependencies as well.

   CLI Example::

       salt '*' pkgng.fetch <package name> depends=True

salt.modules.pkgng.info(pkg_name=None)

Returns info on packages installed on system

CLI Example:

salt '*' pkgng.info
salt '*' pkgng.info sudo

salt.modules.pkgng.install(pkg_name, orphan=False, force=False, glob=False, local=False, dryrun=False, quiet=False, require=False, reponame=None, regex=False, pcre=False)

Install package from repositories

CLI Example:

salt '*' pkgng.install <package name>

orphan
    Mark the installed package as orphan. Will be automatically removed
    if no other packages depend on them. For more information please
    refer to pkg-autoremove(8).

   CLI Example::

       salt '*' pkgng.install <package name> orphan=True

force
    Force the reinstallation of the package if already installed.

   CLI Example::

       salt '*' pkgng.install <package name> force=True

glob
    Treat the package names as shell glob patterns.

   CLI Example::

       salt '*' pkgng.install <package name> glob=True

local
    Skip updating the repository catalogues with pkg-update(8). Use the
    locally cached copies only.

   CLI Example::

       salt '*' pkgng.install <package name> local=True

dryrun
    Dru-run mode. The list of changes to packages is always printed,
    but no changes are actually made.

   CLI Example::

       salt '*' pkgng.install <package name> dryrun=True

quiet
    Force quiet output, except when dryrun is used, where pkg install
    will always show packages to be installed, upgraded or deleted.

   CLI Example::

       salt '*' pkgng.install <package name> quiet=True

require
    When used with force, reinstalls any packages that require the
    given package.

   CLI Example::

       salt '*' pkgng.install <package name> require=True force=True

reponame
    In multi-repo mode, override the pkg.conf ordering and only attempt
    to download packages from the named repository.

   CLI Example::

       salt '*' pkgng.install <package name> reponame=repo

regex
    Treat the package names as a regular expression

   CLI Example::

       salt '*' pkgng.install <regular expression> regex=True

pcre
    Treat the package names as extended regular expressions.

   CLI Example::

       salt '*' pkgng.install <extended regular expression> pcre=True

salt.modules.pkgng.parse_config(file_name='/usr/local/etc/pkg.conf')

Return dict of uncommented global variables.

CLI Example:

salt '*' pkgng.parse_config
*NOTE* not working right

salt.modules.pkgng.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.pkgng.restore(file_name)

Reads archive created by pkg backup -d and recreates the database.

salt '*' pkgng.restore /tmp/pkg

salt.modules.pkgng.search(pkg_name, exact=False, glob=False, regex=False, pcre=False, comment=False, desc=False, full=False, depends=False, size=False, quiet=False, origin=False, prefix=False)

Searches in remote package repositories

CLI Example:

salt '*' pkgng.search pattern

exact
    Treat pattern as exact pattern.

   CLI Example::

       salt '*' pkgng.search pattern exact=True

glob
    Treat pattern as a shell glob pattern.

   CLI Example::

       salt '*' pkgng.search pattern glob=True

regex
    Treat pattern as a regular expression.

   CLI Example::

       salt '*' pkgng.search pattern regex=True

pcre
    Treat pattern as an extended regular expression.

   CLI Example::

       salt '*' pkgng.search pattern pcre=True

comment
    Search for pattern in the package comment one-line description.

   CLI Example::

       salt '*' pkgng.search pattern comment=True

desc
    Search for pattern in the package description.

   CLI Example::

       salt '*' pkgng.search pattern desc=True

full
    Displays full information about the matching packages.

   CLI Example::

       salt '*' pkgng.search pattern full=True

depends
    Displays the dependencies of pattern.

   CLI Example::

       salt '*' pkgng.search pattern depends=True

size
    Displays the size of the package

   CLI Example::

       salt '*' pkgng.search pattern size=True

quiet
    Be quiet. Prints only the requested information without displaying
    many hints.

   CLI Example::

       salt '*' pkgng.search pattern quiet=True

origin
    Displays pattern origin.

   CLI Example::

       salt '*' pkgng.search pattern origin=True

prefix
    Displays the installation prefix for each package matching pattern.

   CLI Example::

       salt '*' pkgng.search pattern prefix=True

salt.modules.pkgng.stats(local=False, remote=False)

Return pkgng stats.

CLI Example:

salt '*' pkgng.stats

local
    Display stats only for the local package database.

   CLI Example::

       salt '*' pkgng.stats local=True

remote
    Display stats only for the remote package database(s).

   CLI Example::

       salt '*' pkgng.stats remote=True

salt.modules.pkgng.update(force=False)

Refresh PACKAGESITE contents

CLI Example:

salt '*' pkgng.update

force
    Force a full download of the repository catalogue without regard to
    the respective ages of the local and remote copies of the
    catalogue.

   CLI Example::

       salt '*' pkgng.update force=True

salt.modules.pkgng.update_package_site(new_url)

Updates remote package repo url, PACKAGESITE var to be exact.

Must be using http://, ftp://, or https// protos

CLI Example:

salt '*' pkgng.update_package_site http://127.0.0.1/

salt.modules.pkgng.updating(pkg_name, filedate=None, filename=None)

' Displays UPDATING entries of software packages

CLI Example:

salt '*' pkgng.updating foo

filedate
    Only entries newer than date are shown. Use a YYYYMMDD date format.

   CLI Example::

       salt '*' pkgng.updating foo filedate=20130101

filename
    Defines an alternative location of the UPDATING file.

   CLI Example::

       salt '*' pkgng.updating foo filename=/tmp/UPDATING

salt.modules.pkgng.upgrade(force=False, local=False, dryrun=False)

Upgrade all packages

CLI Example:

salt '*' pkgng.upgrade

force
    Force reinstalling/upgrading the whole set of packages.

   CLI Example::

       salt '*' pkgng.upgrade force=True

local
    Skip updating the repository catalogues with pkg-update(8). Use the
    local cache only.

   CLI Example::

       salt '*' pkgng.update local=True

dryrun
    Dry-run mode: show what packages have updates available, but do not
    perform any upgrades. Repository catalogues will be updated as
    usual unless the local option is also given.

   CLI Example::

       salt '*' pkgng.update dryrun=True

salt.modules.pkgng.version()

Displays the current version of pkg

CLI Example:

salt '*' pkgng.version

salt.modules.pkgng.which(file_name, origin=False, quiet=False)

Displays which package installed a specific file

CLI Example:

salt '*' pkgng.which <file name>

origin
    Shows the origin of the package instead of name-version.

   CLI Example::

       salt '*' pkgng.which <file name> origin=True

quiet
    Quiet output.

   CLI Example::

       salt '*' pkgng.which <file name> quiet=True

salt.modules.pkg_resource

Resources needed by pkg providers

salt.modules.pkg_resource.add_pkg(pkgs, name, version)

Add a package to a dict of installed packages.

CLI Example:

salt '*' pkg_resource.add_pkg '{}' bind 9

salt.modules.pkg_resource.check_desired(desired=None)

Examines desired package names to make sure they were formatted properly. Returns a list of problems encountered.

CLI Examples:

salt '*' pkg_resource.check_desired

salt.modules.pkg_resource.compare(pkg1='', oper='==', pkg2='')

Package version comparison function.

CLI Example:

salt '*' pkg_resource.compare

salt.modules.pkg_resource.find_changes(old=None, new=None)

Compare before and after results from pkg.list_pkgs() to determine what changes were made to the packages installed on the minion.

CLI Example:

salt '*' pkg_resource.find_changes

salt.modules.pkg_resource.pack_pkgs(pkgs)

Accepts a list of packages or package/version pairs (or a string representing said list) and returns a dict of name/version pairs. For a given package, if no version was specified (i.e. the value is a string and not a dict, then the dict returned will use None as the value for that package.

Example: '["foo", {"bar": 1.2}, baz ]' would become

{'foo': None, 'bar': 1.2, 'baz': None}

CLI Example:

salt '*' pkg_resource.pack_pkgs '["foo", {"bar": 1.2}, "baz"]'

salt.modules.pkg_resource.pack_sources(sources)

Accepts list of dicts (or a string representing a list of dicts) and packs the key/value pairs into a single dict.

Example: '[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]' would become {"foo": "salt://foo.rpm", "bar": "salt://bar.rpm"}

CLI Example:

salt '*' pkg_resource.pack_sources '[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]'

salt.modules.pkg_resource.parse_targets(name=None, pkgs=None, sources=None)

Parses the input to pkg.install and returns back the package(s) to be installed. Returns a list of packages, as well as a string noting whether the packages are to come from a repository or a binary package.

CLI Example:

salt '*' pkg_resource.parse_targets

salt.modules.pkg_resource.perform_cmp(pkg1='', pkg2='')

Compares two version strings using distutils.version.LooseVersion. This is a fallback for providers which don't have a version comparison utility built into them. Return -1 if version1 < version2, 0 if version1 == version2, and 1 if version1 > version2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg_resource.perform_cmp

salt.modules.pkg_resource.sort_pkglist(pkgs)

Accepts a dict obtained from pkg.list_pkgs() and sorts in place the list of versions for any packages that have multiple versions installed, so that two package lists can be compared to one another.

CLI Example:

salt '*' pkg_resource.sort_pkglist '["3.45", "2.13"]'

salt.modules.pkgutil

Pkgutil support for Solaris

salt.modules.pkgutil.available_version(name)

The available version of the package in the repository

CLI Example:

salt '*' pkgutil.available_version CSWpython

salt.modules.pkgutil.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.pkgutil.install(name, refresh=False, version=None, **kwargs)

Install the named package using the pkgutil tool.

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkgutil.install <package_name>
salt '*' pkgutil.install SMClgcc346

salt.modules.pkgutil.list_pkgs()

List the packages currently installed as a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkgutil.list_pkgs

salt.modules.pkgutil.list_upgrades(refresh=True)

List all available package upgrades on this system

CLI Example:

salt '*' pkgutil.list_upgrades

salt.modules.pkgutil.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.pkgutil.purge(name, **kwargs)

Remove a package and all its dependencies which are not in use by other packages.

Returns a list containing the removed packages.

CLI Example:

salt '*' pkgutil.purge <package name>

salt.modules.pkgutil.refresh_db()

Updates the pkgutil repo database (pkgutil -U)

CLI Example:

salt '*' pkgutil.refresh_db

salt.modules.pkgutil.remove(name, **kwargs)

Remove a package and all its dependencies which are not in use by other packages.

Returns a list containing the removed packages.

CLI Example:

salt '*' pkgutil.remove <package name>
salt '*' pkgutil.remove SMCliconv

salt.modules.pkgutil.upgrade(refresh=True, **kwargs)

Upgrade all of the packages to the latest available version.

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkgutil.upgrade

salt.modules.pkgutil.upgrade_available(name)

Check if there is an upgrade available for a certain package

CLI Example:

salt '*' pkgutil.upgrade_available CSWpython

salt.modules.pkgutil.version(name)

Returns a version if the package is installed, else returns an empty string

CLI Example:

salt '*' pkgutil.version CSWpython

salt.modules.postgres

Module to provide Postgres compatibility to salt.

configuration

In order to connect to Postgres, certain configuration is required in /etc/salt/minion on the relevant minions. Some sample configs might look like:

postgres.host: 'localhost'
postgres.port: '5432'
postgres.user: 'postgres'
postgres.pass: ''
postgres.db: 'postgres'

This data can also be passed into pillar. Options passed into opts will overwrite options passed into pillar

salt.modules.postgres.db_create(name, user=None, host=None, port=None, db=None, password=None, tablespace=None, encoding=None, locale=None, lc_collate=None, lc_ctype=None, owner=None, template=None, runas=None)

Adds a databases to the Postgres server.

CLI Example:

salt '*' postgres.db_create 'dbname'

salt '*' postgres.db_create 'dbname' template=template_postgis

salt.modules.postgres.db_exists(name, user=None, host=None, port=None, db=None, password=None, runas=None)

Checks if a database exists on the Postgres server.

CLI Example:

salt '*' postgres.db_exists 'dbname'

salt.modules.postgres.db_list(user=None, host=None, port=None, db=None, password=None, runas=None)

Return a list of databases of a Postgres server using the output from the psql -l query.

CLI Example:

salt '*' postgres.db_list

salt.modules.postgres.db_remove(name, user=None, host=None, port=None, db=None, password=None, runas=None)

Removes a databases from the Postgres server.

CLI Example:

salt '*' postgres.db_remove 'dbname'

salt.modules.postgres.group_create(groupname, user=None, host=None, port=None, db=None, password=None, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, rolepassword=None, groups=None, runas=None)

Creates a Postgres group. A group is postgres is similar to a user, but cannot login.

CLI Example:

salt '*' postgres.group_create 'groupname' user='user' host='hostname' port='port' rolepassword='password'

salt.modules.postgres.group_remove(groupname, user=None, host=None, port=None, db=None, password=None, runas=None)

Removes a group from the Postgres server.

CLI Example:

salt '*' postgres.group_remove 'groupname'

salt.modules.postgres.group_update(groupname, user=None, host=None, port=None, db=None, password=None, createdb=False, createuser=False, encrypted=False, replication=False, rolepassword=None, groups=None, runas=None)

Updated a postgres group

CLI Examples:

salt '*' postgres.group_update 'username' user='user' host='hostname' port='port' rolepassword='password'

salt.modules.postgres.user_create(username, user=None, host=None, port=None, db=None, password=None, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, rolepassword=None, groups=None, runas=None)

Creates a Postgres user.

CLI Examples:

salt '*' postgres.user_create 'username' user='user' host='hostname' port='port' rolepassword='password'

salt.modules.postgres.user_exists(name, user=None, host=None, port=None, db=None, password=None, runas=None)

Checks if a user exists on the Postgres server.

CLI Example:

salt '*' postgres.user_exists 'username'

salt.modules.postgres.user_list(user=None, host=None, port=None, db=None, password=password, runas=None)

Return a list of users of a Postgres server.

CLI Example:

salt '*' postgres.user_list

salt.modules.postgres.user_remove(username, user=None, host=None, port=None, db=None, password=None, runas=None)

Removes a user from the Postgres server.

CLI Example:

salt '*' postgres.user_remove 'username'

salt.modules.postgres.user_update(username, user=None, host=None, port=None, db=None, password=None, createdb=False, createuser=False, encrypted=False, replication=False, rolepassword=None, groups=None, runas=None)

Creates a Postgres user.

CLI Examples:

salt '*' postgres.user_create 'username' user='user' host='hostname' port='port' rolepassword='password'

salt.modules.postgres.version()

Return the version of a Postgres server using the output from the psql --version cmd.

CLI Example:

salt '*' postgres.version

salt.modules.poudriere

Support for poudriere

salt.modules.poudriere.bulk_build(jail, pkg_file, keep=False)

Run bulk build on poudriere server.

Return number of pkg builds, failures, and errors, on error dump to cli

CLI Example:

salt -N buildbox_group poudriere.bulk_build 90amd64 /root/pkg_list

salt.modules.poudriere.create_jail(name, arch, version='9.0-RELEASE')

Creates a new poudriere jail if one does not exist

NOTE creating a new jail will take some time the master is not hanging

CLI Example::

salt '*' poudriere.create_jail 90amd64 amd64

salt.modules.poudriere.create_ports_tree()

Not working need to run portfetch non interactive

salt.modules.poudriere.delete_jail(name)

Deletes poudriere jail with name

CLI Example:

salt '*' poudriere.delete_jail 90amd64

salt.modules.poudriere.is_jail(name)

Return True if jail exists False if not

CLI Example:

salt '*' poudriere.is_jail <jail name>

salt.modules.poudriere.list_jails()

Return a list of current jails managed by poudriere

CLI Example:

salt '*' poudriere.list_jails

salt.modules.poudriere.list_ports()

Return a list of current port trees managed by poudriere

CLI Example:

salt '*' poudriere.list_ports

salt.modules.poudriere.make_pkgng_aware(jname)

Make jail jname pkgng aware

CLI Example:

salt '*' poudriere.make_pkgng_aware <jail name>

salt.modules.poudriere.parse_config(config_file=None)

Returns a dict of poudriere main configuration defintions

CLI Example:

salt '*' poudriere.parse_config

salt.modules.poudriere.version()

Return poudriere version

CLI Example:

salt '*' poudriere.version

salt.modules.ps

A salt interface to psutil, a system and process library. See http://code.google.com/p/psutil.

depends

• psutil Python module

salt.modules.ps.boot_time()

Return the boot time in number of seconds since the epoch began.

CLI Example:

salt '*' ps.boot_time

salt.modules.ps.cached_physical_memory()

Return the amount cached memory.

CLI Example:

salt '*' ps.cached_physical_memory

salt.modules.ps.cpu_percent(interval=0.1, per_cpu=False)

Return the percent of time the CPU is busy.

interval

the number of seconds to sample CPU usage over

per_cpu

if True return an array of CPU percent busy for each CPU, otherwise aggregate all percents into one number

CLI Example:

salt '*' ps.cpu_percent

salt.modules.ps.cpu_times(per_cpu=False)

Return the percent of time the CPU spends in each state, e.g. user, system, idle, nice, iowait, irq, softirq.

per_cpu

if True return an array of percents for each CPU, otherwise aggregate all percents into one number

CLI Example:

salt '*' ps.cpu_times

salt.modules.ps.disk_io_counters()

Return disk I/O statisitics.

CLI Example:

salt '*' ps.disk_io_counters

salt.modules.ps.disk_partition_usage(all=False)

Return a list of disk partitions plus the mount point, filesystem and usage statistics.

CLI Example:

salt '*' ps.disk_partition_usage

salt.modules.ps.disk_partitions(all=False)

Return a list of disk partitions and their device, mount point, and filesystem type.

all

if set to False, only return local, physical partitions (hard disk, USB, CD/DVD partitions). If True, return all filesystems.

CLI Example:

salt '*' ps.disk_partitions

salt.modules.ps.disk_usage(path)

Given a path, return a dict listing the total available space as well as the free space, and used space.

CLI Example:

salt '*' ps.disk_usage /home

salt.modules.ps.get_pid_list()

Return a list of process ids (PIDs) for all running processes.

CLI Example:

salt '*' ps.get_pid_list

salt.modules.ps.network_io_counters()

Return network I/O statisitics.

CLI Example:

salt '*' ps.network_io_counters

salt.modules.ps.num_cpus()

Return the number of CPUs.

CLI Example:

salt '*' ps.num_cpus

salt.modules.ps.physical_memory_buffers()

Return the amount of physical memory buffers.

CLI Example:

salt '*' ps.physical_memory_buffers

salt.modules.ps.physical_memory_usage()

Return a dict that describes free and available physical memory.

CLI Examples:

salt '*' ps.physical_memory_usage

salt.modules.ps.top(num_processes=5, interval=3)

Return a list of top CPU consuming processes during the interval. num_processes = return the top N CPU consuming processes interval = the number of seconds to sample CPU usage over

CLI Examples:

salt '*' ps.top

salt '*' ps.top 5 10

salt.modules.ps.total_physical_memory()

Return the total number of bytes of physical memory.

CLI Example:

salt '*' ps.total_physical_memory

salt.modules.ps.virtual_memory_usage()

Return a dict that describes free and available memory, both physical and virtual.

CLI Example:

salt '*' ps.virtual_memory_usage

salt.modules.publish

Publish a command from a minion to a target

salt.modules.publish.full_data(tgt, fun, arg=None, expr_form='glob', returner='', timeout=5)

Return the full data about the publication, this is invoked in the same way as the publish function

CLI Example:

salt system.example.com publish.full_data '*' cmd.run 'ls -la /tmp'

salt.modules.publish.publish(tgt, fun, arg=None, expr_form='glob', returner='', timeout=5)

Publish a command from the minion out to other minions, publications need to be enabled on the Salt master and the minion needs to have permission to publish the command. The Salt master will also prevent a recursive publication loop, this means that a minion cannot command another minion to command another minion as that would create an infinite command loop.

The expr_form argument is used to pass a target other than a glob into the execution, the available options are: glob pcre grain grain_pcre pillar ipcidr range compound

The arguments sent to the minion publish function are separated with commas. This means that for a minion executing a command with multiple args it will look like this:

salt system.example.com publish.publish '*' user.add 'foo,1020,1020'
salt system.example.com publish.publish 'os:Fedora' network.interfaces '' grain

CLI Example:

salt system.example.com publish.publish '*' cmd.run 'ls -la /tmp'

salt.modules.publish.runner(fun, arg=None)

Execute a runner on the master and return the data from the runner function

CLI Example:

salt publish.runner manage.down

salt.modules.puppet

Execute puppet routines

salt.modules.puppet.fact(name)

Run facter for a specific fact

CLI Example:

salt '*' puppet.fact kernel

salt.modules.puppet.facts()

Run facter and return the results

CLI Example:

salt '*' puppet.facts

salt.modules.puppet.noop(*args, **kwargs)

Execute a puppet noop run and return a dict with the stderr, stdout, return code, etc. Usage is the same as for puppet.run.

CLI Example:

salt '*' puppet.noop

salt '*' puppet.noop tags=basefiles::edit,apache::server

salt '*' puppet.noop debug

salt '*' puppet.noop apply /a/b/manifest.pp modulepath=/a/b/modules tags=basefiles::edit,apache::server

salt.modules.puppet.run(*args, **kwargs)

Execute a puppet run and return a dict with the stderr, stdout, return code, etc. The first positional argument given is checked as a subcommand. Following positional arguments should be ordered with arguments required by the subcommand first, followed by non-keyvalue pair options. Tags are specified by a tag keyword and comma separated list of values. -- http://projects.puppetlabs.com/projects/1/wiki/Using_Tags

CLI Examples:

salt '*' puppet.run

salt '*' puppet.run tags=basefiles::edit,apache::server

salt '*' puppet.run debug

salt '*' puppet.run apply /a/b/manifest.pp modulepath=/a/b/modules tags=basefiles::edit,apache::server

salt.modules.pw_group

Manage groups on FreeBSD

salt.modules.pw_group.add(name, gid=None, system=False)

Add the specified group

CLI Example:

salt '*' group.add foo 3456

salt.modules.pw_group.chgid(name, gid)

Change the gid for a named group

CLI Example:

salt '*' group.chgid foo 4376

salt.modules.pw_group.delete(name)

Remove the named group

CLI Example:

salt '*' group.delete foo

salt.modules.pw_group.getent()

Return info on all groups

CLI Example:

salt '*' group.getent

salt.modules.pw_group.info(name)

Return information about a group

CLI Example:

salt '*' group.info foo

salt.modules.pw_user

Manage users with the useradd command

salt.modules.pw_user.add(name, uid=None, gid=None, groups=None, home=True, shell=None, unique=True, system=False, fullname='', roomnumber='', workphone='', homephone='', **kwargs)

Add a user to the minion

CLI Example:

salt '*' user.add name <uid> <gid> <groups> <home> <shell>

salt.modules.pw_user.chfullname(name, fullname)

Change the user's Full Name

CLI Example:

salt '*' user.chfullname foo "Foo Bar"

salt.modules.pw_user.chgid(name, gid)

Change the default group of the user

CLI Example:

salt '*' user.chgid foo 4376

salt.modules.pw_user.chgroups(name, groups, append=False)

Change the groups this user belongs to, add append to append the specified groups

CLI Example:

salt '*' user.chgroups foo wheel,root True

salt.modules.pw_user.chhome(name, home, persist=False)

Change the home directory of the user, pass true for persist to copy files to the new home dir

CLI Example:

salt '*' user.chhome foo /home/users/foo True

salt.modules.pw_user.chhomephone(name, homephone)

Change the user's Home Phone

CLI Example:

salt '*' user.chhomephone foo "7735551234"

salt.modules.pw_user.chroomnumber(name, roomnumber)

Change the user's Room Number

CLI Example:

salt '*' user.chroomnumber foo 123

salt.modules.pw_user.chshell(name, shell)

Change the default shell of the user

CLI Example:

salt '*' user.chshell foo /bin/zsh

salt.modules.pw_user.chuid(name, uid)

Change the uid for a named user

CLI Example:

salt '*' user.chuid foo 4376

salt.modules.pw_user.chworkphone(name, workphone)

Change the user's Work Phone

CLI Example:

salt '*' user.chworkphone foo "7735550123"

salt.modules.pw_user.delete(name, remove=False, force=False)

Remove a user from the minion

CLI Example:

salt '*' user.delete name remove=True force=True

salt.modules.pw_user.getent()

Return the list of all info for all users

CLI Example:

salt '*' user.getent

salt.modules.pw_user.info(name)

Return user information

CLI Example:

salt '*' user.info root

salt.modules.pw_user.list_groups(name)

Return a list of groups the named user belongs to

CLI Example:

salt '*' user.list_groups foo

salt.modules.rabbitmq

Module to provide RabbitMQ compatibility to Salt. Todo: A lot, need to add cluster support, logging, and minion configuration data.

salt.modules.rabbitmq.add_user(name, password, runas=None)

Add a rabbitMQ user via rabbitmqctl user_add <user> <password>

CLI Example:

salt '*' rabbitmq.add_user rabbit_user password

salt.modules.rabbitmq.add_vhost(vhost, runas=None)

Adds a vhost via rabbitmqctl add_vhost.

CLI Example:

salt '*' rabbitmq add_vhost '<vhost_name>'

salt.modules.rabbitmq.change_password(name, password, runas=None)

Changes a user's password.

CLI Example:

salt '*' rabbitmq.change_password rabbit_user password

salt.modules.rabbitmq.clear_password(name, runas=None)

Removes a user's password.

CLI Example:

salt '*' rabbitmq.clear_password rabbit_user

salt.modules.rabbitmq.delete_user(name, runas=None)

Deletes a user via rabbitmqctl delete_user.

CLI Example:

salt '*' rabbitmq.delete_user rabbit_user

salt.modules.rabbitmq.delete_vhost(vhost, runas=None)

Deletes a vhost rabbitmqctl delete_vhost.

CLI Example:

salt '*' rabbitmq.delete_vhost '<vhost_name>'

salt.modules.rabbitmq.list_user_permissions(name, user=None)

List permissions for a user via rabbitmqctl list_user_permissions

Example:

salt '*' rabbitmq.list_user_permissions 'user'.

salt.modules.rabbitmq.list_users(runas=None)

Return a list of users based off of rabbitmqctl user_list.

CLI Example:

salt '*' rabbitmq.list_users

salt.modules.rabbitmq.list_vhosts(runas=None)

Return a list of vhost based of of rabbitmqctl list_vhosts.

CLI Example:

salt '*' rabbitmq.list_vhosts

salt.modules.rabbitmq.set_permissions(vhost, user, conf='.*', write='.*', read='.*', runas=None)

Sets permissions for vhost via rabbitmqctl set_permissions

CLI Example:

salt '*' rabbitmq.set_permissions 'myvhost' 'myuser'

salt.modules.rabbitmq.user_exists(name, runas=None)

Return whether the user exists based on rabbitmqctl list_users.

CLI Example:

salt '*' rabbitmq.user_exists rabbit_user

salt.modules.rabbitmq.vhost_exists(name, runas=None)

Return whether the vhost exists based on rabbitmqctl list_vhosts.

CLI Example:

salt '*' rabbitmq.vhost_exists rabbit_host

salt.modules.reg

Manage the registry on Windows

depends

• winreg Python module

class salt.modules.reg.Registry

Delay '_winreg' usage until this module is used

salt.modules.reg.create_key(hkey, path, key, value=None)

Create a registry key

CLI Example:

salt '*' reg.create_key HKEY_CURRENT_USER 'SOFTWARE\Salt' 'version' '0.97'

salt.modules.reg.delete_key(hkey, path, key)

Delete a registry key

Note: This cannot delete a key with subkeys

CLI Example:

salt '*' reg.delete_key HKEY_CURRENT_USER 'SOFTWARE\Salt' 'version'

salt.modules.reg.read_key(hkey, path, key)

Read registry key value

CLI Example:

salt '*' reg.read_key HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version'

salt.modules.reg.set_key(hkey, path, key, value)

Set a registry key

CLI Example:

salt '*' reg.set_key HKEY_CURRENT_USER 'SOFTWARE\Salt' 'version' '0.97'

salt.modules.ret

Module to integrate with the returner system and retrieve data sent to a salt returner.

salt.modules.ret.get_fun(returner, fun)

Return info about last time fun was called on each minion

CLI Example:

salt '*' ret.get_fun mysql network.interfaces

salt.modules.ret.get_jid(returner, jid)

Return the information for a specified job id

CLI Example:

salt '*' ret.get_jid redis 20421104181954700505

salt.modules.ret.get_jids(returner)

Return a list of all job ids

CLI Example:

salt '*' ret.get_jids mysql

salt.modules.ret.get_minions(returner)

Return a list of all minions

CLI Example:

salt '*' ret.get_minions mysql

salt.modules.rh_ip

The networking module for RHEL/Fedora based distros

salt.modules.rh_ip.apply_network_settings(opts)

Apply global network configuration.

CLI Example:

salt '*' ip.apply_network_settings

salt.modules.rh_ip.build_bond(iface, settings)

Create a bond script in /etc/modprobe.d with the passed settings and load the bonding kernel module.

CLI Example:

salt '*' ip.build_bond bond0 mode=balance-alb

salt.modules.rh_ip.build_interface(iface, iface_type, enabled, settings)

Build an interface script for a network interface.

CLI Example:

salt '*' ip.build_interface eth0 eth <settings>

salt.modules.rh_ip.build_network_settings(settings)

Build the global network script.

CLI Example:

salt '*' ip.build_network_settings <settings>

salt.modules.rh_ip.down(iface, iface_type, opts)

Shutdown a network interface

CLI Example:

salt '*' ip.down eth0

salt.modules.rh_ip.get_bond(iface)

Return the content of a bond script

CLI Example:

salt '*' ip.get_bond bond0

salt.modules.rh_ip.get_interface(iface)

Return the contents of an interface script

CLI Example:

salt '*' ip.get_interface eth0

salt.modules.rh_ip.get_network_settings()

Return the contents of the global network script.

CLI Example:

salt '*' ip.get_network_settings

salt.modules.rh_ip.up(iface, iface_type, opts)

Start up a network interface

CLI Example:

salt '*' ip.up eth0

salt.modules.rh_service

Service support for classic Red Hat type systems. This interface uses the service command (so it is compatible with upstart systems) and the chkconfig command.

salt.modules.rh_service.disable(name, **kwargs)

Disable the named service to start at boot

CLI Example:

salt '*' service.disable <service name>

salt.modules.rh_service.disabled(name)

Check to see if the named service is disabled to start on boot

CLI Example:

salt '*' service.disabled <service name>

salt.modules.rh_service.enable(name, **kwargs)

Enable the named service to start at boot

CLI Example:

salt '*' service.enable <service name>

salt.modules.rh_service.enabled(name)

Check to see if the named service is enabled to start on boot

CLI Example:

salt '*' service.enabled <service name>

salt.modules.rh_service.get_all()

Return all installed services

CLI Example:

salt '*' service.get_all

salt.modules.rh_service.get_disabled()

Return the disabled services

CLI Example:

salt '*' service.get_disabled

salt.modules.rh_service.get_enabled()

Return the enabled services

CLI Example:

salt '*' service.get_enabled

salt.modules.rh_service.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.rh_service.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.rh_service.status(name, sig=None)

Return the status for a service, returns a bool whether the service is running.

CLI Example:

salt '*' service.status <service name>

salt.modules.rh_service.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.rvm

Manage ruby installations and gemsets with RVM, the Ruby Version Manager.
salt.modules.rvm.do(ruby, command, runas=None): Execute a command in an RVM controlled environment.; ruby:
The ruby to use.; command:

The command to execute.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.do 2.0.0 <command>

salt.modules.rvm.gemset_copy(source, destination, runas=None)

Copy all gems from one gemset to another.

source

The name of the gemset to copy, complete with ruby version.

destination

The destination gemset.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.gemset_copy foobar bazquo

salt.modules.rvm.gemset_create(ruby, gemset, runas=None)

Creates a gemset.

ruby

The ruby version to create the gemset for.

gemset

The name of the gemset to create.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.gemset_create 2.0.0 foobar

salt.modules.rvm.gemset_delete(ruby, gemset, runas=None)

Deletes a gemset.

ruby

The ruby version the gemset belongs to.

gemset

The gemset to delete.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.gemset_delete 2.0.0 foobar

salt.modules.rvm.gemset_empty(ruby, gemset, runas=None)

Remove all gems from a gemset.

ruby

The ruby version the gemset belongs to.

gemset

The gemset to empty.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.gemset_empty 2.0.0 foobar

salt.modules.rvm.gemset_list(ruby='default', runas=None)

List all gemsets for the given ruby.

ruby

default The ruby version to list the gemsets for

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.gemset_list

salt.modules.rvm.gemset_list_all(runas=None)

List all gemsets for all installed rubies.

Note that you must have set a default ruby before this can work.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.gemset_list_all

salt.modules.rvm.get(version='stable', runas=None)

Update RVM.

version

stable Which version of RVM to install, e.g. stable or head.

ruby

The version of ruby to reinstall.

CLI Example:

salt '*' rvm.get

salt.modules.rvm.install()

Install RVM system wide.

CLI Example:

salt '*' rvm.install

salt.modules.rvm.install_ruby(ruby, runas=None)

Install a ruby implementation.

ruby

The version of ruby to install.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.install_ruby 1.9.3-p385

salt.modules.rvm.is_installed()

Check if RVM is installed.

CLI Example:

salt '*' rvm.is_installed

salt.modules.rvm.list(runas=None)

List all rvm installed rubies.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.list

salt.modules.rvm.reinstall_ruby(ruby, runas=None)

Reinstall a ruby implementation.

ruby

The version of ruby to reinstall.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.reinstall_ruby 1.9.3-p385

salt.modules.rvm.rubygems(ruby, version, runas=None)

Installs a specific rubygems version in the given ruby.

ruby

The ruby to install rubygems for.

version

The version of rubygems to install or 'remove' to use the version that ships with 1.9

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.rubygems 2.0.0 1.8.24

salt.modules.rvm.set_default(ruby, runas=None)

Set the default ruby.

ruby

The version of ruby to make the default.

runas

None The user to run rvm as.

CLI Example:

salt '*' rvm.set_default 2.0.0

salt.modules.rvm.wrapper(ruby_string, wrapper_prefix, runas=None, *binaries)

Install RVM wrapper scripts.

ruby_string

Ruby/gemset to install wrappers for.

wrapper_prefix

What to prepend to the name of the generated wrapper binaries.

runas

None The user to run rvm as.

binaries

None The names of the binaries to create wrappers for. When nothing is given, wrappers for ruby, gem, rake, irb, rdoc, ri and testrb are generated.

CLI Example:

salt '*' rvm.wrapper <ruby_string> <wrapper_prefix>

salt.modules.saltutil

The Saltutil module is used to manage the state of the salt minion itself. It is used to manage minion modules as well as automate updates to the salt minion

depends

• esky Python module for update functionality

salt.modules.saltutil.find_job(jid)

Return the data for a specific job id

CLI Example:

salt '*' saltutil.find_job <job id>

salt.modules.saltutil.is_running(fun)

If the named function is running return the data associated with it/them. The argument can be a glob

CLI Example:

salt '*' saltutil.is_running state.highstate

salt.modules.saltutil.kill_job(jid)

Sends a kill signal (SIGKILL 9) to the named salt job's process

CLI Example:

salt '*' saltutil.kill_job <job id>

salt.modules.saltutil.refresh_pillar()

Queue the minion to refresh the pillar data.

CLI Example:

salt '*' saltutil.refresh_pillar

salt.modules.saltutil.running()

Return the data on all running salt processes on the minion

CLI Example:

salt '*' saltutil.running

salt.modules.saltutil.signal_job(jid, sig)

Sends a signal to the named salt job's process

CLI Example:

salt '*' saltutil.signal_job <job id> 15

salt.modules.saltutil.sync_all(env=None)

Sync down all of the dynamic modules from the file server for a specific environment

CLI Example:

salt '*' saltutil.sync_all

salt.modules.saltutil.sync_grains(env=None)

Sync the grains from the _grains directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _grains directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_grains

salt.modules.saltutil.sync_modules(env=None)

Sync the modules from the _modules directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _modules directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_modules

salt.modules.saltutil.sync_outputters(env=None)

Sync the outputters from the _outputters directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _outputters directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_outputters

salt.modules.saltutil.sync_renderers(env=None)

Sync the renderers from the _renderers directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _renderers directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_renderers

salt.modules.saltutil.sync_returners(env=None)

Sync the returners from the _returners directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _returners directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_returners

salt.modules.saltutil.sync_states(env=None)

Sync the states from the _states directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _states directory, base is the default environment.

CLI Example:

salt '*' saltutil.sync_states

salt.modules.saltutil.term_job(jid)

Sends a termination signal (SIGTERM 15) to the named salt job's process

CLI Example:

salt '*' saltutil.term_job <job id>

salt.modules.saltutil.update(version=None)

Update the salt minion from the url defined in opts['update_url']

This feature requires the minion to be running a bdist_esky build.

The version number is optional and will default to the most recent version available at opts['update_url'].

Returns details about the transaction upon completion.

CLI Example:

salt '*' saltutil.update 0.10.3

salt.modules.selinux

Execute calls on selinux

salt.modules.selinux.getenforce()

Return the mode selinux is running in

CLI Example:

salt '*' selinux.getenforce

salt.modules.selinux.getsebool(boolean)

Return the information on a specific selinux boolean

CLI Example:

salt '*' selinux.getsebool virt_use_usb

salt.modules.selinux.list_sebool()

Return a structure listing all of the selinux booleans on the system and what state they are in

CLI Example:

salt '*' selinux.list_sebool

salt.modules.selinux.setenforce(mode)

Set the SELinux enforcing mode

CLI Example:

salt '*' selinux.setenforce enforcing

salt.modules.selinux.setsebool(boolean, value, persist=False)

Set the value for a boolean

CLI Example:

salt '*' selinux.setsebool virt_use_usb off

salt.modules.selinux.setsebools(pairs, persist=False)

Set the value of multiple booleans

CLI Example:

salt '*' selinux.setsebools '{virt_use_usb: on, squid_use_tproxy: off}'

salt.modules.service

The default service module, if not otherwise specified salt will fall back to this basic module

salt.modules.service.reload(name)

Restart the named service

CLI Example:

salt '*' service.reload <service name>

salt.modules.service.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.service.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.service.status(name, sig=None)

Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps

CLI Example:

salt '*' service.status <service name> [service signature]

salt.modules.service.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.shadow

Manage the shadow file

salt.modules.shadow.info(name)

Return information for the specified user

CLI Example:

salt '*' shadow.info root

salt.modules.shadow.set_date(name, date)

sets the value for the date the password was last changed to the epoch (January 1, 1970). See man chage.

CLI Example:

salt '*' shadow.set_date username 0

salt.modules.shadow.set_inactdays(name, inactdays)

Set the number of days of inactivity after a password has expired before the account is locked. See man chage.

CLI Example:

salt '*' shadow.set_inactdays username 7

salt.modules.shadow.set_maxdays(name, maxdays)

Set the maximum number of days during which a password is valid. See man chage.

CLI Example:

salt '*' shadow.set_maxdays username 90

salt.modules.shadow.set_mindays(name, mindays)

Set the minimum number of days between password changes. See man chage.

CLI Example:

salt '*' shadow.set_mindays username 7

salt.modules.shadow.set_password(name, password)

Set the password for a named user. The password must be a properly defined hash, the password hash can be generated with this command: python -c "import crypt, getpass, pwd; print crypt.crypt('password', '\$6\$SALTsalt\$')" Keep in mind that the $6 represents a sha512 hash, if your OS is using a different hashing algorithm this needs to be changed accordingly

CLI Example:

salt '*' shadow.set_password root $1$UYCIxa628.9qXjpQCjM4a..

salt.modules.shadow.set_warndays(name, warndays)

Set the number of days of warning before a password change is required. See man chage.

CLI Example:

salt '*' shadow.set_warndays username 7

salt.modules.smf

Service support for Solaris 10 and 11, should work with other systems that use SMF also. (e.g. SmartOS)

salt.modules.smf.disable(name, **kwargs)

Disable the named service to start at boot

CLI Example:

salt '*' service.disable <service name>

salt.modules.smf.disabled(name)

Check to see if the named service is disabled to start on boot

CLI Example:

salt '*' service.disabled <service name>

salt.modules.smf.enable(name, **kwargs)

Enable the named service to start at boot

CLI Example:

salt '*' service.enable <service name>

salt.modules.smf.enabled(name)

Check to see if the named service is enabled to start on boot

CLI Example:

salt '*' service.enabled <service name>

salt.modules.smf.get_all()

Return all installed services

CLI Example:

salt '*' service.get_all

salt.modules.smf.get_disabled()

Return the disabled services

CLI Example:

salt '*' service.get_disabled

salt.modules.smf.get_enabled()

Return the enabled services

CLI Example:

salt '*' service.get_enabled

salt.modules.smf.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.smf.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.smf.status(name, sig=None)

Return the status for a service, returns a bool whether the service is running.

CLI Example:

salt '*' service.status <service name>

salt.modules.smf.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.solaris_group

Manage groups on Solaris

salt.modules.solaris_group.add(name, gid=None, system=False)

Add the specified group

CLI Example:

salt '*' group.add foo 3456

salt.modules.solaris_group.chgid(name, gid)

Change the gid for a named group

CLI Example:

salt '*' group.chgid foo 4376

salt.modules.solaris_group.delete(name)

Remove the named group

CLI Example:

salt '*' group.delete foo

salt.modules.solaris_group.getent()

Return info on all groups

CLI Example:

salt '*' group.getent

salt.modules.solaris_group.info(name)

Return information about a group

CLI Example:

salt '*' group.info foo

salt.modules.solarispkg

Package support for Solaris

salt.modules.solarispkg.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

NOTE: As package repositories are not presently supported for Solaris pkgadd, this function will always return an empty string for a given package.

salt.modules.solarispkg.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.solarispkg.install(name=None, refresh=False, sources=None, **kwargs)

Install the passed package. Can install packages from the following sources:

* Locally (package already exists on the minion
* HTTP/HTTPS server
* FTP server
* Salt master

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example, installing a datastream pkg that already exists on the minion:

salt '*' pkg.install sources='[{"<pkg name>": "/dir/on/minion/<pkg filename>"}]'
salt '*' pkg.install sources='[{"SMClgcc346": "/var/spool/pkg/gcc-3.4.6-sol10-sparc-local.pkg"}]'

CLI Example, installing a datastream pkg that exists on the salt master:

salt '*' pkg.install sources='[{"<pkg name>": "salt://pkgs/<pkg filename>"}]'
salt '*' pkg.install sources='[{"SMClgcc346": "salt://pkgs/gcc-3.4.6-sol10-sparc-local.pkg"}]'

CLI Example, installing a datastream pkg that exists on a HTTP server:

salt '*' pkg.install sources='[{"<pkg name>": "http://packages.server.com/<pkg filename>"}]'
salt '*' pkg.install sources='[{"SMClgcc346": "http://packages.server.com/gcc-3.4.6-sol10-sparc-local.pkg"}]'

If working with solaris zones and you want to install a package only in the global zone you can pass 'current_zone_only=True' to salt to have the package only installed in the global zone. (Behind the scenes this is passing '-G' to the pkgadd command.) Solaris default when installing a package in the global zone is to install it in all zones. This overrides that and installs the package only in the global.

CLI Example, installing a datastream package only in the global zone:

salt 'global_zone' pkg.install sources='[{"SMClgcc346": "/var/spool/pkg/gcc-3.4.6-sol10-sparc-local.pkg"}]' current_zone_only=True

By default salt automatically provides an adminfile, to automate package installation, with these options set:

email= instance=quit partial=nocheck runlevel=nocheck idepend=nocheck rdepend=nocheck space=nocheck setuid=nocheck conflict=nocheck action=nocheck basedir=default

You can override any of these options in two ways. First you can optionally pass any of the options as a kwarg to the module/state to override the default value or you can optionally pass the 'admin_source' option providing your own adminfile to the minions.

Note: You can find all of the possible options to provide to the adminfile by reading the admin man page:

man -s 4 admin

CLI Example - Overriding the 'instance' adminfile option when calling the module directly:

salt '*' pkg.install sources='[{"<pkg name>": "salt://pkgs/<pkg filename>"}]' instance="overwrite"

CLI Example - Overriding the 'instance' adminfile option when used in a state:

SMClgcc346:
  pkg.installed:
    - sources:
      - SMClgcc346: salt://srv/salt/pkgs/gcc-3.4.6-sol10-sparc-local.pkg
    - instance: overwrite

Note: the ID declaration is ignored, as the package name is read from the "sources" parameter.

CLI Example - Providing your own adminfile when calling the module directly:

salt '*' pkg.install sources='[{"<pkg name>": "salt://pkgs/<pkg filename>"}]' admin_source='salt://pkgs/<adminfile filename>'

CLI Example - Providing your own adminfile when using states:

<pkg name>:
  pkg.installed:
    - sources:
      - <pkg name>: salt://pkgs/<pkg filename>
    - admin_source: salt://pkgs/<adminfile filename>

Note: the ID declaration is ignored, as the package name is read from the "sources" parameter.

salt.modules.solarispkg.list_pkgs()

List the packages currently installed as a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.solarispkg.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.solarispkg.purge(name, **kwargs)

Remove a single package with pkgrm

Returns a list containing the removed packages.

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.solarispkg.remove(name, **kwargs)

Remove a single package with pkgrm

By default salt automatically provides an adminfile, to automate package removal, with these options set:

email=
instance=quit
partial=nocheck
runlevel=nocheck
idepend=nocheck
rdepend=nocheck
space=nocheck
setuid=nocheck
conflict=nocheck
action=nocheck
basedir=default

Note: You can find all of the possible options to provide to the adminfile by reading the admin man page:

man -s 4 admin

CLI Example:

salt '*' pkg.remove <package name>
salt '*' pkg.remove SUNWgit

salt.modules.solarispkg.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.solarispkg.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

salt.modules.solaris_shadow

Manage the shadow file

salt.modules.solaris_shadow.info(name)

Return information for the specified user

CLI Example:

salt '*' shadow.info root

salt.modules.solaris_shadow.set_maxdays(name, maxdays)

Set the maximum number of days during which a password is valid. See man passwd.

CLI Example:

salt '*' shadow.set_maxdays username 90

salt.modules.solaris_shadow.set_mindays(name, mindays)

Set the minimum number of days between password changes. See man passwd.

CLI Example:

salt '*' shadow.set_mindays username 7

salt.modules.solaris_shadow.set_password(name, password)

Set the password for a named user. The password must be a properly defined hash, the password hash can be generated with this command: openssl passwd -1 <plaintext password>

CLI Example:

salt '*' shadow.set_password root $1$UYCIxa628.9qXjpQCjM4a..

salt.modules.solaris_shadow.set_warndays(name, warndays)

Set the number of days of warning before a password change is required. See man passwd.

CLI Example:

salt '*' shadow.set_warndays username 7

salt.modules.solaris_user

Manage users with the useradd command

salt.modules.solaris_user.add(name, uid=None, gid=None, groups=None, home=True, shell=None, unique=True, system=False, fullname='', roomnumber='', workphone='', homephone='')

Add a user to the minion

CLI Example:

salt '*' user.add name <uid> <gid> <groups> <home> <shell>

salt.modules.solaris_user.chfullname(name, fullname)

Change the user's Full Name

CLI Example:

salt '*' user.chfullname foo "Foo Bar"

salt.modules.solaris_user.chgid(name, gid)

Change the default group of the user

CLI Example:

salt '*' user.chgid foo 4376

salt.modules.solaris_user.chgroups(name, groups, append=False)

Change the groups this user belongs to, add append to append the specified groups

CLI Example:

salt '*' user.chgroups foo wheel,root True

salt.modules.solaris_user.chhome(name, home, persist=False)

Change the home directory of the user, pass true for persist to copy files to the new home dir

CLI Example:

salt '*' user.chhome foo /home/users/foo True

salt.modules.solaris_user.chhomephone(name, homephone)

Change the user's Home Phone

CLI Example:

salt '*' user.chhomephone foo "7735551234"

salt.modules.solaris_user.chroomnumber(name, roomnumber)

Change the user's Room Number

CLI Example:

salt '*' user.chroomnumber foo 123

salt.modules.solaris_user.chshell(name, shell)

Change the default shell of the user

CLI Example:

salt '*' user.chshell foo /bin/zsh

salt.modules.solaris_user.chuid(name, uid)

Change the uid for a named user

CLI Example:

salt '*' user.chuid foo 4376

salt.modules.solaris_user.chworkphone(name, workphone)

Change the user's Work Phone

CLI Example:

salt '*' user.chworkphone foo "7735550123"

salt.modules.solaris_user.delete(name, remove=False, force=False)

Remove a user from the minion

CLI Example:

salt '*' user.delete name remove=True force=True

salt.modules.solaris_user.getent()

Return the list of all info for all users

CLI Example:

salt '*' user.getent

salt.modules.solaris_user.info(name)

Return user information

CLI Example:

salt '*' user.info root

salt.modules.solaris_user.list_groups(name)

Return a list of groups the named user belongs to

CLI Example:

salt '*' user.list_groups foo

salt.modules.solr

Apache Solr Salt Module

Author: Jed Glazner Version: 0.2.1 Modified: 12/09/2011 This module uses http requests to talk to the apache solr request handlers to gather information and report errors. Because of this the minion doesn't necessarily need to reside on the actual slave. However if you want to use the signal function the minion must reside on the physical solr host. This module supports multi-core and standard setups. Certain methods are master/slave specific. Make sure you set the solr.type. If you have questions or want a feature request please ask.

Coming Features in 0.3

1. Add command for checking for replication failures on slaves 2. Improve match_index_versions since it's pointless on busy solr masters 3. Add additional local fs checks for backups to make sure they succeeded

Override these in the minion config

solr.cores: A list of core names eg ['core1','core2']. An empty list indicates non-multicore setup.
solr.baseurl: The root level url to access solr via http
solr.request_timeout: The number of seconds before timing out an http/https/ftp request. If nothing is specified then the python global timeout setting is used.
solr.type: Possible values are 'master' or 'slave'
solr.backup_path: The path to store your backups. If you are using cores and you can specify to append the core name to the path in the backup method.
solr.num_backups: For versions of solr >= 3.5. Indicates the number of backups to keep. This option is ignored if your version is less.
solr.init_script: The full path to your init script with start/stop options
solr.dih.options: A list of options to pass to the dih.

Required Options for DIH

clean
False Clear the index before importing
commit
True Commit the documents to the index upon completion
optimize: True Optimize the index after commit is complete
verbose: True Get verbose output
salt.modules.solr.abort_import(handler, host=None, core_name=None, verbose=False): MASTER ONLY Aborts an existing import command to the specified handler. This command can only be run if the minion is is configured with solr.type=master; handler

str The name of the data import handler.

host

str (None) The solr host to query. __opts__['host'] is default.

core

str (None) The core the handler belongs to.

verbose

boolean (False) Run the command with verbose output.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.abort_import dataimport None music {'clean':True}

salt.modules.solr.backup(host=None, core_name=None, append_core_to_path=False)

Tell solr make a backup. This method can be mis-leading since it uses the backup api. If an error happens during the backup you are not notified. The status: 'OK' in the response simply means that solr received the request successfully.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

append_core_to_path

boolean (False) If True add the name of the core to the backup path. Assumes that minion backup path is not None.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.backup music

salt.modules.solr.core_status(host=None, core_name=None)

MULTI-CORE HOSTS ONLY Get the status for a given core or all cores if no core is specified

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str The name of the core to reload

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.core_status None music

salt.modules.solr.delta_import(handler, host=None, core_name=None, options=None, extra=None)

Submits an import command to the specified handler using specified options. This command can only be run if the minion is is configured with solr.type=master

handler

str The name of the data import handler.

host

str (None) The solr host to query. __opts__['host'] is default.

core

str (None) The core the handler belongs to.

options

dict (__opts__) A list of options such as clean, optimize commit, verbose, and pause_replication. leave blank to use __opts__ defaults. options will be merged with __opts__

extra

dict ([]) Extra name value pairs to pass to the handler. eg ["name=value"]

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.delta_import dataimport None music {'clean':True}

salt.modules.solr.full_import(handler, host=None, core_name=None, options=None, extra=None)

MASTER ONLY Submits an import command to the specified handler using specified options. This command can only be run if the minion is is configured with solr.type=master

handler

str The name of the data import handler.

host

str (None) The solr host to query. __opts__['host'] is default.

core

str (None) The core the handler belongs to.

options

dict (__opts__) A list of options such as clean, optimize commit, verbose, and pause_replication. leave blank to use __opts__ defaults. options will be merged with __opts__

extra

dict ([]) Extra name value pairs to pass to the handler. e.g. ["name=value"]

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.full_import dataimport None music {'clean':True}

salt.modules.solr.import_status(handler, host=None, core_name=None, verbose=False)

Submits an import command to the specified handler using specified options. This command can only be run if the minion is is configured with solr.type: 'master'

handler

str The name of the data import handler.

host

str (None) The solr host to query. __opts__['host'] is default.

core

str (None) The core the handler belongs to.

verbose

boolean (False) Specifies verbose output

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.import_status dataimport None music False

salt.modules.solr.is_replication_enabled(host=None, core_name=None)

SLAVE CALL Check for errors, and determine if a slave is replicating or not.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.is_replication_enabled music

salt.modules.solr.lucene_version(core_name=None)

Gets the lucene version that solr is using. If you are running a multi-core setup you should specify a core name since all the cores run under the same servlet container, they will all have the same version.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return: dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.lucene_version

salt.modules.solr.match_index_versions(host=None, core_name=None)

SLAVE CALL Verifies that the master and the slave versions are in sync by comparing the index version. If you are constantly pushing updates the index the master and slave versions will seldom match. A solution to this is pause indexing every so often to allow the slave to replicate and then call this method before allowing indexing to resume.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.match_index_versions music

salt.modules.solr.optimize(host=None, core_name=None)

Search queries fast, but it is a very expensive operation. The ideal process is to run this with a master/slave configuration. Then you can optimize the master, and push the optimized index to the slaves. If you are running a single solr instance, or if you are going to run this on a slave be aware than search performance will be horrible while this command is being run. Additionally it can take a LONG time to run and your http request may timeout. If that happens adjust your timeout settings.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.optimize music

salt.modules.solr.ping(host=None, core_name=None)

Does a health check on solr, makes sure solr can talk to the indexes.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.ping music

salt.modules.solr.reload_core(host=None, core_name=None)

MULTI-CORE HOSTS ONLY Load a new core from the same configuration as an existing registered core. While the "new" core is initializing, the "old" one will continue to accept requests. Once it has finished, all new request will go to the "new" core, and the "old" core will be unloaded.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str The name of the core to reload

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.reload_core None music

{'success':bool, 'data':dict, 'errors':list, 'warnings':list}

salt.modules.solr.reload_import_config(handler, host=None, core_name=None, verbose=False)

MASTER ONLY re-loads the handler config XML file. This command can only be run if the minion is a 'master' type

handler

str The name of the data import handler.

host

str (None) The solr host to query. __opts__['host'] is default.

core

str (None) The core the handler belongs to.

verbose

boolean (False) Run the command with verbose output.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.reload_import_config dataimport None music {'clean':True}

salt.modules.solr.replication_details(host=None, core_name=None)

Get the full replication details.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.replication_details music

salt.modules.solr.set_is_polling(polling, host=None, core_name=None)

SLAVE CALL Prevent the slaves from polling the master for updates.

polling

boolean True will enable polling. False will disable it.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.set_is_polling False

salt.modules.solr.set_replication_enabled(status, host=None, core_name=None)

MASTER ONLY Sets the master to ignore poll requests from the slaves. Useful when you don't want the slaves replicating during indexing or when clearing the index.

status

boolean Sets the replication status to the specified state.

host

str (None) The solr host to query. __opts__['host'] is default.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to set the status on all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.set_replication_enabled false, None, music

salt.modules.solr.signal(signal=None)

Signals Apache Solr to start, stop, or restart. Obviously this is only going to work if the minion resides on the solr host. Additionally Solr doesn't ship with an init script so one must be created.

signal

str (None) The command to pass to the apache solr init valid values are 'start', 'stop', and 'restart'

CLI Example:

salt '*' solr.signal restart

salt.modules.solr.version(core_name=None)

Gets the solr version for the core specified. You should specify a core here as all the cores will run under the same servlet container and so will all have the same version.

core_name

str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores.

Return : dict<str,obj>:

{'success':boolean, 'data':dict, 'errors':list, 'warnings':list}

CLI Example:

salt '*' solr.version

salt.modules.sqlite3

Support for SQLite3

salt.modules.sqlite3.fetch(db=None, sql=None)

Retrieve data from an sqlite3 db (returns all rows, be careful!)

CLI Example:

salt '*' sqlite3.fetch /root/test.db 'SELECT * FROM test;'

salt.modules.sqlite3.indexes(db=None)

Show all indices in the database, for people with poor spelling skills

CLI Example:

salt '*' sqlite3.indexes /root/test.db

salt.modules.sqlite3.indices(db=None)

Show all indices in the database

CLI Example:

salt '*' sqlite3.indices /root/test.db

salt.modules.sqlite3.modify(db=None, sql=None)

Issue an SQL query to sqlite3 (with no return data), usually used to modify the database in some way (insert, delete, create, etc)

CLI Example:

salt '*' sqlite3.modify /root/test.db 'CREATE TABLE test(id INT, testdata TEXT);'

salt.modules.sqlite3.sqlite_version()

Return version of sqlite

CLI Example:

salt '*' sqlite3.sqlite_version

salt.modules.sqlite3.tables(db=None)

Show all tables in the database

CLI Example:

salt '*' sqlite3.tables /root/test.db

salt.modules.sqlite3.version()

Return version of pysqlite

CLI Example:

salt '*' sqlite3.version

salt.modules.ssh

Manage client ssh components

salt.modules.ssh.auth_keys(user, config='.ssh/authorized_keys')

Return the authorized keys for the specified user

CLI Example:

salt '*' ssh.auth_keys root

salt.modules.ssh.check_key(user, key, enc, comment, options, config='.ssh/authorized_keys')

Check to see if a key needs updating, returns "update", "add" or "exists"

CLI Example:

salt '*' ssh.check_key <user> <key> <enc> <comment> <options>

salt.modules.ssh.check_key_file(user, keysource, config='.ssh/authorized_keys', env='base')

Check a keyfile from a source destination against the local keys and return the keys to change

CLI Example:

salt '*' root salt://ssh/keyfile

salt.modules.ssh.check_known_host(user, hostname, key=None, fingerprint=None, config='.ssh/known_hosts')

Check the record in known_hosts file, either by its value or by fingerprint (it's enough to set up either key or fingerprint, you don't need to set up both).

If provided key or fingerprint doesn't match with stored value, return "update", if no value is found for a given host, return "add", otherwise return "exists".

If neither key, nor fingerprint is defined, then additional validation is not performed.

CLI Example:

salt '*' ssh.check_known_host <user> <hostname> key='AAAA...FAaQ=='

salt.modules.ssh.get_known_host(user, hostname, config='.ssh/known_hosts')

Return information about known host from the configfile, if any. If there is no such key, return None.

CLI Example:

salt '*' ssh.get_known_host <user> <hostname>

salt.modules.ssh.host_keys(keydir=None)

Return the minion's host keys

CLI Example:

salt '*' ssh.host_keys

salt.modules.ssh.recv_known_host(user, hostname, enc=None, port=None, hash_hostname=False)

Retrieve information about host public key from remote server

CLI Example:

salt '*' ssh.recv_known_host <user> <hostname> enc=<enc> port=<port>

salt.modules.ssh.rm_auth_key(user, key, config='.ssh/authorized_keys')

Remove an authorized key from the specified user's authorized key file

CLI Example:

salt '*' ssh.rm_auth_key <user> <key>

salt.modules.ssh.rm_known_host(user, hostname, config='.ssh/known_hosts')

Remove all keys belonging to hostname from a known_hosts file.

CLI Example:

salt '*' ssh.rm_known_host <user> <hostname>

salt.modules.ssh.set_auth_key(user, key, enc='ssh-rsa', comment='', options=None, config='.ssh/authorized_keys')

Add a key to the authorized_keys file. The "key" parameter must only be the string of text that is the encoded key. If the key begins with "ssh-rsa" or ends with user@host, remove those from the key before passing it to this function.

CLI Example:

salt '*' ssh.set_auth_key <user> '<key>' enc='dsa'

salt.modules.ssh.set_auth_key_from_file(user, source, config='.ssh/authorized_keys', env='base')

Add a key to the authorized_keys file, using a file as the source.

CLI Example:

salt '*' ssh.set_auth_key_from_file <user>                salt://ssh_keys/<user>.id_rsa.pub

salt.modules.ssh.set_known_host(user, hostname, fingerprint=None, port=None, enc=None, hash_hostname=True, config='.ssh/known_hosts')

Download SSH public key from remote host "hostname", optionally validate its fingerprint against "fingerprint" variable and save the record in the known_hosts file.

If such a record does already exists in there, do nothing.

CLI Example:

salt '*' ssh.set_known_host <user> fingerprint='xx:xx:..:xx' enc='ssh-rsa'                 config='.ssh/known_hosts'

salt.modules.state

Control the state system on the minion

salt.modules.state.high(data)

Execute the compound calls stored in a single set of high data This function is mostly intended for testing the state system

CLI Example:

salt '*' state.high '{"vim": {"pkg": ["installed"]}}'

salt.modules.state.highstate(test=None, **kwargs)

Retrive the state data from the salt master for this minion and execute it

CLI Example:

salt '*' state.highstate

salt.modules.state.low(data)

Execute a single low data call This function is mostly intended for testing the state system

CLI Example:

salt '*' state.low '{"state": "pkg", "fun": "installed", "name": "vi"}'

salt.modules.state.running()

Return a dict of state return data if a state function is already running. This function is used to prevent multiple state calls from being run at the same time.

CLI Example:

salt '*' state.running

salt.modules.state.show_highstate()

Retrieve the highstate data from the salt master and display it

CLI Example:

salt '*' state.show_highstate

salt.modules.state.show_lowstate()

List out the low data that will be applied to this minion

CLI Example:

salt '*' state.show_lowstate

salt.modules.state.show_sls(mods, env='base', test=None, **kwargs)

Display the state data from a specific sls or list of sls files on the master

CLI Example:

salt '*' state.show_sls core,edit.vim dev

salt.modules.state.show_top()

Return the top data that the minion will use for a highstate

CLI Example:

salt '*' state.show_top

salt.modules.state.single(fun, name, test=None, kwval_as='yaml', **kwargs)

Execute a single state function with the named kwargs, returns False if insufficient data is sent to the command

By default, the values of the kwargs will be parsed as YAML. So, you can specify lists values, or lists of single entry key-value maps, as you would in a YAML salt file. Alternatively, JSON format of keyword values is also supported.

CLI Example:

salt '*' state.single pkg.installed name=vim

salt.modules.state.sls(mods, env='base', test=None, exclude=None, **kwargs)

Execute a set list of state modules from an environment, default environment is base

CLI Example:

salt '*' state.sls core,edit.vim dev

salt.modules.state.template(tem)

Execute the information stored in a template file on the minion

CLI Example:

salt '*' state.template '<Path to template on the minion>'

salt.modules.state.template_str(tem)

Execute the information stored in a string from an sls template

CLI Example:

salt '*' state.template_str '<Template String>'

salt.modules.state.top(topfn)

Execute a specific top file instead of the default

CLI Example:

salt '*' state.top reverse_top.sls

salt.modules.status

Module for returning various status data about a minion. These data can be useful for compiling into stats later.

salt.modules.status.all_status()

Return a composite of all status data and info for this minion. Warning: There is a LOT here!

CLI Example:

salt '*' status.all_status

salt.modules.status.cpuinfo()

Return the CPU info for this minion

CLI Example:

salt '*' status.cpuinfo

salt.modules.status.cpustats()

Return the CPU stats for this minon

CLI Example:

salt '*' status.cpustats

salt.modules.status.custom()

Return a custom composite of status data and info for this minon, based on the minion config file. An example config like might be:

status.cpustats.custom: [ 'cpu', 'ctxt', 'btime', 'processes' ]

Where status refers to status.py, cpustats is the function where we get our data, and custom is this function It is followed by a list of keys that we want returned.

This function is meant to replace all_status(), which returns anything and everything, which we probably don't want.

By default, nothing is returned. Warning: Depending on what you include, there can be a LOT here!

CLI Example:

salt '*' status.custom

salt.modules.status.diskstats()

Return the disk stats for this minion

CLI Example:

salt '*' status.diskstats

salt.modules.status.diskusage(*args)

Return the disk usage for this minion

Usage:

salt '*' status.diskusage [paths and/or filesystem types]

CLI Example:

salt '*' status.diskusage         # usage for all filesystems
salt '*' status.diskusage / /tmp  # usage for / and /tmp
salt '*' status.diskusage ext?    # usage for ext[234] filesystems
salt '*' status.diskusage / ext?  # usage for / and all ext filesystems

salt.modules.status.loadavg()

Return the load averages for this minion

CLI Example:

salt '*' status.loadavg

salt.modules.status.meminfo()

Return the CPU stats for this minion

CLI Example:

salt '*' status.meminfo

salt.modules.status.netdev()

Return the network device stats for this minion

CLI Example:

salt '*' status.netdev

salt.modules.status.netstats()

Return the network stats for this minion

CLI Example:

salt '*' status.netstats

salt.modules.status.pid(sig)

Return the PID or an empty string if the process is running or not. Pass a signature to use to find the process via ps.

CLI Example:

salt '*' status.pid <sig>

salt.modules.status.procs()

Return the process data

CLI Example:

salt '*' status.procs

salt.modules.status.uptime()

Return the uptime for this minion

CLI Example:

salt '*' status.uptime

salt.modules.status.vmstats()

Return the virtual memory stats for this minion

CLI Example:

salt '*' status.vmstats

salt.modules.status.w()

Return a list of logged in users for this minion, using the w command

CLI Example:

salt '*' status.w

salt.modules.supervisord

Provide the service module for supervisord
salt.modules.supervisord.add(name, user=None): Activates any updates in config for process/group; CLI Example::

salt '*' supervisord.add <name>

salt.modules.supervisord.custom(command, user=None): Run any custom supervisord command; CLI Example::

salt '*' supervisord.custom "mstop 'gunicorn'"

salt.modules.supervisord.remove(name, user=None): Removes process/group from active config; CLI Example::

salt '*' supervisord.remove <name>

salt.modules.supervisord.reread(user=None): Reload the daemon's configuration files; CLI Example::

salt '*' supervisord.reread

salt.modules.supervisord.restart(name='all', user=None): Restart the named service.; CLI Example::

salt '*' supervisord.restart <service>

salt.modules.supervisord.start(name='all', user=None): Start the named service; CLI Example::

salt '*' supervisord.start <service>

salt.modules.supervisord.status(name=None, user=None): List programms and its state; CLI Example::

salt '*' supervisord.status

salt.modules.supervisord.status_raw(name=None, user=None)

Display the raw output of status

CLI Example:

salt '*' supervisord.status_raw

salt.modules.supervisord.stop(name='all', user=None)

Stop the named service.

CLI Example::

salt '*' supervisord.stop <service>

salt.modules.supervisord.update(user=None): Reload config and add/remove as necessary; CLI Example::

salt '*' supervisord.update

salt.modules.svn

Subversion SCM
salt.modules.svn.add(cwd, targets, user=None, *opts): Add files to be tracked by the Subversion working-copy checkout; cwd
The path to the Subversion repository; targets

None files and directories to pass to the command as arguments

user

None Run svn as a user other than what the minion runs as

CLI Example:

salt '*' svn.add /path/to/repo /path/to/new/file

salt.modules.svn.checkout(cwd, remote, target=None, user=None, username=None, *opts)

Download a working copy of the remote Subversion repository directory or file

cwd

The path to the Subversion repository

remote

None URL to checkout

target

None The name to give the file or directory working copy Default: svn uses the remote basename

user

None Run svn as a user other than what the minion runs as

username

None Connect to the Subversion server as another user

CLI Example:

salt '*' svn.checkout /path/to/repo svn://remote/repo

salt.modules.svn.commit(cwd, targets=None, msg=None, user=None, username=None, *opts)

Commit the current directory, files, or directories to the remote Subversion repository

cwd

The path to the Subversion repository

targets

None files and directories to pass to the command as arguments Default: svn uses '.'

msg

None Message to attach to the commit log

user

None Run svn as a user other than what the minion runs as

username

None Connect to the Subversion server as another user

CLI Example:

salt '*' svn.commit /path/to/repo

salt.modules.svn.diff(cwd, targets=None, user=None, username=None, *opts)

Return the diff of the current directory, files, or directories from the remote Subversion repository

cwd

The path to the Subversion repository

targets

None files and directories to pass to the command as arguments Default: svn uses '.'

user

None Run svn as a user other than what the minion runs as

username

None Connect to the Subversion server as another user

CLI Example:

salt '*' svn.diff /path/to/repo

salt.modules.svn.info(cwd, targets=None, user=None, username=None, fmt='str')

Display the Subversion information from the checkout.

cwd

The path to the Subversion repository

targets

None files, directories, and URLs to pass to the command as arguments svn uses '.' by default

user

None Run svn as a user other than what the minion runs as

username

None Connect to the Subversion server as another user

fmt

str How to fmt the output from info. (str, xml, list, dict)

CLI Example:

salt '*' svn.info /path/to/svn/repo

salt.modules.svn.remove(cwd, targets, msg=None, user=None, username=None, *opts)

Remove files and directories from the Subversion repository

cwd

The path to the Subversion repository

targets

None files, directories, and URLs to pass to the command as arguments

msg

None Message to attach to the commit log

user

None Run svn as a user other than what the minion runs as

username

None Connect to the Subversion server as another user

CLI Example:

salt '*' svn.remove /path/to/repo /path/to/repo/remove

salt.modules.svn.status(cwd, targets=None, user=None, username=None, *opts)

Display the status of the current directory, files, or directories in the Subversion repository

cwd

The path to the Subversion repository

targets

None files, directories, and URLs to pass to the command as arguments Default: svn uses '.'

user

None Run svn as a user other than what the minion runs as

username

None Connect to the Subversion server as another user

CLI Example:

salt '*' svn.status /path/to/repo

salt.modules.svn.update(cwd, targets=None, user=None, *opts)

Update the current directory, files, or directories from the remote Subversion repository

cwd

The path to the Subversion repository

targets

None files and directories to pass to the command as arguments Default: svn uses '.'

user

None Run svn as a user other than what the minion runs as

username

None Connect to the Subversion server as another user

CLI Example:

salt '*' svn.update /path/to/repo

salt.modules.sysbench

The 'sysbench' module is used to analyse the performance of the minions, right from the master! It measures various system parameters such as CPU, Memory, FileI/O, Threads and Mutex.

salt.modules.sysbench.cpu()

Tests for the cpu performance of minions.

CLI Examples:

salt '*' sysbench.cpu

salt.modules.sysbench.fileio()

This tests for the file read and write operations Various modes of operations are

• sequential write

• sequential rewrite

• sequential read

• random read

• random write

• random read and write

The test works with 32 files with each file being 1Gb in size The test consumes a lot of time. Be patient!

CLI Examples:

salt \* sysbench.fileio

salt.modules.sysbench.memory()

This tests the memory for read and write operations.

CLI Examples:

salt \* sysbench.memory

salt.modules.sysbench.mutex()

Tests the implementation of mutex

CLI Examples:

salt \* sysbench.mutex

salt.modules.sysbench.ping()

salt.modules.sysbench.threads()

This tests the performance of the processor's scheduler

CLI Example:

salt \* sysbench.threads

salt.modules.sysmod

The sys module provides information about the available functions on the minion.

salt.modules.sysmod.doc(module='')

Return the docstrings for all modules. Optionally, specify a module or a function to narrow te selection.

The strings are aggregated into a single document on the master for easy reading.

CLI Example:

salt \* sys.doc
salt \* sys.doc sys
salt \* sys.doc sys.doc

salt.modules.sysmod.list_functions(module='')

List the functions for all modules. Optionally, specify a module to list from.

CLI Example:

salt \* sys.list_functions
salt \* sys.list_functions sys

salt.modules.sysmod.list_modules()

List the modules loaded on the minion

CLI Example:

salt \* sys.list_modules

salt.modules.sysmod.reload_modules()

Tell the minion to reload the execution modules

CLI Example:

salt \* sys.reload_modules

salt.modules.systemd

Provide the service module for systemd

salt.modules.systemd.available(name)

Check that the given service is available taking into account template units.

CLI Example:

salt '*' service.available sshd

salt.modules.systemd.disable(name, **kwargs)

Disable the named service to not start when the system boots

CLI Example:

salt '*' service.disable <service name>

salt.modules.systemd.disabled(name)

Return if the named service is disabled to start on boot

CLI Example:

salt '*' service.disabled <service name>

salt.modules.systemd.enable(name, **kwargs)

Enable the named service to start when the system boots

CLI Example:

salt '*' service.enable <service name>

salt.modules.systemd.enabled(name)

Return if the named service is enabled to start on boot

CLI Example:

salt '*' service.enabled <service name>

salt.modules.systemd.force_reload(name)

Force-reload the specified service with systemd

CLI Example:

salt '*' service.force_reload <service name>

salt.modules.systemd.get_all()

Return a list of all available services

CLI Example:

salt '*' service.get_all

salt.modules.systemd.get_disabled()

Return a list of all disabled services

CLI Example:

salt '*' service.get_disabled

salt.modules.systemd.get_enabled()

Return a list of all enabled services

CLI Example:

salt '*' service.get_enabled

salt.modules.systemd.reload(name)

Reload the specified service with systemd

CLI Example:

salt '*' service.reload <service name>

salt.modules.systemd.restart(name)

Restart the specified service with systemd

CLI Example:

salt '*' service.restart <service name>

salt.modules.systemd.start(name)

Start the specified service with systemd

CLI Example:

salt '*' service.start <service name>

salt.modules.systemd.status(name, sig=None)

Return the status for a service via systemd, returns a bool whether the service is running.

CLI Example:

salt '*' service.status <service name>

salt.modules.systemd.stop(name)

Stop the specified service with systemd

CLI Example:

salt '*' service.stop <service name>

salt.modules.test

Module for running arbitrary tests

salt.modules.test.collatz(start)

Execute the collatz conjecture from the passed starting number, returns the sequence and the time it took to compute. Used for performance tests.

CLI Example:

salt '*' test.collatz 3

salt.modules.test.conf_test()

Return the value for test.foo in the minion configuration file, or return the default value

CLI Example:

salt '*' test.conf_test

salt.modules.test.cross_test(func, args=None)

Execute a minion function via the __salt__ object in the test module, used to verify that the minion functions can be called via the __salt__ module.

CLI Example:

salt '*' test.cross_test file.gid_to_group 0

salt.modules.test.echo(text)

Return a string - used for testing the connection

CLI Example:

salt '*' test.echo 'foo bar baz quo qux'

salt.modules.test.fib(num)

Return a Fibonacci sequence up to the passed number, and the timeit took to compute in seconds. Used for performance tests

CLI Example:

salt '*' test.fib 3

salt.modules.test.get_opts()

Return the configuration options passed to this minion

CLI Example:

salt '*' test.get_opts

salt.modules.test.kwarg(**kwargs)

Print out the data passed into the function **kwargs, this is used to both test the publication data and cli kwarg passing, but also to display the information available within the publication data.

CLI Example:

salt '*' test.kwarg

salt.modules.test.outputter(data)

Test the outputter, pass in data to return

CLI Example:

salt '*' test.outputter foobar

salt.modules.test.ping()

Just used to make sure the minion is up and responding Return True

CLI Example:

salt '*' test.ping

salt.modules.test.sleep(length)

Instruct the minion to initiate a process that will sleep for a given period of time.

CLI Example:

salt '*' test.sleep 20

salt.modules.test.version()

Return the version of salt on the minion

CLI Example:

salt '*' test.version

salt.modules.timezone

Module for managing timezone on posix-like systems.

salt.modules.timezone.get_hwclock()

Get current hardware clock setting (UTC or localtime)

CLI Example:

salt '*' timezone.get_hwclock

salt.modules.timezone.get_offset()

Get current numeric timezone offset from UCT (i.e. -0700)

CLI Example:

salt '*' timezone.get_offset

salt.modules.timezone.get_zone()

Get current timezone (i.e. America/Denver)

CLI Example:

salt '*' timezone.get_zone

salt.modules.timezone.get_zonecode()

Get current timezone (i.e. PST, MDT, etc)

CLI Example:

salt '*' timezone.get_zonecode

salt.modules.timezone.set_hwclock(clock)

Sets the hardware clock to be either UTC or localtime

CLI Example:

salt '*' timezone.set_hwclock UTC

salt.modules.timezone.set_zone(timezone)

Unlinks, then symlinks /etc/localtime to the set timezone.

The timezone is crucial to several system processes, each of which SHOULD be restarted (for instance, whatever you system uses as its cron and syslog daemons). This will not be magically done for you!

CLI Example:

salt '*' timezone.set_zone 'America/Denver'

salt.modules.timezone.zone_compare(timezone)

Checks the md5sum between the given timezone, and the one set in /etc/localtime. Returns True if they match, and False if not. Mostly useful for running state checks.

Example:

salt '*' timezone.zone_compare 'America/Denver'

salt.modules.tls

A salt module for SSL/TLS. Can create a Certificate Authority (CA) or use Self-Signed certificates.

depends

• PyOpenSSL Python module

configuration

Add the following values in /etc/salt/minion for the CA module to function properly:

ca.cert_base_path: '/etc/pki'

salt.modules.tls.create_ca(ca_name, bits=2048, days=365, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='Salt Stack', OU=None, emailAddress='xyz@pdq.net')

Create a Certificate Authority (CA)

ca_name

name of the CA

bits

number of RSA key bits, default is 2048

days

number of days the CA will be valid, default is 365

common name in the request, default is "localhost"

country, default is "US"

state, default is "Utah"

locality, default is "Centerville", the city where SaltStack originated

organization, default is "Salt Stack"

organizational unit, default is None

emailAddress

email address for the CA owner, default is 'xyz@pdq.net'

Writes out a CA certificate based upon defined config values. If the file already exists, the function just returns assuming the CA certificate already exists.

If the following values were set:

ca.cert_base_path='/etc/pki/koji' ca_name='koji'

the resulting CA would be written in the following location:

/etc/pki/koji/koji_ca_cert.crt

CLI Example:

salt '*' tls.create_ca test_ca

salt.modules.tls.create_ca_signed_cert(ca_name, CN, days=365)

Create a Certificate (CERT) signed by a named Certificate Authority (CA)

ca_name

name of the CA

common name matching the certificate signing request

days

number of days certficate is valid, default is 365 (1 year)

Writes out a Certificate (CERT) If the file already exists, the function just returns assuming the CERT already exists.

The CN must match an existing CSR generated by create_csr. If it does not, this method does nothing.

CLI Example:

salt '*' tls.create_ca_signed_cert test localhost

salt.modules.tls.create_csr(ca_name, bits=2048, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='Salt Stack', OU=None, emailAddress='xyz@pdq.net')

Create a Certificate Signing Request (CSR) for a particular Certificate Authority (CA)

ca_name

name of the CA

bits

number of RSA key bits, default is 2048

common name in the request, default is "localhost"

country, default is "US"

state, default is "Utah"

locality, default is "Centerville", the city where SaltStack originated

organization, default is "Salt Stack" NOTE: Must the same as CA certificate or an error will be raised

organizational unit, default is None

emailAddress

email address for the request, default is 'xyz@pdq.net'

Writes out a Certificate Signing Request (CSR) If the file already exists, the function just returns assuming the CSR already exists.

If the following values were set:

ca.cert_base_path='/etc/pki/koji' ca_name='koji' CN='test.egavas.org'

the resulting CSR, and corresponding key, would be written in the following location:

/etc/pki/koji/certs/test.egavas.org.csr /etc/pki/koji/certs/test.egavas.org.key

CLI Example:

salt '*' tls.create_csr test

salt.modules.tls.create_pkcs12(ca_name, CN, passphrase='')

Create a PKCS#12 browser certificate for a particular Certificate (CN)

ca_name

name of the CA

common name matching the the certificate signing request

passphrase

used to unlock the PKCS#12 certificate when loaded into the browser

CLI Example:

salt '*' tls.create_pkcs12 test localhost

salt.modules.tls.create_self_signed_cert(tls_dir='tls', bits=2048, days=365, CN='localhost', C='US', ST='Utah', L='Salt Lake City', O='Salt Stack', OU=None, emailAddress='xyz@pdq.net')

Create a Self-Signed Certificate (CERT)

tls_dir

location appended to the ca.cert_base_path, default is 'tls'

bits

number of RSA key bits, default is 2048

common name in the request, default is "localhost"

country, default is "US"

state, default is "Utah"

locality, default is "Centerville", the city where SaltStack originated

organization, default is "Salt Stack" NOTE: Must the same as CA certificate or an error will be raised

organizational unit, default is None

emailAddress

email address for the request, default is 'xyz@pdq.net'

Writes out a Self-Signed Certificate (CERT). If the file already exists, the function just returns.

If the following values were set:

ca.cert_base_path='/etc/pki/koji' tls_dir='koji' CN='test.egavas.org'

the resulting CERT, and corresponding key, would be written in the following location:

/etc/pki/tls/certs/test.egavas.org.crt /etc/pki/tls/certs/test.egavas.org.key

CLI Example:

salt '*' tls.create_self_signed_cert

salt.modules.tomcat

Support for Tomcat

salt.modules.tomcat.fullversion()

Return all server information from catalina.sh version

CLI Example:

salt '*' tomcat.fullversion

salt.modules.tomcat.signal(signal=None)

Signals catalina to start, stop, securestart, forcestop.

CLI Example:

salt '*' tomcat.signal start

salt.modules.tomcat.version()

Return server version from catalina.sh version

CLI Example:

salt '*' tomcat.version

salt.modules.upstart

Module for the management of upstart systems. The Upstart system only supports service starting, stopping and restarting. Currently (as of Ubuntu 12.04) there is no tool available to disable Upstart services (like update-rc.d). This[1] is the recommended way to disable an Upstart service. So we assume that all Upstart services that have not been disabled in this manner are enabled. But this is broken because we do not check to see that the dependent services are enabled. Otherwise we would have to do something like parse the output of "initctl show-config" to determine if all service dependencies are enabled to start on boot. For example, see the "start on" condition for the lightdm service below[2]. And this would be too hard. So we wait until the upstart developers have solved this problem. :) This is to say that an Upstart service that is enabled may not really be enabled. Also, when an Upstart service is enabled, should the dependent services be enabled too? Probably not. But there should be a notice about this, at least. [1] http://upstart.ubuntu.com/cookbook/#disabling-a-job-from-automatically-starting

[2] lightdm

emits login-session-start emits desktop-session-start emits desktop-shutdown start on ((((filesystem and runlevel [!06]) and started dbus) and (drm-device-added card0 PRIMARY_DEVICE_FOR_DISPLAY=1 or stopped udev-fallback-graphics)) or runlevel PREVLEVEL=S) stop on runlevel [016]

DO NOT use this module on Red Hat systems, as Red Hat systems should use the rh_service module, since red hat systems support chkconfig

salt.modules.upstart.disable(name, **kwargs)

Disable the named service from starting on boot

CLI Example:

salt '*' service.disable <service name>

salt.modules.upstart.disabled(name)

Check to see if the named service is disabled to start on boot

CLI Example:

salt '*' service.disabled <service name>

salt.modules.upstart.enable(name, **kwargs)

Enable the named service to start at boot

CLI Example:

salt '*' service.enable <service name>

salt.modules.upstart.enabled(name)

Check to see if the named service is enabled to start on boot

CLI Example:

salt '*' service.enabled <service name>

salt.modules.upstart.force_reload(name)

Force-reload the named service

CLI Example:

salt '*' service.force_reload <service name>

salt.modules.upstart.full_restart(name)

Do a full restart (stop/start) of the named service

CLI Example:

salt '*' service.full_restart <service name>

salt.modules.upstart.get_all()

Return all installed services

CLI Example:

salt '*' service.get_all

salt.modules.upstart.get_disabled()

Return the disabled services

CLI Example:

salt '*' service.get_disabled

salt.modules.upstart.get_enabled()

Return the enabled services

CLI Example:

salt '*' service.get_enabled

salt.modules.upstart.reload(name)

Reload the named service

CLI Example:

salt '*' service.reload <service name>

salt.modules.upstart.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.upstart.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.upstart.status(name, sig=None)

Return the status for a service, returns a bool whether the service is running.

CLI Example:

salt '*' service.status <service name>

salt.modules.upstart.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.useradd

Manage users with the useradd command

salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=True, shell=None, unique=True, system=False, fullname='', roomnumber='', workphone='', homephone='')

Add a user to the minion

CLI Example:

salt '*' user.add name <uid> <gid> <groups> <home> <shell>

salt.modules.useradd.chfullname(name, fullname)

Change the user's Full Name

CLI Example:

salt '*' user.chfullname foo "Foo Bar"

salt.modules.useradd.chgid(name, gid)

Change the default group of the user

CLI Example:

salt '*' user.chgid foo 4376

salt.modules.useradd.chgroups(name, groups, append=False)

Change the groups this user belongs to, add append to append the specified groups

CLI Example:

salt '*' user.chgroups foo wheel,root True

salt.modules.useradd.chhome(name, home, persist=False)

Change the home directory of the user, pass true for persist to copy files to the new home dir

CLI Example:

salt '*' user.chhome foo /home/users/foo True

salt.modules.useradd.chhomephone(name, homephone)

Change the user's Home Phone

CLI Example:

salt '*' user.chhomephone foo "7735551234"

salt.modules.useradd.chroomnumber(name, roomnumber)

Change the user's Room Number

CLI Example:

salt '*' user.chroomnumber foo 123

salt.modules.useradd.chshell(name, shell)

Change the default shell of the user

CLI Example:

salt '*' user.chshell foo /bin/zsh

salt.modules.useradd.chuid(name, uid)

Change the uid for a named user

CLI Example:

salt '*' user.chuid foo 4376

salt.modules.useradd.chworkphone(name, workphone)

Change the user's Work Phone

CLI Example:

salt '*' user.chworkphone foo "7735550123"

salt.modules.useradd.delete(name, remove=False, force=False)

Remove a user from the minion

CLI Example:

salt '*' user.delete name remove=True force=True

salt.modules.useradd.getent()

Return the list of all info for all users

CLI Example:

salt '*' user.getent

salt.modules.useradd.info(name)

Return user information

CLI Example:

salt '*' user.info root

salt.modules.useradd.list_groups(name)

Return a list of groups the named user belongs to

CLI Example:

salt '*' user.list_groups foo

salt.modules.useradd.list_users()

Return a list of all users

CLI Example:

salt '*' user.list_users

salt.modules.virt

Work with virtual machines managed by libvirt

depends

libvirt Python module

salt.modules.virt.create(vm_)

Start a defined domain

CLI Example:

salt '*' virt.create <vm name>

salt.modules.virt.create_xml_path(path)

Start a defined domain

CLI Example:

salt '*' virt.create_xml_path <path to xml file on the node>

salt.modules.virt.create_xml_str(xml)

Start a domain based on the xml passed to the function

CLI Example:

salt '*' virt.create_xml_str <xml in string format>

salt.modules.virt.ctrl_alt_del(vm_)

Sends CTRL+ALT+DEL to a VM

CLI Example:

salt '*' virt.ctrl_alt_del <vm name>

salt.modules.virt.define_xml_str(xml)

Define a domain based on the xml passed to the function

CLI Example:

salt '*' virt.define_xml_str <xml in string format>

salt.modules.virt.destroy(vm_)

Hard power down the virtual machine, this is equivalent to pulling the power

CLI Example:

salt '*' virt.destroy <vm name>

salt.modules.virt.freecpu()

Return an int representing the number of unallocated cpus on this hypervisor

CLI Example:

salt '*' virt.freecpu

salt.modules.virt.freemem()

Return an int representing the amount of memory that has not been given to virtual machines on this node

CLI Example:

salt '*' virt.freemem

salt.modules.virt.full_info()

Return the node_info, vm_info and freemem

CLI Example:

salt '*' virt.full_info

salt.modules.virt.get_disks(vm_)

Return the disks of a named vm

CLI Example:

salt '*' virt.get_disks <vm name>

salt.modules.virt.get_graphics(vm_)

Returns the information on vnc for a given vm

CLI Example:

salt '*' virt.get_graphics <vm name>

salt.modules.virt.get_macs(vm_)

Return a list off MAC addresses from the named vm

CLI Example:

salt '*' virt.get_macs <vm name>

salt.modules.virt.get_nics(vm_)

Return info about the network interfaces of a named vm

CLI Example:

salt '*' virt.get_nics <vm name>

salt.modules.virt.get_xml(vm_)

Returns the xml for a given vm

CLI Example:

salt '*' virt.get_xml <vm name>

salt.modules.virt.is_hyper()

Returns a bool whether or not this node is a hypervisor of any kind

CLI Example:

salt '*' virt.is_hyper

salt.modules.virt.is_kvm_hyper()

Returns a bool whether or not this node is a KVM hypervisor

CLI Example:

salt '*' virt.is_kvm_hyper

salt.modules.virt.is_xen_hyper()

Returns a bool whether or not this node is a XEN hypervisor

CLI Example:

salt '*' virt.is_xen_hyper

salt.modules.virt.list_active_vms()

Return a list of names for active virtual machine on the minion

CLI Example:

salt '*' virt.list_active_vms

salt.modules.virt.list_inactive_vms()

Return a list of names for inactive virtual machine on the minion

CLI Example:

salt '*' virt.list_inactive_vms

salt.modules.virt.list_vms()

Return a list of virtual machine names on the minion

CLI Example:

salt '*' virt.list_vms

salt.modules.virt.migrate(vm_, target, ssh=False)

Shared storage migration

CLI Example:

salt '*' virt.migrate <vm name> <target hypervisor>

salt.modules.virt.migrate_non_shared(vm_, target, ssh=False)

Attempt to execute non-shared storage "all" migration

CLI Example:

salt '*' virt.migrate_non_shared <vm name> <target hypervisor>

salt.modules.virt.migrate_non_shared_inc(vm_, target, ssh=False)

Attempt to execute non-shared storage "all" migration

CLI Example:

salt '*' virt.migrate_non_shared_inc <vm name> <target hypervisor>

salt.modules.virt.node_info()

Return a dict with information about this node

CLI Example:

salt '*' virt.node_info

salt.modules.virt.pause(vm_)

Pause the named vm

CLI Example:

salt '*' virt.pause <vm name>

salt.modules.virt.purge(vm_, dirs=False)

Recursively destroy and delete a virtual machine, pass True for dir's to also delete the directories containing the virtual machine disk images - USE WITH EXTREME CAUTION!

CLI Example:

salt '*' virt.purge <vm name>

salt.modules.virt.reboot(vm_)

Reboot a domain via ACPI request

CLI Example:

salt '*' virt.reboot <vm name>

salt.modules.virt.reset(vm_)

Reset a VM by emulating the reset button on a physical machine

CLI Example:

salt '*' virt.reset <vm name>

salt.modules.virt.resume(vm_)

Resume the named vm

CLI Example:

salt '*' virt.resume <vm name>

salt.modules.virt.seed_non_shared_migrate(disks, force=False)

Non shared migration requires that the disks be present on the migration destination, pass the disks information via this function, to the migration destination before executing the migration.

CLI Example:

salt '*' virt.seed_non_shared_migrate <disks>

salt.modules.virt.set_autostart(vm_, state='on')

Set the autostart flag on a VM so that the VM will start with the host system on reboot.

CLI Example:

salt "*" virt.set_autostart <vm name> <on | off>

salt.modules.virt.setmem(vm_, memory, config=False)

Changes the amount of memory allocated to VM. The VM must be shutdown for this to work.

memory is to be specified in MB If config is True then we ask libvirt to modify the config as well

CLI Example:

salt '*' virt.setmem myvm 768

salt.modules.virt.setvcpus(vm_, vcpus, config=False)

Changes the amount of vcpus allocated to VM. The VM must be shutdown for this to work.

vcpus is an int representing the number to be assigned If config is True then we ask libvirt to modify the config as well

CLI Example:

salt '*' virt.setvcpus myvm 2

salt.modules.virt.shutdown(vm_)

Send a soft shutdown signal to the named vm

CLI Example:

salt '*' virt.shutdown <vm name>

salt.modules.virt.start(vm_)

Alias for the obscurely named 'create' function

CLI Example:

salt '*' virt.start <vm name>

salt.modules.virt.undefine(vm_)

Remove a defined vm, this does not purge the virtual machine image, and this only works if the vm is powered down

CLI Example:

salt '*' virt.undefine <vm name>

salt.modules.virt.virt_type()

Returns the virtual machine type as a string

CLI Example:

salt '*' virt.virt_type

salt.modules.virt.vm_cputime(vm_=None)

Return cputime used by the vms on this hyper in a list of dicts:

[
    'your-vm': {
        'cputime' <int>
        'cputime_percent' <int>
        },
    ...
    ]

If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs.

CLI Example:

salt '*' virt.vm_cputime

salt.modules.virt.vm_diskstats(vm_=None)

Return disk usage counters used by the vms on this hyper in a list of dicts:

[
    'your-vm': {
        'rd_req'   : 0,
        'rd_bytes' : 0,
        'wr_req'   : 0,
        'wr_bytes' : 0,
        'errs'     : 0
        },
    ...
    ]

If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs.

CLI Example:

salt '*' virt.vm_blockstats

salt.modules.virt.vm_info(vm_=None)

Return detailed information about the vms on this hyper in a list of dicts:

[
    'your-vm': {
        'cpu': <int>,
        'maxMem': <int>,
        'mem': <int>,
        'state': '<state>',
        'cputime' <int>
        },
    ...
    ]

If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs.

CLI Example:

salt '*' virt.vm_info

salt.modules.virt.vm_netstats(vm_=None)

Return combined network counters used by the vms on this hyper in a list of dicts:

[
    'your-vm': {
        'rx_bytes'   : 0,
        'rx_packets' : 0,
        'rx_errs'    : 0,
        'rx_drop'    : 0,
        'tx_bytes'   : 0,
        'tx_packets' : 0,
        'tx_errs'    : 0,
        'tx_drop'    : 0
        },
    ...
    ]

If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs.

CLI Example:

salt '*' virt.vm_netstats

salt.modules.virt.vm_state(vm_=None)

Return list of all the vms and their state.

If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs.

CLI Example:

salt '*' virt.vm_state <vm name>

salt.modules.virtualenv

Create virtualenv environments
salt.modules.virtualenv.create(path, venv_bin=None, no_site_packages=False, system_site_packages=False, distribute=False, clear=False, python='', extra_search_dir='', never_download=False, prompt='', runas=None): Create a virtualenv; path
The path to create the virtualenv; venv_bin

'virtualenv' The name (and optionally path) of the virtualenv command. This can also be set globally in the minion config file as virtualenv.venv_bin.

no_site_packages

False Passthrough argument given to virtualenv

system_site_packages

False Passthrough argument given to virtualenv

distribute

False Passthrough argument given to virtualenv

clear

False Passthrough argument given to virtualenv

python

(default) Passthrough argument given to virtualenv

extra_search_dir

(default) Passthrough argument given to virtualenv

never_download

(default) Passthrough argument given to virtualenv

prompt

(default) Passthrough argument given to

virtualenv

runas

None Set ownership for the virtualenv

CLI Example:

salt '*' virtualenv.create /path/to/new/virtualenv

salt.modules.win_disk

Module for gathering disk information on Windows

depends

• win32api Python module

salt.modules.win_disk.usage()

Return usage information for volumes mounted on this minion

CLI Example:

salt '*' disk.usage

salt.modules.win_file

Manage information about files on the minion, set/read user, group data

depends

• win32api

• win32con

• win32security

• ntsecuritycon

salt.modules.win_file.append(path, *args)

Append text to the end of a file

CLI Example:

salt '*' file.append /etc/motd \
        "With all thine offerings thou shalt offer salt."\
        "Salt is what makes things taste bad when it isn't in them."

New in version 0.9.5.

salt.modules.win_file.chgrp(path, group)

Change the group of a file

CLI Example:

salt '*' file.chgrp c:\temp\test.txt administrators

salt.modules.win_file.chown(path, user, group)

Chown a file, pass the file the desired user and group

CLI Example:

salt '*' file.chown c:\temp\test.txt myusername administrators

salt.modules.win_file.comment(path, regex, char='#', backup='.bak')

Comment out specified lines in a file

path

The full path to the file to be edited

regex

char

# The character to be inserted at the beginning of a line in order to comment it out

backup

.bak The file will be backed up before edit with this file extension

Warning

This backup will be overwritten each time sed / comment / uncomment is called. Meaning the backup will only be useful after the first invocation.

CLI Example:

salt '*' file.comment /etc/modules pcspkr

New in version 0.9.5.

salt.modules.win_file.contains(path, text, limit='')

Return True if the file at path contains text

CLI Example:

salt '*' file.contains /etc/crontab 'mymaintenance.sh'

New in version 0.9.5.

salt.modules.win_file.find(path, **kwargs)

Approximate the Unix find(1) command and return a list of paths that meet the specified criteria.

The options include match criteria:

name    = path-glob                 # case sensitive
iname   = path-glob                 # case insensitive
regex   = path-regex                # case sensitive
iregex  = path-regex                # case insensitive
type    = file-types                # match any listed type
user    = users                     # match any listed user
group   = groups                    # match any listed group
size    = [+-]number[size-unit]     # default unit = byte
mtime   = interval                  # modified since date
grep    = regex                     # search file contents

and/or actions:

delete [= file-types]               # default type = 'f'
exec    = command [arg ...]         # where {} is replaced by pathname
print  [= print-opts]

The default action is 'print=path'.

file-glob:

*                = match zero or more chars
?                = match any char
[abc]            = match a, b, or c
[!abc] or [^abc] = match anything except a, b, and c
[x-y]            = match chars x through y
[!x-y] or [^x-y] = match anything except chars x through y
{a,b,c}          = match a or b or c

path-regex: a Python re (regular expression) pattern to match pathnames

file-types: a string of one or more of the following:

a: all file types
b: block device
c: character device
d: directory
p: FIFO (named pipe)
f: plain file
l: symlink
s: socket

users: a space and/or comma separated list of user names and/or uids

groups: a space and/or comma separated list of group names and/or gids

size-unit:

b: bytes
k: kilobytes
m: megabytes
g: gigabytes
t: terabytes

interval:

[<num>w] [<num>[d]] [<num>h] [<num>m] [<num>s]

where:
    w: week
    d: day
    h: hour
    m: minute
    s: second

print-opts: a comma and/or space separated list of one or more of the following:

group: group name
md5:   MD5 digest of file contents
mode:  file permissions (as integer)
mtime: last modification time (as time_t)
name:  file basename
path:  file absolute path
size:  file size in bytes
type:  file type
user:  user name

CLI Examples:

salt '*' file.find / type=f name=\*.bak size=+10m
salt '*' file.find /var mtime=+30d size=+10m print=path,size,mtime
salt '*' file.find /var/log name=\*.[0-9] mtime=+30d size=+10m delete

salt.modules.win_file.get_gid(path)

Return the id of the group that owns a given file

CLI Example:

salt '*' file.get_gid c:\temp\test.txt

salt.modules.win_file.get_group(path)

Return the group that owns a given file

CLI Example:

salt '*' file.get_group c:\temp\test.txt

salt.modules.win_file.get_mode(path)

Return the mode of a file

Right now we're just returning 777 because Windows' doesn't have a mode like Linux

CLI Example:

salt '*' file.get_mode /etc/passwd

salt.modules.win_file.get_sum(path, form='md5')

Return the sum for the given file, default is md5, sha1, sha224, sha256, sha384, sha512 are supported

CLI Example:

salt '*' file.get_sum /etc/passwd sha512

salt.modules.win_file.get_uid(path)

Return the id of the user that owns a given file

CLI Example:

salt '*' file.get_uid c:\temp\test.txt

salt.modules.win_file.get_user(path)

Return the user that owns a given file

CLI Example:

salt '*' file.get_user c:\temp\test.txt

salt.modules.win_file.gid_to_group(gid)

Convert the group id to the group name on this system

CLI Example:

salt '*' file.gid_to_group S-1-5-21-626487655-2533044672-482107328-1010

salt.modules.win_file.group_to_gid(group)

Convert the group to the gid on this system

CLI Example:

salt '*' file.group_to_gid administrators

salt.modules.win_file.sed(path, before, after, limit='', backup='.bak', options='-r -e', flags='g')

Make a simple edit to a file

Equivalent to:

sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"

path

The full path to the file to be edited

before

A pattern to find in order to replace with after

after

Text that will replace before

limit

'' An initial pattern to search for before searching for before

backup

.bak The file will be backed up before edit with this file extension; WARNING: each time sed/comment/uncomment is called will overwrite this backup

options

-r -e Options to pass to sed

flags

g Flags to modify the sed search; e.g., i for case-insensitve pattern matching

Forward slashes and single quotes will be escaped automatically in the before and after patterns.

CLI Example:

salt '*' file.sed /etc/httpd/httpd.conf 'LogLevel warn' 'LogLevel info'

New in version 0.9.5.

salt.modules.win_file.touch(name, atime=None, mtime=None)

Just like 'nix's "touch" command, create a file if it doesn't exist or simply update the atime and mtime if it already does.

atime:

Access time in Unix epoch time

mtime:

Last modification in Unix epoch time

CLI Example:

salt '*' file.touch /var/log/emptyfile

New in version 0.9.5.

salt.modules.win_file.uid_to_user(uid)

Convert a uid to a user name

CLI Example:

salt '*' file.uid_to_user S-1-5-21-626487655-2533044672-482107328-1010

salt.modules.win_file.uncomment(path, regex, char='#', backup='.bak')

Uncomment specified commented lines in a file

path

The full path to the file to be edited

regex

char

# The character to remove in order to uncomment a line; if a single whitespace character follows the comment it will also be removed

backup

.bak The file will be backed up before edit with this file extension; WARNING: each time sed/comment/uncomment is called will overwrite this backup

CLI Example:

salt '*' file.uncomment /etc/hosts.deny 'ALL: PARANOID'

New in version 0.9.5.

salt.modules.win_file.user_to_uid(user)

Convert user name to a uid

CLI Example:

salt '*' file.user_to_uid myusername

salt.modules.win_groupadd

Manage groups on Windows

salt.modules.win_groupadd.add(name, gid=None, system=False)

Add the specified group

CLI Example:

salt '*' group.add foo

salt.modules.win_groupadd.delete(name)

Remove the named group

CLI Example:

salt '*' group.delete foo

salt.modules.win_groupadd.getent()

Return info on all groups

CLI Example:

salt '*' group.getent

salt.modules.win_groupadd.info(name)

Return information about a group

CLI Example:

salt '*' group.info foo

salt.modules.win_network

Module for gathering and managing network information

salt.modules.win_network.dig(host)

Performs a DNS lookup with dig

Note: dig must be installed on the Windows minion

CLI Example:

salt '*' network.dig archlinux.org

salt.modules.win_network.interfaces()

salt.modules.win_network.netstat()

Return information on open ports and states

CLI Example:

salt '*' network.netstat

salt.modules.win_network.nslookup(host)

Query DNS for information about a domain or ip address

CLI Example:

salt '*' network.nslookup archlinux.org

salt.modules.win_network.ping(host)

Performs a ping to a host

CLI Example:

salt '*' network.ping archlinux.org

salt.modules.win_network.traceroute(host)

Performs a traceroute to a 3rd party host

CLI Example:

salt '*' network.traceroute archlinux.org

salt.modules.win_pkg

A module to manage software on Windows

depends

• pythoncom

• win32com

• win32con

• win32api

salt.modules.win_pkg.available_version(name)

The available version of the package in the repository

CLI Example:

salt '*' pkg.available_version <package name>

salt.modules.win_pkg.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.win_pkg.install(name=None, refresh=False, **kwargs)

Install the passed package

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.install <package name>

salt.modules.win_pkg.list_pkgs(*args)

List the packages currently installed in a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.win_pkg.list_upgrades(refresh=True)

List all available package upgrades on this system

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.win_pkg.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.win_pkg.purge(name, **kwargs)

Recursively remove a package and all dependencies which were installed with it

Return a list containing the removed packages.

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.win_pkg.refresh_db()

Just recheck the repository and return a dict:

{'<database name>': Bool}

CLI Example:

salt '*' pkg.refresh_db

salt.modules.win_pkg.remove(name, version=None, **kwargs)

Remove a single package

Return a list containing the removed packages.

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.win_pkg.upgrade(refresh=True)

Run a full system upgrade

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

salt.modules.win_pkg.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.win_pkg.version(name)

Returns a version if the package is installed, else returns an empty string

CLI Example:

salt '*' pkg.version <package name>

salt.modules.win_service

Windows Service module.

salt.modules.win_service.disable(name, **kwargs)

Disable the named service to start at boot

CLI Example:

salt '*' service.disable <service name>

salt.modules.win_service.disabled(name)

Check to see if the named service is disabled to start on boot

CLI Example:

salt '*' service.disabled <service name>

salt.modules.win_service.enable(name, **kwargs)

Enable the named service to start at boot

CLI Example:

salt '*' service.enable <service name>

salt.modules.win_service.enabled(name)

Check to see if the named service is enabled to start on boot

CLI Example:

salt '*' service.enabled <service name>

salt.modules.win_service.get_all()

Return all installed services

CLI Example:

salt '*' service.get_all

salt.modules.win_service.get_disabled()

Return the disabled services

CLI Example:

salt '*' service.get_disabled

salt.modules.win_service.get_enabled()

Return the enabled services

CLI Example:

salt '*' service.get_enabled

salt.modules.win_service.getsid(name)

Return the sid for this windows service

CLI Example:

salt '*' service.getsid <service name>

salt.modules.win_service.restart(name)

Restart the named service

CLI Example:

salt '*' service.restart <service name>

salt.modules.win_service.start(name)

Start the specified service

CLI Example:

salt '*' service.start <service name>

salt.modules.win_service.status(name, sig=None)

Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps

CLI Example:

salt '*' service.status <service name> [service signature]

salt.modules.win_service.stop(name)

Stop the specified service

CLI Example:

salt '*' service.stop <service name>

salt.modules.win_shadow

Manage the shadow file

salt.modules.win_shadow.info(name)

Return information for the specified user This is just returns dummy data so that salt states can work.

CLI Example:

salt '*' shadow.info root

salt.modules.win_shadow.set_password(name, password)

Set the password for a named user.

CLI Example:

salt '*' shadow.set_password root mysecretpassword

salt.modules.win_status

Module for returning various status data about a minion. These data can be useful for compiling into stats later.

depends

• pythoncom

• wmi

salt.modules.win_status.procs()

Return the process data

CLI Example:

salt '*' status.procs

salt.modules.win_useradd

Manage Windows users with the net user command NOTE: This currently only works with local user accounts, not domain accounts

salt.modules.win_useradd.add(name, uid=None, gid=None, groups=None, home=False, shell=None, system=False)

Add a user to the minion

CLI Example:

salt '*' user.add name password

salt.modules.win_useradd.addgroup(name, group)

Add user to a group

CLI Example:

salt '*' user.addgroup username groupname

salt.modules.win_useradd.chgroups(name, groups, append=False)

Change the groups this user belongs to, add append to append the specified groups

CLI Example:

salt '*' user.chgroups foo wheel,root True

salt.modules.win_useradd.chhome(name, home)

Change the home directory of the user

CLI Example:

salt '*' user.chhome foo \\fileserver\home\foo

salt.modules.win_useradd.chprofile(name, profile)

Change the profile directory of the user

CLI Example:

salt '*' user.chprofile foo \\fileserver\profiles\foo

salt.modules.win_useradd.delete(name)

Remove a user from the minion

CLI Example:

salt '*' user.delete name

salt.modules.win_useradd.getent()

Return the list of all info for all users

CLI Example:

salt '*' user.getent

salt.modules.win_useradd.info(name)

Return user information

CLI Example:

salt '*' user.info root

salt.modules.win_useradd.list_groups(name)

Return a list of groups the named user belongs to

CLI Example:

salt '*' user.list_groups foo

salt.modules.win_useradd.removegroup(name, group)

Remove user from a group

CLI Example:

salt '*' user.removegroup username groupname

salt.modules.win_useradd.setpassword(name, password)

Set a user's password

CLI Example:

salt '*' user.setpassword name password

salt.modules.yumpkg5

Support for YUM

salt.modules.yumpkg5.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

salt.modules.yumpkg5.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.yumpkg5.install(name=None, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, sources=None, **kwargs)

Install the passed package(s), add refresh=True to clean the yum database before package is installed.

name

CLI Example::

salt '*' pkg.install <package name>

refresh

Whether or not to update the yum database before executing.

skip_verify

Skip the GPG verification check (e.g., --nogpgcheck)

version

Install a specific version of the package, e.g. 1.2.3-4.el5. Ignored if "pkgs" or "sources" is passed.

Repository Options:

fromrepo

Specify a package repository (or repositories) from which to install. (e.g., yum --disablerepo='*' --enablerepo='somerepo')

enablerepo (ignored if fromrepo is specified)

Specify a disabled package repository (or repositories) to enable. (e.g., yum --enablerepo='somerepo')

disablerepo (ignored if fromrepo is specified)

Specify an enabled package repository (or repositories) to disable. (e.g., yum --disablerepo='somerepo')

Multiple Package Installation Options:

pkgs

CLI Examples::

salt '*' pkg.install pkgs='["foo", "bar"]' salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-4.el5"}]'

sources

A list of RPM packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

CLI Example::

salt '*' pkg.install sources='[{"foo": "salt://foo.rpm"},{"bar": "salt://bar.rpm"}]'

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

salt.modules.yumpkg5.list_pkgs()

List the packages currently installed in a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.yumpkg5.list_upgrades(refresh=True)

Check whether or not an upgrade is available for all packages

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.yumpkg5.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.yumpkg5.purge(pkg, **kwargs)

Yum does not have a purge, this function calls remove

Return a list containing the removed packages:

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.yumpkg5.refresh_db()

Since yum refreshes the database automatically, this runs a yum clean, so that the next yum operation will have a clean database

CLI Example:

salt '*' pkg.refresh_db

salt.modules.yumpkg5.remove(pkg, **kwargs)

Remove a single package with yum remove

Return a list containing the removed packages:

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.yumpkg5.upgrade(refresh=True)

Run a full system upgrade, a yum upgrade

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

salt.modules.yumpkg5.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.yumpkg5.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

salt.modules.yumpkg

New in version 0.9.4: This module replaces the "yum" module in previous releases. It is backward compatibile and uses the native yum Python interface instead of the CLI interface. Support for YUM

depends

• yum Python module

• rpmUtils Python module

salt.modules.yumpkg.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

salt.modules.yumpkg.clean_metadata()

Cleans local yum metadata.

CLI Example:

salt '*' pkg.clean_metadata

salt.modules.yumpkg.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.yumpkg.del_repo(repo, basedir='/etc/yum.repos.d')

Delete a repo from <basedir> (default basedir: /etc/yum.repos.d).

If the .repo file that the repo exists in does not contain any other repo configuration, the file itself will be deleted.

CLI Examples:

salt '*' pkg.del_repo myrepo
salt '*' pkg.del_repo myrepo basedir=/path/to/dir

salt.modules.yumpkg.file_dict(*packages)

List the files that belong to a package, grouped by package. Not specifying any packages will return a list of _every_ file on the system's rpm database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.yumpkg.file_list(*packages)

List the files that belong to a package. Not specifying any packages will return a list of _every_ file on the system's rpm database (not generally recommended).

CLI Examples:

salt '*' pkg.file_list httpd
salt '*' pkg.file_list httpd postfix
salt '*' pkg.file_list

salt.modules.yumpkg.get_repo(repo, basedir='/etc/yum.repos.d')

Display a repo from <basedir> (default basedir: /etc/yum.repos.d).

CLI Examples:

salt '*' pkg.get_repo myrepo
salt '*' pkg.get_repo myrepo basedir=/path/to/dir

salt.modules.yumpkg.group_diff(groupname)

Lists packages belonging to a certain group, and which are installed

CLI Example:

salt '*' pkg.group_diff 'Perl Support'

salt.modules.yumpkg.group_info(groupname)

Lists packages belonging to a certain group

CLI Example:

salt '*' pkg.groupinfo 'Perl Support'

salt.modules.yumpkg.group_install(name=None, groups=None, skip=None, include=None, **kwargs)

Install the passed package group(s). This is basically a wrapper around pkg.install, which performs package group resolution for the user. This function is currently considered "experimental", and should be expected to undergo changes before it becomes official.

name

The name of a single package group to install. Note that this option is ignored if "groups" is passed.

groups

The names of multiple packages which are to be installed.

CLI Example:

salt '*' pkg.groupinstall groups='["Group 1", "Group 2"]'

skip

The name(s), in a list, of any packages that would normally be installed by the package group ("default" packages), which should not be installed.

CLI Examples:

salt '*' pkg.groupinstall 'My Group' skip='["foo", "bar"]'

include

The name(s), in a list, of any packages which are included in a group, which would not normally be installed ("optional" packages). Note that this will nor enforce group membership; if you include packages which are not members of the specified groups, they will still be installed.

CLI Examples:

salt '*' pkg.groupinstall 'My Group' include='["foo", "bar"]'

other arguments

Because this is essentially a wrapper around pkg.install, any argument which can be passed to pkg.install may also be included here, and it will be passed along wholesale.

salt.modules.yumpkg.group_list()

Lists all groups known by yum on this system

CLI Example:

salt '*' pkg.group_list

salt.modules.yumpkg.install(name=None, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, sources=None, **kwargs)

Install the passed package(s), add refresh=True to clean the yum database before package is installed.

name

CLI Example::

salt '*' pkg.install <package name>

refresh

Whether or not to update the yum database before executing.

skip_verify

Skip the GPG verification check. (e.g., --nogpgcheck)

version

Install a specific version of the package, e.g. 1.2.3-4.el6. Ignored if "pkgs" or "sources" is passed.

Repository Options:

fromrepo

Specify a package repository (or repositories) from which to install. (e.g., yum --disablerepo='*' --enablerepo='somerepo')

enablerepo

Specify a disabled package repository (or repositories) to enable. (e.g., yum --enablerepo='somerepo')

disablerepo

Specify an enabled package repository (or repositories) to disable. (e.g., yum --disablerepo='somerepo')

Multiple Package Installation Options:

pkgs

CLI Examples::

salt '*' pkg.install pkgs='["foo", "bar"]' salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-4.el6"}]'

sources

A list of RPM packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

CLI Example::

salt '*' pkg.install sources='[{"foo": "salt://foo.rpm"},{"bar": "salt://bar.rpm"}]'

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

salt.modules.yumpkg.list_pkgs()

List the packages currently installed in a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.yumpkg.list_repos(basedir='/etc/yum.repos.d')

Lists all repos in <basedir> (default: /etc/yum.repos.d/).

CLI Example:

salt '*' pkg.list_repos

salt.modules.yumpkg.list_upgrades(refresh=True)

Check whether or not an upgrade is available for all packages

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.yumpkg.mod_repo(repo, basedir=None, **kwargs)

Modify one or more values for a repo. If the repo does not exist, it will be created, so long as the following values are specified:

repo (name by which the yum refers to the repo)
name (a human-readable name for the repo)
baseurl or mirrorlist (the url for yum to reference)

Key/Value pairs may also be removed from a repo's configuration by setting a key to a blank value. Bear in mind that a name cannot be deleted, and a baseurl can only be deleted if a mirrorlist is specified (or vice versa).

CLI Examples:

salt '*' pkg.mod_repo reponame enabled=1 gpgcheck=1
salt '*' pkg.mod_repo reponame basedir=/path/to/dir enabled=1
salt '*' pkg.mod_repo reponame baseurl= mirrorlist=http://host.com/

salt.modules.yumpkg.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.yumpkg.purge(pkgs, **kwargs)

Yum does not have a purge, this function calls remove

Return a list containing the removed packages:

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.yumpkg.refresh_db()

Since yum refreshes the database automatically, this runs a yum clean, so that the next yum operation will have a clean database

CLI Example:

salt '*' pkg.refresh_db

salt.modules.yumpkg.remove(pkgs, **kwargs)

Removes packages with yum remove

Return a list containing the removed packages:

CLI Example:

salt '*' pkg.remove <package,package,package>

salt.modules.yumpkg.upgrade(refresh=True)

Run a full system upgrade, a yum upgrade

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

salt.modules.yumpkg.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.yumpkg.verify(*package)

Runs an rpm -Va on a system, and returns the results in a dict

CLI Example:

salt '*' pkg.verify

salt.modules.yumpkg.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

salt.modules.zpool

zfs support. Assumes FreeBSD

depends

• mkfile

salt.modules.zpool.add(pool_name, vdisk)

Add a single device to mirror

CLI Example:

salt '*' zfs.add myzpool /disk2

salt.modules.zpool.create_file_vdevice(size, *names)

creates file based virtual devices for a zpool

*names is a list of full paths for mkfile to create

CLI Example:

salt '*' zfs.create_file_vdevice 7g /disk1 /disk2

Depending on file size this may take a while to return

salt.modules.zpool.list_installed()

returns a list of installed packages

salt.modules.zpool.pool_exists(pool_name)

Check if a zfs storage pool is active

salt.modules.zpool.replace(pool_name, old, new)

Replace a disk in a pool with another disk.

CLI Example:

salt '*' zfs.replace myzpool /disk1 /disk2

salt.modules.zpool.zpool_create(pool_name, *disks)

Create a simple storage pool

CLI Example:

salt '*' zfs.zpool_create myzpool /disk1 /disk2

salt.modules.zpool.zpool_destory(pool_name)

Destorys a storage pool

CLI Example:

salt '*' zfs.zpool_destory myzpool

salt.modules.zpool.zpool_detach(zpool, device)

Detach a device from a storage pool

CLI Example:

salt '*' zfs.detach myzpool /disk1

salt.modules.zpool.zpool_list()

list zpool's size and usage

salt.modules.zpool.zpool_status(name=None)

salt.modules.zypper

Package support for openSUSE via the zypper package manager

salt.modules.zypper.available_version(*names)

Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned.

If the latest version of a given package is already installed, an empty string will be returned for that package.

CLI Example:

salt '*' pkg.available_version <package name>
salt '*' pkg.available_version <package1> <package2> <package3> ...

salt.modules.zypper.compare(pkg1='', oper='==', pkg2='')

Compare two version strings.

CLI Example:

salt '*' pkg.compare '0.2.4-0' '<' '0.2.4.1-0'
salt '*' pkg.compare pkg1='0.2.4-0' oper='<' pkg2='0.2.4.1-0'

salt.modules.zypper.install(name=None, refresh=False, pkgs=None, sources=None, **kwargs)

Install the passed package(s), add refresh=True to run 'zypper refresh' before package is installed.

name

CLI Example::

salt '*' pkg.install <package name>

refresh

Whether or not to refresh the package database before installing.

version

Can be either a version number, or the combination of a comparison operator (<, >, <=, >=, =) and a version number (ex. '>1.2.3-4'). This parameter is ignored if "pkgs" or "sources" is passed.

Multiple Package Installation Options:

pkgs

CLI Examples::

salt '*' pkg.install pkgs='["foo", "bar"]' salt '*' pkg.install pkgs='["foo", {"bar": "1.2.3-4"}]' salt '*' pkg.install pkgs='["foo", {"bar": "<1.2.3-4"}]'

sources

A list of RPM packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package.

CLI Example::

salt '*' pkg.install sources='[{"foo": "salt://foo.rpm"},{"bar": "salt://bar.rpm"}]'

Returns a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

salt.modules.zypper.list_pkgs()

List the packages currently installed as a dict:

{'<package_name>': '<version>'}

CLI Example:

salt '*' pkg.list_pkgs

salt.modules.zypper.list_upgrades(refresh=True)

List all available package upgrades on this system

CLI Example:

salt '*' pkg.list_upgrades

salt.modules.zypper.perform_cmp(pkg1='', pkg2='')

Do a cmp-style comparison on two packages. Return -1 if pkg1 < pkg2, 0 if pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem making the comparison.

CLI Example:

salt '*' pkg.perform_cmp '0.2.4-0' '0.2.4.1-0'
salt '*' pkg.perform_cmp pkg1='0.2.4-0' pkg2='0.2.4.1-0'

salt.modules.zypper.purge(name, **kwargs)

Recursively remove a package and all dependencies which were installed with it, this will call a zypper remove -u

Return a list containing the removed packages.

CLI Example:

salt '*' pkg.purge <package name>

salt.modules.zypper.refresh_db()

Just run a zypper refresh, return a dict:

{'<database name>': Bool}

CLI Example:

salt '*' pkg.refresh_db

salt.modules.zypper.remove(name, **kwargs)

Remove a single package with zypper remove

Return a list containing the removed packages.

CLI Example:

salt '*' pkg.remove <package name>

salt.modules.zypper.upgrade(refresh=True)

Run a full system upgrade, a zypper upgrade

Return a dict containing the new package names and versions:

{'<package>': {'old': '<old-version>',
               'new': '<new-version>'}}

CLI Example:

salt '*' pkg.upgrade

salt.modules.zypper.upgrade_available(name)

Check whether or not an upgrade is available for a given package

CLI Example:

salt '*' pkg.upgrade_available <package name>

salt.modules.zypper.version(*names)

Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

CLI Example:

salt '*' pkg.version <package name>
salt '*' pkg.version <package1> <package2> <package3> ...

Returners

By default the return values of the commands sent to the Salt minions are returned to the salt-master. But since the commands executed on the Salt minions are detached from the call on the Salt master, there is no need for the minion to return the data to the Salt master.

This is where the returner interface comes in. Returners are modules called in place of returning the data to the Salt master.

The returner interface allows the return data to be sent to any system that can receive data. This means that return data can be sent to a Redis server, a MongoDB server, a MySQL server, or any system!

See also: Full list of builtin returners

Using Returners

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

Writing a Returner

A returner is a module which contains a returner function, the returner function must accept a single argument. this argument is the return data from the called minion function. So if the minion function test.ping is called the value of the argument will be True.
A simple returner is implemented here:
import redis import json def returner(ret): ''' Return information to a redis server ''' # Get a redis commection serv = redis.Redis( host='redis-serv.example.com', port=6379, db='0') serv.sadd("%(id)s:jobs" % ret, ret['jid']) serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret['return'])) serv.sadd('jobs', ret['jid']) serv.sadd(ret['jid'], ret['id'])
This simple example of a returner set to send the data to a redis server serializes the data as json and sets it in redis.
You can place your custom returners in a _returners directory within the file_roots specified by the master config file. These custom returners are distributed when state.highstate is run, or by executing the saltutil.sync_returners or saltutil.sync_all functions.

Examples

The collection of built-in Salt returners can be found here: https://github.com/saltstack/salt/blob/develop/salt/returners

Full List Of Builtin Returner Modules

salt.returners.cassandra_return

Return data to a Cassandra ColumnFamily Here's an example Keyspace / ColumnFamily setup that works with this returner: create keyspace salt; use salt; create column family returns with key_validation_class='UTF8Type' and comparator='UTF8Type' and default_validation_class='UTF8Type'; Required python modules: pycassa
salt.returners.cassandra_return.returner(ret): Return data to a Cassandra ColumnFamily

salt.returners.local

The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly
salt.returners.local.returner(ret): Print the return data to the terminal to verify functionality

salt.returners.mongo_future_return

Return data to a mongodb server Required python modules: pymongo This returner will send data from the minions to a MongoDB server. To configure the settings for your MongoDB server, add the following lines to the minion config files: mongo.db: <database name> mongo.host: <server ip address> mongo.user: <MongoDB username> mongo.password: <MongoDB user password> mongo.port: 27017 This mongo returner is being developed to replace the default mongodb returner in the future and should not be considered api stable yet.
salt.returners.mongo_future_return.get_fun(fun): Return the most recent jobs that have executed the named function
salt.returners.mongo_future_return.get_jid(jid): Return the return information associated with a jid
salt.returners.mongo_future_return.get_jids(): Return a list of job ids
salt.returners.mongo_future_return.get_load(jid): Returnt he load asociated with a given job id
salt.returners.mongo_future_return.get_minions(): Return a list of minions
salt.returners.mongo_future_return.returner(ret): Return data to a mongodb server
salt.returners.mongo_future_return.save_load(jid, load): Save the load for a given job id

salt.returners.mongo_return

Return data to a mongodb server Required python modules: pymongo This returner will send data from the minions to a MongoDB server. To configure the settings for your MongoDB server, add the following lines to the minion config files: mongo.db: <database name> mongo.host: <server ip address> mongo.user: <MongoDB username> mongo.password: <MongoDB user password> mongo.port: 27017
salt.returners.mongo_return.get_fun(fun): Return the most recent jobs that have executed the named function
salt.returners.mongo_return.get_jid(jid): Return the return information associated with a jid
salt.returners.mongo_return.returner(ret): Return data to a mongodb server

salt.returners.mysql

Return data to a mysql server
maintainer: Dave Boucha <dave@saltstack.com>, Seth House <- shouse@saltstack.com>
maturity: new
depends: python-mysqldb
platform: all
To enable this returner the minion will need the python client for mysql installed and the following values configured in the minion or master config, these are the defaults:
mysql.host: 'salt' mysql.user: 'salt' mysql.pass: 'salt' mysql.db: 'salt' mysql.port: 3306
Use the following mysql database schema:
CREATE DATABASE `salt` DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; USE `salt`; -- -- Table structure for table `jids` -- DROP TABLE IF EXISTS `jids`; CREATE TABLE `jids` ( `jid` varchar(255) NOT NULL, `load` mediumtext NOT NULL, UNIQUE KEY `jid` (`jid`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8; -- -- Table structure for table `salt_returns` -- DROP TABLE IF EXISTS `salt_returns`; CREATE TABLE `salt_returns` ( `fun` varchar(50) NOT NULL, `jid` varchar(255) NOT NULL, `return` mediumtext NOT NULL, `id` varchar(255) NOT NULL, `success` varchar(10) NOT NULL, `full_ret` mediumtext NOT NULL, KEY `id` (`id`), KEY `jid` (`jid`), KEY `fun` (`fun`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Required python modules: MySQLdb
salt.returners.mysql.get_fun(fun): Return a dict of the last function called for all minions
salt.returners.mysql.get_jid(jid): Return the information returned when the specified job id was executed
salt.returners.mysql.get_jids(): Return a list of all job ids
salt.returners.mysql.get_load(jid): Return the load data that marks a specified jid
salt.returners.mysql.get_minions(): Return a list of minions
salt.returners.mysql.returner(ret): Return data to a mysql server
salt.returners.mysql.save_load(jid, load): Save the load to the specified jid id

salt.returners.postgres

Return data to a postgresql server
maintainer: None
maturity: New
depends: psycopg2
platform: all
To enable this returner the minion will need the psycopg2 installed and the following values configured in the minion or master config:
returner.postgres.host: 'salt' returner.postgres.user: 'salt' returner.postgres.passwd: 'salt' returner.postgres.db: 'salt' returner.postgres.port: 5432
Running the following commands as the postgres user should create the database correctly:
psql << EOF CREATE ROLE salt WITH PASSWORD 'salt'; CREATE DATABASE salt WITH OWNER salt; EOF psql -h localhost -U salt << EOF -- -- Table structure for table 'jids' -- DROP TABLE IF EXISTS jids; CREATE TABLE jids ( jid bigint PRIMARY KEY, load text NOT NULL ); -- -- Table structure for table 'salt_returns' -- DROP TABLE IF EXISTS salt_returns; CREATE TABLE salt_returns ( fun text NOT NULL, jid varchar(20) NOT NULL, return text NOT NULL, id text NOT NULL, success boolean ); CREATE INDEX ON salt_returns (id); CREATE INDEX ON salt_returns (jid); CREATE INDEX ON salt_returns (fun);
Required python modules: psycopg2
salt.returners.postgres.get_fun(fun): Return a dict of the last function called for all minions
salt.returners.postgres.get_jid(jid): Return the information returned when the specified job id was executed
salt.returners.postgres.get_jids(): Return a list of all job ids
salt.returners.postgres.get_load(jid): Return the load data that marks a specified jid
salt.returners.postgres.get_minions(): Return a list of minions
salt.returners.postgres.returner(ret): Return data to a postgres server
salt.returners.postgres.save_load(jid, load): Save the load to the specified jid id

salt.returners.redis_return

Return data to a redis server To enable this returner the minion will need the python client for redis installed and the following values configured in the minion or master config, these are the defaults:: redis.db: '0' redis.host: 'salt' redis.port: 6379
salt.returners.redis_return.get_fun(fun): Return a dict of the last function called for all minions
salt.returners.redis_return.get_jid(jid): Return the information returned when the specified job id was executed
salt.returners.redis_return.get_jids(): Return a list of all job ids
salt.returners.redis_return.get_load(jid): Return the load data that marks a specified jid
salt.returners.redis_return.get_minions(): Return a list of minions
salt.returners.redis_return.returner(ret): Return data to a redis data store
salt.returners.redis_return.save_load(jid, load): Save the load to the specified jid

salt.returners.smtp_return

Return salt data via email The following fields can be set in the minion conf file:: smtp.from (required) smtp.to (required) smtp.host (required) smtp.username (optional) smtp.password (optional) smtp.tls (optional, defaults to False) smtp.subject (optional, but helpful) smtp.fields (optional)
There are a few things to keep in mind:
• If a username is used, a password is also required.
• You should at least declare a subject, but you don't have to.
• smtp.fields lets you include the value(s) of various fields in the subject line of the email. These are comma-delimited. For instance:: smtp.fields: id,fun
subject line. You may also use 'jid' (the job id), but it is generally recommended not to use 'return', which contains the entire return data structure (which can be very large).
salt.returners.smtp_return.returner(ret): Send an email with the data

salt.returners.syslog_return

Return data to the host operating system's syslog facility Required python modules: syslog, json The syslog returner simply reuses the operating system's syslog facility to log return data
salt.returners.syslog_return.returner(ret): Return data to the local syslog

State File 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 is 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.

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. Than the ssh server is extended to watch the banner file in addition to anything it is already watching.

Extend is a Top Level Declaration

This means that extend can only be called once in an sls, if if is used twice then only one of the extend blocks will be read. So this is WRONG:
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.

Highstate Data Structure Definitions

The Salt State Tree

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
State tree: A collection of SLS files that live under the directory specified in file_roots. A state tree can be organized into SLS modules.

Include declaration

Include declaration: Defines a list of module reference strings to include in this SLS.
Occurs only in the top level of the highstate structure.
Example: include: - edit.vim - http.server

Module reference

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 declarations and requisite declarations. 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

Until 0.9.6, IDs could not contain a dot, otherwise highstate summary output was unpredictable. (It was fixed in versions 0.9.7 and above)

Extend declaration

Extend declaration: Extends a name declaration from an included SLS module. The keys of the extend declaration always define existing ID declarations which have been defined in included SLS modules.
Occurs only in the top level and defines a dictionary.
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

State declaration

A list which contains one string defining the function declaration and any number of function arg declaration dictionaries.

Can, optionally, contain a number of additional components like the name override components - name and names. Can also contain requisite declarations.

Occurs under an ID declaration.

Requisite declaration

A list containing requisite references.

Used to build the action dependency tree. While Salt states are made to execute in a deterministic order, this order is managed by requiring and watching other Salt states.

Occurs as a list component under a state declaration or as a key under an ID declaration.

Requisite reference

Requisite reference: A single key dictionary. The key is the name of the referenced state declaration and the value is the ID of the referenced ID declaration.
Occurs as a single index in a requisite declaration list.

Function declaration

The name of the function to call within the state. A state declaration can contain only a single function declaration.

For example, the following state declaration calls the installed function in the pkg state module:

httpd:
  pkg.installed

The function can be declared inline with the state as a shortcut, but the actual data structure is better referenced in this form:

httpd:
  pkg:
    - installed

Where the function is a string in the body of the state declaration. Technically when the function is declared in dot notation the compiler converts it to be a string in the state declaration list. Note that the use of the first example more than once in an ID declaration is invalid yaml.

INVALID:

httpd:
  pkg.installed
  service.running

When passing a function without arguments and another state declaration within a single ID declaration, then the long or "standard" format needs to be used since otherwise it does not represent a valid data structure.

VALID:

httpd:
  pkg:
    - installed
  service:
    - running

Occurs as the only index in the state declaration list.

Function arg declaration

Function arg declaration: A single key dictionary referencing a Python type which is to be passed to the named function declaration as a parameter. The type must be the data type expected by the function.
Occurs under a function declaration.
For example in the following state declaration user, group, and mode are passed as arguments to the managed function in the file state module:
/etc/http/conf/http.conf: file.managed: - user: root - group: root - mode: 644

Name declaration

Name declaration: Overrides the name argument of a state declaration. If name is not specified the ID declaration satisfies the name argument.
The name is always a single key dictionary referencing a string.
Overriding name is useful for a variety of scenarios.
For example, avoiding clashing ID declarations. The following two state declarations cannot both have /etc/motd as the ID declaration:
motd_perms: file.managed: - name: /etc/motd - mode: 644 motd_quote: file.append: - name: /etc/motd - text: "Of all smells, bread; of all tastes, salt."
Another common reason to override name is if the ID declaration is long and needs to be referenced in multiple places. In the example below it is much easier to specify mywebsite than to specify /etc/apache2/sites-available/mywebsite.com multiple times:
mywebsite: file.managed: - name: /etc/apache2/sites-available/mywebsite.com - source: salt://mywebsite.com a2ensite mywebsite.com: cmd.wait: - unless: test -L /etc/apache2/sites-enabled/mywebsite.com - watch: - file: mywebsite apache2: service: - running - watch: - file: mywebsite

Names declaration

Names declaration: Expands the contents of the containing state declaration into multiple state declarations, each with its own name.
For example, given the following state declaration: python-pkgs: pkg.installed: - names: - python-django - python-crypto - python-yaml Once converted into the lowstate data structure the above state declaration will be expanded into the following three state declarations: python-django: pkg.installed python-crypto: pkg.installed python-yaml: pkg.installed

Large example

Here is the layout in yaml using the names of the highdata structure components. <Include Declaration>: - <Module Reference> - <Module Reference> <Extend Declaration>: <ID Declaration>: [<overrides>] # standard declaration <ID Declaration>: <State Declaration>: - <Function> - <Function Arg> - <Function Arg> - <Function Arg> - <Name>: <name> - <Requisite Declaration>: - <Requisite Reference> - <Requisite Reference> # inline function and names <ID Declaration>: <State Declaration>.<Function>: - <Function Arg> - <Function Arg> - <Function Arg> - <Names>: - <name> - <name> - <name> - <Requisite Declaration>: - <Requisite Reference> - <Requisite Reference> # multiple states for single id <ID Declaration>: <State Declaration>: - <Function> - <Function Arg> - <Name>: <name> - <Requisite Declaration>: - <Requisite Reference> <State Declaration>: - <Function> - <Function Arg> - <Names>: - <name> - <name> - <Requisite Declaration>: - <Requisite Reference>

Include And Exclude

Salt sls files can include other sls files and exclude sls files that have been otherwise included. This allows for an sls file to easily extend or manipulate other sls files.

Exclude

The exclude statement, added in Salt 0.10.3 allows an sls to hard exclude another sls file or a specific id. The component is excluded after the high data has been compiled, so nothing should be able to override an exclude. Since the exclude can remove an id or an sls the type of component to exclude needs to be defined. an exclude statement that verifies that the running highstate does not contain the http sls and the /etc/vimrc id would look like this: exclude: - sls: http - id: /etc/vimrc

State Enforcement

Salt offers an optional 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.

The Salt state system is made to be accurate, simple, and fast. And like the rest of the Salt system, Salt states are highly modular.

State management

State management, also frequently called software configuration management (SCM), is a program that puts and keeps a system into a predetermined state. It installs software packages, starts or restarts services, or puts configuration files in place and watches them for changes.
Having a state management system in place allows you to easily and reliably configure and manage a few servers or a few thousand servers. It allows you to keep that configuration under version control.
Salt States is an extension of the Salt Modules that we discussed in the previous remote execution tutorial. Instead of calling one-off executions the state of a system can be easily defined and then enforced.

Understanding the Salt State System Components

The Salt state system is comprised of a number of components. As a user, an understanding of the SLS and renderer systems are needed. But as a developer, an understanding of Salt states and how to write the states is needed as well.

Salt SLS System

SLS
The primary system used by the Salt state system is the SLS system. SLS stands for SaLt State.
The Salt States are files which contain the information about how to configure Salt minions. The states are laid out in a directory tree and can be written in many different formats. The contents of the files and they way they are laid out is intended to be as simple as possible while allowing for maximum flexibility. The files are laid out in states and contains information about how the minion needs to be configured.

SLS File Layout

SLS files are laid out in the Salt file server. A simple layout can look like this:
top.sls ssh.sls sshd_config users/init.sls users/admin.sls salt/init.sls salt/master.sls
This example shows the core concepts of file layout. The top file is a key component and is used with Salt matchers to match SLS states with minions. The .sls files are states. The rest of the files are seen by the Salt master as just files that can be downloaded.
The states are translated into dot notation, so the ssh.sls file is seen as the ssh state, the users/admin.sls file is seen as the users.admin states.
The init.sls files are translated to be the state name of the parent directory, so the salt/init.sls file translates to the Salt state.
The plain files are visible to the minions, as well as the state files. In Salt, everything is a file; there is no "magic translation" of files and file types. This means that a state file can be distributed to minions just like a plain text or binary file.

SLS Files

The Salt state files are simple sets of data. Since the SLS files are just data they can be represented in a number of different ways. The default format is yaml generated from a jinja template. This allows for the states files to have all the language constructs of Python and the simplicity of yaml. State files can then be complicated jinja templates that translate down to yaml, or just plain and simple yaml files! The State files are constructed data structures in a simple format. The format allows for many real activates to be expressed in very little text, while maintaining the utmost in readability and usability. Here is an example of a Salt State: vim: pkg: - installed salt: pkg: - latest service.running: - require: - file: /etc/salt/minion - pkg: salt - names: - salt-master - salt-minion - watch: - file: /etc/salt/minion /etc/salt/minion: file.managed: - source: salt://salt/minion - user: root - group: root - mode: 644 - require: - pkg: salt This short stanza will ensure that vim is installed, Salt is installed and up to date, the salt-master and salt-minion daemons are running and the Salt minion configuration file is in place. It will also ensure everything is deployed in the right order and that the Salt services are restarted when the watched file updated.

The Top File

The top file is the mapping for the state system. The top file specifies which minions should have which modules applied and which environments they should draw the states from. The top file works by specifying the environment, containing matchers with lists of Salt states sent to the matching minions: base: '*': - salt - users - users.admin 'saltmaster.*': - match: pcre - salt.master This simple example uses the base environment, which is built into the default Salt setup, and then all minions will have the modules salt, users and users.admin since '*' will match all minions. Then the regular expression matcher will match all minions' with an id matching saltmaster.* and add the salt.master state.

Renderer System

The Renderer system is a key component to the state system. SLS files are representations of Salt "high data" structures. All Salt cares about when reading an SLS file is the data structure that is produced from the file. This allows Salt states to be represented by multiple types of files. The Renderer system can be used to allow different formats to be used for SLS files. The available renderers can be found in the renderers directory in the Salt source code: https://github.com/saltstack/salt/blob/develop/salt/renderers By default SLS files are rendered using jinja as a templating engine, and yaml as the serialization format. Since the rendering system can be extended simply by adding a new renderer to the renderers directory, it is possible that any structured file could be used to represent the SLS files. In the future xml and raw Python will be added, as well as many other formats.

Ordering States

When creating Salt SLS files, it is often important to ensure that they run in a specific order. While states will always execute in the same order, that order is not necessarily defined the way you want it.

A few tools exist in Salt to set up the correct state ordering. These tools consist of requisite declarations and order options.

Note
Salt does not execute state declarations in the order they appear in the source.

Requisite Statements

Note This document represents behavior exhibited by Salt requisites as of version 0.9.7 of Salt.
Often when setting up states any single action will require or depend on another action. Salt allows you to build relationships between states with requisite statements. A requisite statement ensure that the named state is evaluated before the state requiring it. There are two types of requisite statements in Salt, require and watch.
These requisite statements are applied to a specific state declaration:
httpd: pkg: - installed file.managed: - name: /etc/httpd/conf/httpd.conf - source: salt://httpd/httpd.conf - require: - pkg: httpd
In this example we use the require requisite to declare that the file /etc/httpd/conf/httpd.conf should only be set up if the pkg state executes successfully.
The requisite system works by finding the states that are required and executing them before the state that requires them. Then the required states can be evaluated to see if they have executed correctly.

Multiple Requisites

The requisite statement is passed as a list, allowing for the easy addition of more requisites. Both requisite types can also be separately declared: httpd: pkg: - installed service.running: - enable: True - watch: - file: /etc/httpd/conf/httpd.conf - require: - pkg: httpd - user: httpd - group: httpd file.managed: - name: /etc/httpd/conf/httpd.conf - source: salt://httpd/httpd.conf - require: - pkg: httpd user: - present group: - present In this example the httpd service is only going to be started if the package, user, group and file are executed successfully.

The Require Requisite

The foundation of the requisite system is the require requisite. The require requisite ensures that the required state(s) are executed before the requiring state. So, if a state is declared that sets down a vimrc, then it would be pertinent to make sure that the vimrc file would only be set down if the vim package has been installed:
vim: pkg: - installed file.managed: - source: salt://vim/vimrc - require: - pkg: vim
In this case, the vimrc file will only be applied by Salt if and after the vim package is installed.

The Watch Requisite

The watch requisite is more advanced than the require requisite. The watch requisite executes the same logic as require (therefore if something is watched it does not need to also be required) with the addition of executing logic if the required states have changed in some way.
The watch requisite checks to see if the watched states have returned any changes. If the watched state returns changes, and the watched states execute successfully, then the watching state will execute a function that reacts to the changes in the watched states.
Perhaps an example can better explain the behavior:
redis: pkg: - latest file.managed: - source: salt://redis/redis.conf - name: /etc/redis.conf - require: - pkg: redis service.running: - enable: True - watch: - file: /etc/redis.conf - pkg: redis
In this example the redis service will only be started if the file /etc/redis.conf is applied, and the file is only applied if the package is installed. This is normal require behavior, but if the watched file changes, or the watched package is installed or upgraded, then the redis service is restarted.

Watch and the mod_watch Function

The watch requisite is based on the mod_watch function. Python state modules can include a function called mod_watch which is then called if the watch call is invoked. When mod_watch is called depends on the execution of the watched state, which:: • If no changes then just run the watching state itself as usual. mod_watch is not called. This behavior is same as using a require.
• If changes then run the watching state AND if that changes nothing then react by calling mod_watch.
When reacting, in the case of the service module the underlying service is restarted. In the case of the cmd state the command is executed.
The mod_watch function for the service state looks like this:
def mod_watch(name, sig=None, reload=False, full_restart=False): ''' The service watcher, called to invoke the watch command. name The name of the init or rc script used to manage the service sig The string to search for when looking for the service process with ps ''' if __salt__['service.status'](name, sig): if 'service.reload' in __salt__ and reload: restart_func = __salt__['service.reload'] elif 'service.full_restart' in __salt__ and full_restart: restart_func = __salt__['service.full_restart'] else: restart_func = __salt__['service.restart'] else: restart_func = __salt__['service.start'] result = restart_func(name) return {'name': name, 'changes': {name: result}, 'result': result, 'comment': 'Service restarted' if result else \ 'Failed to restart the service' }
The watch requisite only works if the state that is watching has a mod_watch function written. If watch is set on a state that does not have a mod_watch function (like pkg), then the listed states will behave only as if they were under a require statement.
Also notice that a mod_watch may accept additional keyword arguments, which, in the sls file, will be taken from the same set of arguments specified for the state that includes the watch requisite. This means, for the earlier service.running example above, you can tell the service to reload instead of restart like this:
redis: # ... other state declarations omitted ... service.running: - enable: True - reload: True - watch: - file: /etc/redis.conf - pkg: redis

The Order Option

Before using the order option, remember that the majority of state ordering should be done with a requisite declaration, and that a requisite declaration will override an order option.
The order option is used by adding an order number to a state declaration with the option order:
vim: pkg.installed: - order: 1
By adding the order option to 1 this ensures that the vim package will be installed in tandem with any other state declaration set to the order 1.
Any state declared without an order option will be executed after all states with order options are executed.
But this construct can only handle ordering states from the beginning. Sometimes you may want to send a state to the end of the line. To do this, set the order to last:
vim: pkg.installed: - order: last
Remember that requisite statements override the order option. So the order option should be applied to the highest component of the requisite chain:
vim: pkg.installed: - order: last - require: - file: /etc/vimrc /etc/vimrc: file.managed: - source: salt://edit/vimrc

Overstate System

Often servers need to be set up and configured in a specific order, and systems should only be set up if systems earlier in the sequence has been set up without any issues.

The 0.11.0 release of Salt addresses this problem with a new layer in the state system called the Over State. The concept of the Over State is managed on the master, a series of state executions is controlled from the master and executed in order. If an execution requires that another execution first run without problems then the state executions will stop.

The Over State system is used to orchestrate deployment in a smooth and reliable way across multiple systems in small to large environments.

The Over State SLS

The overstate system is managed by an sls file located in the root of an environment. This file uses a data structure like all sls files. The overstate sls file configures an unordered list of stages, each stage defines the minions to execute on and can define what sls files to run or to execute a state.highstate. mysql: match: db* sls: - mysql.server - drbd webservers: match: web* require: - mysql all: match: '*' require: - mysql - webservers The above defined over state will execute the mysql stage first because it is required by the webservers stage. The webservers stage will then be executed only if the mysql stage executes without any issues. The webservers stage will execute state.highstate on the matched minions, while the mysql stage will execute state.sls with the named sls files. Finally the all stage will execute state.highstate on all systems only if the mysql and webservers stages complete without failures. The overstate system checks for any states that return a result of False, if the run has any False returns then the overstate will quit.

Executing the Over State

The over state can be executed from the salt-run command, calling the state.over runner function. The function will by default look in the base environment for the overstate.sls file: salt-run state.over To specify the location of the overstate file and the environment to pull from pass the arguments to the salt-run command: salt-run state.over base /root/overstate.sls Remember, that these calls are made on the master.

State Providers

New in version 0.9.8.

Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management.

Sometimes in states, it may be necessary to use an alternative module to provide the needed functionality. For instance, an older Arch Linux system may not be running systemd, so instead of using the systemd service module, you can revert to the default service module:

httpd:
  service.running:
    - enable: True
    - provider: service

In this instance, the basic service module will replace the systemd module which is used by default on Arch Linux, and the httpd service will be managed using sysvinit.

Note
You can also set a provider globally in the minion config providers.

Arbitrary Module Redirects

The provider statement can also be used for more powerful means, instead of overwriting or extending the module used for the named service an arbitrary module can be used to provide certain functionality.
emacs: pkg.installed: - provider: - pkg: yumpkg5 - cmd: customcmd
In this example the default pkg module is being redirected to use the yumpkg5 module (yum via shelling out instead of via the yum Python API), but is also using a custom module to invoke commands. This could be used to dramatically change the behavior of a given state.

Requisites

The Salt requisite system is used to create relationships between states. The core idea being, that when one state it dependent somehow on another that interdependency can be easily defined.

Requisites come in two types. Direct requisites, and requisite_ins. The relationships are directional, so a requisite statement makes the requiring state declaration depend on the required state declaration:

vim:
  pkg.installed

/etc/vimrc:
  file.managed:
    - source: salt://edit/vimrc
    - require:
      - pkg: vim

So in this example, the file /etc/vimrc depends on the vim package.

Requisite_in statements are the opposite, instead of saying "I depend on something", requisite_ins say "Someone depends on me":

vim:
  pkg.installed:
    - require_in:
      - file: /etc/vimrc

/etc/vimrc:
  file.managed:
    - source: salt://edit/vimrc

So here, with a requisite_in, the same thing is accomplished, but just from the other way around. The vim package is saying "/etc/vimrc depends on me".

In the end a single dependency map is created and everything is executed in a finite and predictable order.

Requisite and Requisite in types

There are three requisite statements that can be used in Salt. the require, watch and use requisites. Each requisite also has a corresponding requisite_in: require_in, watch_in and use_in. All of the requisites define specific relationships and always work with the dependency logic defined above.

Require

The most basic requisite statement is require. The behavior of require is simple. Make sure that the dependent state is executed before the depending state, and it the dependent state fails, don't run the depending state. So in the above examples the file /etc/vimrc will only be applied after the vim package is installed and only if the vim package is installed successfully.

Watch

The watch statement does everything the require statement does, but with a little more. The watch statement looks into the state modules for a function called mod_watch. If this function is not available in the corresponding state module, then watch does the same thing as require. If the mod_watch function is in the state module, then the watched state is checked to see if it made any changes to the system, if it has, then mod_watch is called.
Perhaps the best example of using watch is with a service, when a service watches other states, then when the other states make changes on the system the service is reloaded or restarted.

Use

The use requisite is used to inherit the arguments passed in another id declaration. This is useful when many files need to have the same defaults.
The use statement was developed primarily for the networking states but can be used on any states in Salt. This made sense for the networking state because it can define a long list of options that need to be applied to multiple network interfaces.

Require In

The require_in requisite is the literal reverse of require. If a state declaration needs to be required by another state declaration then require_in can accommodate it, so these two sls files would be the same in the end:
Using require
httpd: pkg: - installed service: - running - require: - pkg: httpd
Using require_in
httpd: pkg: - installed - require_in: - service: httpd service: - running
The require_in statement is particularly useful when assigning a require in a sperate sls file. For instance it may be common for httpd to require components used to set up php or mod_python, but the http state does not need to be aware of the additional components that require it when it is set up:
http.sls
httpd: pkg: - installed service: - running - require: - pkg: httpd
php.sls
include: - http php: pkg: - installed - require_in: - service: httpd
mod_python.sls
include: - http mod_python: pkg: - installed - require_in: - service: httpd
Now the httpd server will only start if php or mod_python are first verified to be installed. Thus allowing for a requisite to be defined "after the fact".

Watch In

Watch in functions the same was as require in, but applies a watch statement rather than a require statement to the external state declaration.

Startup States

Sometimes it may be desired that the salt minion execute a state run when it is started. This alleviates the need for the master to initiate a state run on a new minion and can make provisioning much easier.

As of Salt 0.10.3 the minion config reads options that allow for states to be executed at startup. The options are startup_states, sls_list and top_file.

The startup_states option can be passed one of a number of arguments to define how to execute states. The available options are:

highstate: Execute state.highstate
sls
Read in the sls_list option and execute the named sls files
top
Read in the top_file option and execute states based on that top file on the Salt Master

Examples:

Execute state.highstate when starting the minion:
startup_states: highstate
Execute the sls files edit.vim and hyper:
startup_states: sls sls_list: - edit.vim - hyper

State Testing

Executing a Salt state run can potentially change many aspects of a system and it may be desirable to first see what a state run is going to change before applying the run.

Salt has a test interface to report on exactly what will be changed, this interface can be invoked on any of the major state run functions:

# salt \* state.highstate test=True
# salt \* state.sls test=True
# salt \* state.single test=True

The test run is mandated by adding the test=True option to the states. The return information will show states that will be applied in yellow and the result is reported as None.

Default Test

If the value test is set to True in the minion configuration file then states will default to being executed in test mode. If this value is set then states can still be run by calling test=False: # salt \* state.highstate test=False # salt \* state.sls test=False # salt \* state.single test=False

The Top File

The top file is used to map what SLS modules get loaded onto what minions via the state system. The top file creates a few general abstractions. First it maps what nodes should pull from which environments, next it defines which matches systems should draw from.

Environments

Environment: A configuration that allows conceptually organizing state tree directories. Environments can be made to be self-contained or state trees can be made to bleed through environments.
The environments in the top file corresponds with the environments defined in the file_roots variable. In a simple, single environment setup you only have the base environment, and therefore only one state tree. Here is a simple example of file_roots in the master configuration:
file_roots: base: - /srv/salt
This means that the top file will only have one environment to pull from, here is a simple, single environment top file:
base: '*': - core - edit
This also means that /srv/salt has a state tree. But if you want to use multiple environments, or partition the file server to serve more than just the state tree, then the file_roots option can be expanded:
file_roots: base: - /srv/salt/base dev: - /srv/salt/dev qa: - /srv/salt/qa prod: - /srv/salt/prod
Then our top file could reference the environments:
dev: 'webserver*dev*': - webserver 'db*dev*': - db qa: 'webserver*qa*': - webserver 'db*qa*': - db prod: 'webserver*prod*': - webserver 'db*prod*': - db
In this setup we have state trees in three of the four environments, and no state tree in the base environment. Notice that the targets for the minions specify environment data. In Salt the master determines who is in what environment, and many environments can be crossed together. For instance, a separate global state tree could be added to the base environment if it suits your deployment:
base: '*': - global dev: 'webserver*dev*': - webserver 'db*dev*': - db qa: 'webserver*qa*': - webserver 'db*qa*': - db prod: 'webserver*prod*': - webserver 'db*prod*': - db
In this setup all systems will pull the global SLS from the base environment, as well as pull from their respective environments.
Remember, that since everything is a file in Salt, the environments are primarily file server environments, this means that environments that have nothing to do with states can be defined and used to distribute other files.
A clean and recommended setup for multiple environments would look like this:
# Master file_roots configuration: file_roots: base: - /srv/salt/base dev: - /srv/salt/dev qa: - /srv/salt/qa prod: - /srv/salt/prod
Then only place state trees in the dev, qa and prod environments, leaving the base environment open for generic file transfers. Then the top.sls file would look something like this:
dev: 'webserver*dev*': - webserver 'db*dev*': - db qa: 'webserver*qa*': - webserver 'db*qa*': - db prod: 'webserver*prod*': - webserver 'db*prod*': - db

Other Ways of Targeting Minions

In addition to globs, minions can be specified in top files a few other ways. Some common ones are compound matches and node groups.
Here is a slightly more complex top file example, showing the different types of matches you can perform:
base: '*': - ldap-client - networking - salt.minion 'salt-master*': - salt.master '^(memcache|web).(qa|prod).loc$': - match: pcre - nagios.mon.web - apache.server 'os:Ubuntu': - match: grain - repos.ubuntu 'os:(RedHat|CentOS)': - match: grain_pcre - repos.epel 'foo,bar,baz': - match: list - database 'somekey:abc': - match: pillar - xyz 'nag1* or G@role:monitoring': - match: compound - nagios.server
In this example top.sls, all minions get the ldap-client, networking and salt.minion states. Any minion with an id matching the salt-master* glob will get the salt.master state. Any minion with ids matching the regular expression ^(memcache|web).(qa|prod).loc$ will get the nagios.mon.web and apache.server states. All Ubuntu minions will receive the repos.ubuntu state, while all RHEL and CentOS minions will receive the repos.epel state. The minions foo, bar, and baz will receive the database state. Any minion with a pillar named somekey, having a value of abc will receive the xyz state. Finally, minions with ids matching the nag1* glob or with a grain named role equal to monitoring will receive the nagios.server state.

State Modules

State Modules are the components that map to actual enforcement and management of Salt states.

States are Easy to Write!

State Modules should be easy to write and straightforward. The information passed to the SLS data structures will map directly to the states modules. Mapping the information from the SLS data is simple, this example should illustrate: /etc/salt/master: # maps to "name" file: # maps to State module filename eg https://github.com/saltstack/salt/blob/develop/salt/states/file.py - managed # maps to the managed function in the file State module - user: root # one of many options passed to the manage function - group: root - mode: 644 - source: salt://salt/master Therefore this SLS data can be directly linked to a module, function and arguments passed to that function. This does issue the burden, that function names, state names and function arguments should be very human readable inside state modules, since they directly define the user interface.

Using Custom State Modules

Place your custom state modules inside a _states directory within the file_roots specified by the master config file. These custom state modules can then be distributed in a number of ways. Custom state modules are distributed when state.highstate is run, or by executing the saltutil.sync_states or saltutil.sync_all functions.

Cross Calling Modules

As with Execution Modules, State Modules can also make use of the __salt__ and __grains__ data.
It is important to note that the real work of state management should not be done in the state module unless it is needed. A good example is the pkg state module. This module does not do any package management work, it just calls the pkg execution module. This makes the pkg state module completely generic, which is why there is only one pkg state module and many backend pkg execution modules.
On the other hand some modules will require that the logic be placed in the state module, a good example of this is the file module. But in the vast majority of cases this is not the best approach, and writing specific execution modules to do the backend work will be the optimal solution.

Return Data

A State Module must return a dict containing the following keys/values:
• name: The same value passed to the state as "name".
• changes: A dict describing the changes made. Each thing changed should be a key, with its value being another dict with keys called "old" and "new" containing the old/new values. For example, the pkg state's changes dict has one key for each package changed, with the "old" and "new" keys in its sub-dict containing the old and new versions of the package.
• result: A boolean value. True if the action was successful, otherwise False.
• comment: A string containing a summary of the result.

Test State

All states should check for and support test being passed in the options. This will return data about what changes would occur if the state were actually run. An example of such a check could look like this:
# Return comment of changes if test. if __opts__['test']: ret['result'] = None ret['comment'] = 'State Foo will execute with param {0}'.format(bar) return ret
Make sure to test and return before performing any real actions on the minion.

Watcher Function

If the state being written should support the watch requisite then a watcher function needs to be declared. The watcher function is called whenever the watch requisite is invoked and should be generic to the behavior of the state itself. The watcher function should accept all of the options that the normal state functions accept (as they will be passed into the watcher function). A watcher function typically is used to execute state specific reactive behavior, for instance, the watcher for the service module restarts the named service and makes it useful for the watcher to make the service react to changes in the environment. The watcher function also needs to return the same data that a normal state function returns.

Mod_init Interface

Some states need to execute something only once to ensure that an environment has been set up, or certain conditions global to the state behavior can be predefined. This is the realm of the mod_init interface.
A state module can have a function called mod_init which executes when the first state of this type is called. This interface was created primarily to improve the pkg state. When packages are installed the package metadata needs to be refreshed, but refreshing the package metadata every time a package is installed is wasteful. The mod_init function for the pkg state sets a flag down so that the first, and only the first, package installation attempt will refresh the package database (the package database can of course be manually called to refresh via the refresh option in the pkg state).
The mod_init function must accept the Low State Data for the given executing state as an argument. The low state data is a dict and can be seen by executing the state.show_lowstate function. Then the mod_init function must return a bool. If the return value is True, then the mod_init function will not be executed again, meaning that the needed behavior has been set up. Otherwise, if the mod_init function returns False, then the function will be called the next time.
A good example of the mod_init function is found in the pkg state module:
def mod_init(low): ''' Refresh the package database here so that it only needs to happen once ''' if low['fun'] == 'installed' or low['fun'] == 'latest': rtag = __gen_rtag() if not os.path.exists(rtag): open(rtag, 'w+').write('') return True else: return False
The mod_init function in the pkg state accepts the low state data as low and then checks to see if the function being called is going to install packages, if the function is not going to install packages then there is no need to refresh the package database. Therefore if the package database is prepared to refresh, then return True and the mod_init will not be called the next time a pkg state is evaluated, otherwise return False and the mod_init will be called next time a pkg state is evaluated.

Full List Of Builtin State Modules

salt.states.alias

Configuration of email aliases.

The mail aliases file can be managed to contain definitions for specific email aliases: username: alias.present: - target: user@example.com

salt.states.alias.absent(name)

Ensure that the named alias is absent

name

The alias to remove

salt.states.alias.present(name, target)

Ensures that the named alias is present with the given target

name

The local user/address to assign an alias to

target

The forwarding address

salt.states.alternatives

Configuration of the alternatives system

Control the alternatives system hadoop-0.20-conf: alternatives.install: - name: hadoop-0.20-conf - link: /etc/hadoop-0.20/conf - path: /opt/hadoop/conf - priority: 30 hadoop-0.20-conf: alternatives: - remove - name: hadoop-0.20-conf - path: /opt/hadoop/conf

salt.states.alternatives.install(name, link, path, priority)

Install new alternative for defined <name>

name

is the master name for this link group (e.g. pager)

link

is the symlink pointing to /etc/alternatives/<name>. (e.g. /usr/bin/pager)

path

is the location of one of the alternative target files. (e.g. /usr/bin/less)

priority

is an integer; options with higher numbers have higher priority in automatic mode.

salt.states.alternatives.remove(name, path)

Removes installed alternative for defined <name> and <path> or fallback to default alternative, if some defined before.

name

is the master name for this link group (e.g. pager)

path

is the location of one of the alternative target files. (e.g. /usr/bin/less)

salt.states.cmd

Execution of arbitrary commands.

The cmd state module manages the enforcement of executed commands, this state can tell a command to run under certain circumstances.

Available Functions

The cmd state only has a single function, the run function

run
Execute a command given certain conditions

A simple example:

date > /tmp/salt-run:
cmd:
    - run

Only run if another execution returns successfully, in this case truncate syslog if there is no disk space:
> /var/log/messages: cmd.run: - unless: echo 'foo' > /tmp/.test
Note that when executing a command or script, the state(ie, changed or not) of the command is unknown to Salt's state system. Therefore, by default, the cmd state assumes that any command execution results in a changed state.
This means that if a cmd state is watched by another state then the state that's watching will always be executed due to the changed state in the cmd state.
Many state functions in this module now also accept a stateful argument. If stateful is specified to be true then it is assumed that the command or script will determine its own state and communicate it back by following a simple protocol described below:

If there's nothing in the stdout of the command, then assume no changes. Otherwise, the stdout must be either in JSON or its last non-empty line must be a string of key=value pairs delimited by spaces(no spaces on the sides of =).

If it's JSON then it must be a JSON object(ie, {}). If it's key=value pairs then quoting may be used to include spaces. (Python's shlex module is used to parse the key=value string)

Two special keys or attributes are recognized in the output:

changed: bool (ie, 'yes', 'no', 'true', 'false', case-insensitive)
comment: str  (ie, any string)

So, only if 'changed' is true then assume the command execution has changed the state, and any other key values or attributes in the output will be set as part of the changes.

If there's a comment then it will be used as the comment of the state.

Here's an example of how one might write a shell script for use with a stateful command:

#!/bin/bash
#
echo "Working hard..."

# writing the state line
echo  # an empty line here so the next line will be the last.
echo "changed=yes comment='something has changed' whatever=123"

And an example salt file using this module:

Run myscript:
  cmd.run:
    - name: /path/to/myscript
    - cwd: /
    - stateful: true

Run only if myscript changed something:
  cmd.wait:
    - name: echo hello
    - cwd: /
    - watch:
      - cmd: Run myscript

Note that if the cmd.wait state also specfies stateful: true it can then be watched by some other states as well.

cmd.wait is not restricted to watching only cmd states. For example it can also watch a git state for changes
# Watch for changes to a git repo and rebuild the project on updates my-project: git.latest: - name: git@github.com/repo/foo - target: /opt/foo - rev: master cmd.wait: - name: make install - cwd: /opt/foo - watch: - git: my-project

salt.states.cmd.call(name, func, args=(), kws=None, onlyif=None, unless=None, **kwargs)

Invoke a pre-defined Python function with arguments specified in the state declaration. This function is mainly used by the salt.renderers.pydsl renderer.

The intepretation of onlyif and unless arguments are identical to those of salt.states.cmd.run(), and all other arguments(cwd, runas, ...) allowed by cmd.run are allowed here, except that their effects apply only to the commands specified in onlyif and unless rather than to the function to be invoked.

In addition the stateful argument has no effects here.

The return value of the invoked function will be interpreted as follows.

If it's a dictionary then it will be passed through to the state system, which expects it to have the usual structure returned by any salt state function.

Otherwise, the return value(denoted as result in the code below) is expected to be a JSON serializable object, and this dictionary is returned:

{ 'changes': { 'retval': result },
  'result': True if result is None else bool(result),
  'comment': result if isinstance(result, basestring) else ''
}

salt.states.cmd.mod_watch(name, **kwargs)

Execute a cmd function based on a watch call

salt.states.cmd.run(name, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, env=(), stateful=False, **kwargs)

Run a command if certain circumstances are met

name

The command to execute, remember that the command will execute with the path and permissions of the salt-minion.

onlyif

A command to run as a check, run the named command only if the command passed to the onlyif option returns true

unless

A command to run as a check, only run the named command if the command passed to the unless option returns false

cwd

The current working directory to execute the command in, defaults to /root

user

The user name to run the command as

group

The group context to run the command as

shell

The shell to use for execution, defaults to the shell grain

env

The root directory of the environment for the referencing script. The environments are defined in the master config file.

stateful

The command being executed is expected to return data about executing a state

salt.states.cmd.script(name, source=None, template=None, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, env=None, stateful=False, **kwargs): Download a script from a remote source and execute it. The name can be the source or the source value can be defined.; source
The source script being downloaded to the minion, this source script is hosted on the salt master server. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs; template

If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja, mako, and wempy are supported

name

The command to execute, remember that the command will execute with the path and permissions of the salt-minion.

onlyif

A command to run as a check, run the named command only if the command passed to the onlyif option returns true

unless

A command to run as a check, only run the named command if the command passed to the unless option returns false

cwd

The current working directory to execute the command in, defaults to /root

user

The user name to run the command as

group

The group context to run the command as

shell

The shell to use for execution, defaults to the shell grain

env

The root directory of the environment for the referencing script. The environments are defined in the master config file.

stateful

The command being executed is expected to return data about executing a state

salt.states.cmd.wait(name, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, stateful=False, **kwargs)

Run the given command only if the watch statement calls it

name

The command to execute, remember that the command will execute with the path and permissions of the salt-minion.

onlyif

A command to run as a check, run the named command only if the command passed to the onlyif option returns true

unless

A command to run as a check, only run the named command if the command passed to the unless option returns false

cwd

The current working directory to execute the command in, defaults to /root

user

The user name to run the command as

group

The group context to run the command as

shell

The shell to use for execution, defaults to /bin/sh

stateful

The command being executed is expected to return data about executing a state

salt.states.cmd.wait_call(name, func, args=(), kws=None, onlyif=None, unless=None, stateful=False, **kwargs)
salt.states.cmd.wait_script(name, source=None, template=None, onlyif=None, unless=None, cwd='/root', user=None, group=None, shell=None, env=None, stateful=False, **kwargs): Download a script from a remote source and execute it only if a watch statement calls it.; source
The source script being downloaded to the minion, this source script is hosted on the salt master server. If the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs; template

If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja, mako, and wempy are supported

name

The command to execute, remember that the command will execute with the path and permissions of the salt-minion.

onlyif

A command to run as a check, run the named command only if the command passed to the onlyif option returns true

unless

A command to run as a check, only run the named command if the command passed to the unless option returns false

cwd

The current working directory to execute the command in, defaults to /root

user

The user name to run the command as

group

The group context to run the command as

shell

The shell to use for execution, defaults to the shell grain

env

The root directory of the environment for the referencing script. The environments are defined in the master config file.

stateful

The command being executed is expected to return data about executing a state

salt.states.cron

Management of cron, the Unix command scheduler.

The cron state module allows for user crontabs to be cleanly managed. Cron declarations require a number of parameters. The timing parameters, need to be declared, minute, hour, daymonth, month and dayweek. The user who's crontab is to be edited also needs to be defined. By default the timing arguments are all * and the user is root. When making changes to an existing cron job the name declaration is the unique factor, so if and existing cron that looks like this: date > /tmp/crontest: cron.present: - user: root - minute: 5 Is changed to this: date > /tmp/crontest: cron.present: - user: root - minute: 7 - hour: 2 Then the existing cron will be updated, but if the cron command is changed, then a new cron job will be added to the user's crontab.

salt.states.cron.absent(name, user='root', minute='*', hour='*', daymonth='*', month='*', dayweek='*')

Verifies that the specified cron job is absent for the specified user, only the name is matched when removing a cron job.

name

The command that should be absent in the user crontab.

user

The name of the user who's crontab needs to be modified, defaults to the root user

minute

The information to be set into the minute section, this can be any string supported by your cron system's the minute field. Default is *

hour

The information to be set in the hour section. Default is *

daymonth

The information to be set in the day of month section. Default is *

month

The information to be set in the month section. Default is *

dayweek

The information to be set in the day of day of week section. Default is *

salt.states.cron.file(name, source_hash='', user='root', template=None, context=None, replace=True, defaults=None, env=None, backup='', **kwargs): Provides file.managed-like functionality (templating, etc.) for a pre-made crontab file, to be assigned to a given user.; name
The source file to be used as the crontab. This source file can be hosted on either the salt master server, or on an http or ftp server. For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs.; If the file is hosted on a http or ftp server then the source_hash argument is also required; source_hash

This can be either a file which contains a source hash string for the source, or a source hash string. The source hash string is the hash algorithm followed by the hash of the file: md5=e138491e9d5b97023cea823fe17bac22

user

The user to whome the crontab should be assigned. This defaults to root.

template

If this setting is applied then the named templating engine will be used to render the downloaded file. Currently, jinja and mako are supported.

context

Overrides default context variables passed to the template.

replace

If the crontab should be replaced, if False then this command will be ignored if a crontab exists for the specified user. Default is True.

defaults

Default context passed to the template.

backup

Overrides the default backup mode for the user's crontab.

salt.states.cron.present(name, user='root', minute='*', hour='*', daymonth='*', month='*', dayweek='*')

Verifies that the specified cron job is present for the specified user. For more advanced information about what exactly can be set in the cron timing parameters check your cron system's documentation. Most Unix-like systems' cron documentation can be found via the crontab man page: man 5 crontab.

name

The command that should be executed by the cron job.

user

The name of the user who's crontab needs to be modified, defaults to the root user

minute

The information to be set into the minute section, this can be any string supported by your cron system's the minute field. Default is *

hour

The information to be set in the hour section. Default is *

daymonth

The information to be set in the day of month section. Default is *

month

The information to be set in the month section. Default is *

dayweek

The information to be set in the day of day of week section. Default is *

salt.states.debconfmod

Management of debconf selections.

The debconfmod state module manages the enforcement of debconf selections, this state can set those selections prior to package installation.

Available Functions

The debconfmod state has two functions, the set and set_file functions

set
Set debconf selections from the state itself

set_file

Set debconf selections from a file

nullmailer-debconf: debconf.set: - name: nullmailer - data: 'shared/mailname': {'type': 'string', 'value': 'server.domain.tld'} 'nullmailer/relayhost': {'type': 'string', 'value': 'mail.domain.tld'} ferm-debconf: debconf.set: - name: ferm - data: 'ferm/enable': {'type': 'boolean', 'value': True}

salt.states.debconfmod.set(name, data)

Set debconf selections

<state_id>:
  debconf.set:
    - name: <name>
    - data:
        <question>: {'type': <type>, 'value': <value>}
        <question>: {'type': <type>, 'value': <value>}

<state_id>:
  debconf.set:
    - name: <name>
    - data:
        <question>: {'type': <type>, 'value': <value>}
        <question>: {'type': <type>, 'value': <value>}

name:

The package name to set answers for.

data:

A set of questions/answers for debconf. Note that everything under this must be indented twice.

question:

The question the is being pre-answered

type:

The type of question that is being asked (string, boolean, select, etc.)

value:

The answer to the question

salt.states.debconfmod.set_file(name, source)

Set debconf selections from a file

<state_id>:
  debconf.set_file:
    - source: salt://pathto/pkg.selections

source:

The location of the file containing the package selections

salt.states.file

Operations on files, directories and symlinks.

Salt States can aggressively manipulate files on a system. There are a number of ways in which files can be managed.
Regular files can be enforced with the managed function. This function downloads files from the salt master and places them on the target system. The downloaded files can be rendered as a jinja, mako, or wempy template adding a dynamic component to file management. An example of file.managed which makes use of the jinja templating system would look like this:
/etc/http/conf/http.conf: file.managed: - source: salt://apache/http.conf - user: root - group: root - mode: 644 - template: jinja - context: custom_var: "override" - defaults: custom_var: "default value" other_var: 123
Directories can be managed via the directory function. This function can create and enforce the permissions on a directory. A directory statement will look like this:
/srv/stuff/substuf: file.directory: - user: fred - group: users - mode: 755 - makedirs: True
If you need to enforce user and/or group ownership recursively on the directory's contents, you can do so by adding a recurse directive:
/srv/stuff/substuf: file.directory: - user: fred - group: users - mode: 755 - makedirs: True - recurse: - user - group
Symlinks can be easily created, the symlink function is very simple and only takes a few arguments:
/etc/grub.conf: file.symlink: - target: /boot/grub/grub.conf
Recursive directory management can also be set via the recurse function. Recursive directory management allows for a directory on the salt master to be recursively copied down to the minion. This is a great tool for deploying large code and configuration systems. A recurse state would look something like this:
/opt/code/flask: file.recurse: - source: salt://code/flask - include_empty: True
salt.states.file.absent(name): Verify that the named file or directory is absent, this will work to reverse any of the functions in the file state module.; name
The path which should be deleted
salt.states.file.accumulated(name, filename, text, **kwargs): Prepare accumulator which can be used in template in file.managed state. accumulator dictionary becomes available in template.; name
Accumulator name; filename

Filename which would receive this accumulator (see file.managed state documentation about ''name``)

text

String or list for adding in accumulator

require_in / watch_in

One of them required for sure we fill up accumulator before we manage the file. Probably the same as filename

salt.states.file.append(name, text=None, makedirs=False, source=None, source_hash=None)

Ensure that some text appears at the end of a file

The text will not be appended again if it already exists in the file. You may specify a single line of text or a list of lines to append.

Multi-line example:

/etc/motd:
  file.append:
    - text: |
        Thou hadst better eat salt with the Philosophers of Greece,
        than sugar with the Courtiers of Italy.
        - Benjamin Franklin

Multiple lines of text:

/etc/motd:
  file.append:
    - text:
      - Trust no one unless you have eaten much salt with him.
      - Salt is born of the purest of parents: the sun and the sea.

New in version 0.9.5.

salt.states.file.comment(name, regex, char='#', backup='.bak')

Comment out specified lines in a file.

path

The full path to the file to be edited

regex

A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing ^ or $ characters outside the parenthesis (e.g., the pattern ^foo$ will be rewritten as ^(foo)$) Note that you _need_ the leading ^, otherwise each time you run highstate, another comment char will be inserted.

char

# The character to be inserted at the beginning of a line in order to comment it out

backup

.bak The file will be backed up before edit with this file extension

Warning

This backup will be overwritten each time sed / comment / uncomment is called. Meaning the backup will only be useful after the first invocation.

Usage:

/etc/fstab:
  file.comment:
    - regex: ^bind 127.0.0.1

New in version 0.9.5.

salt.states.file.directory(name, user=None, group=None, recurse=None, mode=None, makedirs=False, clean=False, require=None, exclude_pat=None, **kwargs)

Ensure that a named directory is present and has the right perms

name

The location to create or manage a directory

user

The user to own the directory, this defaults to the user salt is running as on the minion

group

The group ownership set for the directory, this defaults to the group salt is running as on the minion

recurse

Enforce user/group ownership of directory recursively

mode

The permissions to set on this directory, aka 755

makedirs

If the directory is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file.

clean

Make sure that only files that are set up by salt and required by this function are kept. If this option is set then everything in this directory will be deleted unless it is required.

require

Require other resources such as packages or files

exclude_pat

When 'clean' is set to True, exclude this pattern from removal list and preserve in the destination.

salt.states.file.exists(name)

Verify that the named file or directory is present or exists. Ensures pre-requisites outside of salts per-vue have been previously satisified (aka, keytabs, private keys, etc.) before deployment

name

Absolute path which must exist

salt.states.file.managed(name, source=None, source_hash='', user=None, group=None, mode=None, template=None, makedirs=False, context=None, replace=True, defaults=None, env=None, backup='', **kwargs)

Manage a given file, this function allows for a file to be downloaded from the salt master and potentially run through a templating system.

name

The location of the file to manage

source

The source file to download to the minion, this source file can be hosted on either the salt master server, or on an http or ftp server. For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs. If source is left blank or None, the file will be created as an empty file and the content will not be managed

If the file is hosted on a http or ftp server then the source_hash argument is also required

source_hash:

The file can contain checksums for several files, in this case every line must consist of full name of the file and checksum separated by space:

Example:

/etc/rc.conf md5=ef6e82e4006dee563d98ada2a2a80a27
/etc/resolv.conf sha256=c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a

user

The user to own the file, this defaults to the user salt is running as on the minion

group

The group ownership set for the file, this defaults to the group salt is running as on the minion

mode

The permissions to set on this file, aka 644, 0775, 4664

template

If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja, mako, and wempy are supported

makedirs

If the file is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file.

replace

If this file should be replaced. If false, this command will not overwrite file contents but will enforce permissions if the file exists already. Default is true.

context

Overrides default context variables passed to the template.

defaults

Default context passed to the template.

backup

Overrides the default backup mode for this specific file

salt.states.file.patch(name, source=None, hash=None, options='', dry_run_first=True, env='base')

Apply a patch to a file. Note: a suitable patch executable must be available on the minion when using this state function.

name

The file to with the patch will be applied.

source

The source patch to download to the minion, this source file must be hosted on the salt master server. If the file is located in the directory named spam, and is called eggs, the source string is salt://spam/eggs. A source is required.

hash

Hash of the patched file. If the hash of the target file matches this value then the patch is assumed to have been applied. The hash string is the hash algorithm followed by the hash of the file: md5=e138491e9d5b97023cea823fe17bac22

options

Extra options to pass to patch.

dry_run_first

True Run patch with --dry-run first to check if it will apply cleanly.

Usage:

# Equivalent to ``patch --forward /opt/file.txt file.patch``
/opt/file.txt:
  file.patch:
    - source: salt://file.patch
    - hash: md5=e138491e9d5b97023cea823fe17bac22

salt.states.file.recurse(name, source, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, template=None, context=None, defaults=None, env=None, include_empty=False, backup='', include_pat=None, exclude_pat=None, **kwargs)

Recurse through a subdirectory on the master and copy said subdirectory over to the specified path.

name

The directory to set the recursion in

source

The source directory, this directory is located on the salt master file server and is specified with the salt:// protocol. If the directory is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs

clean

Make sure that only files that are set up by salt and required by this function are kept. If this option is set then everything in this directory will be deleted unless it is required.

require

Require other resources such as packages or files

user

The user to own the directory, this defaults to the user salt is running as on the minion

group

The group ownership set for the directory, this defaults to the group salt is running as on the minion

dir_mode

The permissions mode to set any directories created

file_mode

The permissions mode to set any files created

template

If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja, mako, and wempy are supported

context

Overrides default context variables passed to the template.

defaults

Default context passed to the template.

include_empty

Set this to True if empty directories should also be created (default is False)

include_pat

When copying, include only this pattern from the source. Default is glob match , if prefixed with E@ then regexp match Example:

- include_pat: hello*       :: glob matches 'hello01', 'hello02' ... but not 'otherhello'
- include_pat: E@hello      :: regexp matches 'otherhello', 'hello01' ...

exclude_pat

When copying, exclude this pattern from the source. If both include_pat and exclude_pat are supplied, then it will apply conditions cumulatively. i.e. first select based on include_pat and then with in that result, applies exclude_pat.

Also when 'clean=True', exclude this pattern from the removal list and preserve in the destination. Example:

- exclude: APPDATA*               :: glob matches APPDATA.01, APPDATA.02,.. for exclusion
- exclude: E@(APPDATA)|(TEMPDATA) :: regexp matches APPDATA or TEMPDATA for exclusion

salt.states.file.rename(name, source, force=False, makedirs=False)

If the source file exists on the system, rename it to the named file. The named file will not be overwritten if it already exists unless the force option is set to True.

name

The location of the file to rename to

source

The location of the file to move to the location specified with name

force:

If the target location is present then the file will not be moved, specify "force: True" to overwrite the target file

makedirs:

If the target subdirectories don't exist create them

salt.states.file.sed(name, before, after, limit='', backup='.bak', options='-r -e', flags='g')

Maintain a simple edit to a file

The file will be searched for the before pattern before making the edit and then searched for the after pattern to verify the edit was successful using salt.modules.file.contains. In general the limit pattern should be as specific as possible and before and after should contain the minimal text to be changed.

Usage:

# Disable the epel repo by default
/etc/yum.repos.d/epel.repo:
  file.sed:
    - before: 1
    - after: 0
    - limit: ^enabled=

# Remove ldap from nsswitch
/etc/nsswitch.conf:
  file.sed:
    - before: 'ldap'
    - after: ''
    - limit: '^passwd:'

New in version 0.9.5.

salt.states.file.symlink(name, target, force=False, makedirs=False, user=None, group=None, mode=None, **kwargs)

Create a symlink

name

The location of the symlink to create

target

The location that the symlink points to

force

If the location of the symlink exists and is not a symlink then the state will fail, set force to True and any file or directory in the way of the symlink file will be deleted to make room for the symlink

makedirs

If the location of the symlink does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory

salt.states.file.touch(name, atime=None, mtime=None, makedirs=False)

Replicate the 'nix "touch" command to create a new empty file or update the atime and mtime of an existing file.

Usage:

/var/log/httpd/logrotate.empty:
  file.touch

New in version 0.9.5.

salt.states.file.uncomment(name, regex, char='#', backup='.bak')

Uncomment specified commented lines in a file

path

The full path to the file to be edited

regex

char

# The character to remove in order to uncomment a line; if a single whitespace character follows the comment it will also be removed

backup

.bak The file will be backed up before edit with this file extension; WARNING: each time sed/comment/uncomment is called will overwrite this backup

Usage:

/etc/adduser.conf:
  file.uncomment:
    - regex: EXTRA_GROUPS

New in version 0.9.5.

salt.states.gem

Installation of Ruby modules packaged as gems.

A state module to manage rubygems. Gems can be set up to be installed or removed. This module will use RVM if it is installed. In that case you can specify what ruby version and gemset to target. addressable: gem.installed: - runas: rvm - ruby: jruby@jgemset

salt.states.gem.installed(name, ruby=None, runas=None, version=None, rdoc=False, ri=False)

Make sure that a gem is installed.

name

The name of the gem to install

ruby

None For RVM installations: the ruby version and gemset to target.

runas

None The user to run gem as.

version

None Specify the version to install for the gem. Doesn't play nice with multiple gems at once

rdoc

False Generate RDoc documentation for the gem(s).

False Generate RI documentation for the gem(s).

salt.states.gem.removed(name, ruby=None, runas=None)

Make sure that a gem is not installed.

name

The name of the gem to uninstall

ruby

None For RVM installations: the ruby version and gemset to target.

runas

None The user to run gem as.

salt.states.git

Interaction with Git repositories.

NOTE: This modules is under heavy development and the API is subject to change. It may be replaced with a generic VCS module if this proves viable. Important, before using git over ssh, make sure your remote host fingerprint exists in "~/.ssh/known_hosts" file. https://github.com/saltstack/salt.git: git.latest: - rev: develop - target: /tmp/salt

salt.states.git.latest(name, rev=None, target=None, runas=None, force=None, submodules=False, mirror=False, bare=False)

Make sure the repository is cloned to the given directory and is up to date

name

Address of the remote repository as passed to "git clone"

rev

The remote branch, tag, or revision ID to checkout after clone / before update

target

Name of the target directory where repository is about to be cloned

runas

Name of the user performing repository management operations

force

Force git to clone into pre-existing directories (deletes contents)

submodules

Update submodules on clone or branch change (Default: False)

mirror

True if the repository is to be a mirror of the remote repository. This implies bare, and thus is incompatible with rev.

bare

True if the repository is to be a bare clone of the remote repository. This is incompatible with rev, as nothing will be checked out.

salt.states.git.present(name, bare=True, runas=None, force=False)

Make sure the repository is present in the given directory

name

Name of the directory where the repository is about to be created

bare

Create a bare repository (Default: True)

runas

Name of the user performing repository management operations

force

Force create a new repository into an pre-existing non-git directory (deletes contents)

salt.states.group

Management of user groups.

The group module is used to create and manage unix group settings, groups can be either present or absent: cheese: group.present: - gid: 7648 - system: True

salt.states.group.absent(name)

Ensure that the named group is absent

name

The name of the group to remove

salt.states.group.present(name, gid=None, system=False)

Ensure that a group is present

name

The name of the group to manage

gid

The group id to assign to the named group, if left empty then the next available group id will be assigned

salt.states.hg

Interaction with Mercurial repositories.

NOTE: This module is currently experimental. Most of this code is copied from git.py with changes to handle hg. Before using hg over ssh, make sure the remote host fingerprint already exists in ~/.ssh/known_hosts, and the remote host has this host's public key. https://bitbucket.org/example_user/example_repo: hg.latest: - rev: tip - target: /tmp/example_repo

salt.states.hg.latest(name, rev=None, target=None, runas=None, force=False)

Make sure the repository is cloned to to given directory and is up to date

name

Address of the remote repository as passed to "hg clone"

rev

The remote branch, tag, or revision hash to clone/pull

target

Name of the target directory where repository is about to be cloned

runas

Name of the user performing repository management operations

force

Force hg to clone into pre-existing directories (deletes contents)

salt.states.host

Management of addresses and names in hosts file.

The /etc/hosts file can be managed to contain definitions for specific hosts:
salt-master: host.present: - ip: 192.168.0.42
Or using the "names:" directive, you can put several names for the same IP. (Do not try one name with space-seperated values).
server1: host.present: - ip: 192.168.0.42 - names: - server1 - florida
NOTE: changing the IP or name(s) in the present() function does not cause an update to remove the old entry.

salt.states.host.absent(name, ip)

Ensure that the named host is absent

name

The host to remove

The ip addr of the host to remove

salt.states.host.present(name, ip)

Ensures that the named host is present with the given ip

name

The host to assign an ip to

The ip addr to apply to the host

salt.states.keyboard

Management of keyboard layouts

The keyboard layout can be managed for the system: us: keyboard.system Or it can be managed for XOrg: us: keyboard.xorg
salt.states.keyboard.system(name): Set the keyboard layout for the system; name
The keyboard layout to use
salt.states.keyboard.xorg(name): Set the keyboard layout for XOrg; layout
The keyboard layout to use

salt.states.kmod

Loading and unloading of kernel modules.

The Kernel modules on a system can be managed cleanly with the kmod state module: kvm_amd: kmod.present pcspkr: kmod.absent
salt.states.kmod.absent(name, persist=False, comment=True): Verify that the named kernel module is not loaded; name
The name of the kernel module to verify is not loaded; persist

Delete module from /etc/modules

comment

Don't remove module from /etc/modules, only comment it

salt.states.kmod.present(name, persist=False): Ensure that the specified kernel module is loaded; name
The name of the kernel module to verify is loaded; persist

Also add module to /etc/modules

salt.states.layman

Mangement of Gentoo Overlays using layman

A state module to manage Gentoo package overlays via layman sunrise: layman.present
salt.states.layman.absent(name): Verify that the overlay is absent; name
The name of the overlay to delete
salt.states.layman.present(name): Verify that the overlay is present; name
The name of the overlay to add

salt.states.locale

Management of languages/locales ==============================+ The locale can be managed for the system: en_US.UTF-8: locale.system
salt.states.locale.system(name): Set the locale for the system; name
The name of the locale to use

salt.states.makeconf

Management of Gentoo make.conf

A state module to manage Gentoo's make.conf file makeopts: makeconf.present: - value: '-j3'

salt.states.makeconf.absent(name)

Verify that the variable is not in the make.conf.

name

The variable name. This will automatically be converted to all Upper Case since variables in make.conf are Upper Case

salt.states.makeconf.present(name, value=None, contains=None, excludes=None)

Verify that the variable is in the make.conf and has the provided settings. If value is set, contains and excludes will be ignored.

name

The variable name. This will automatically be converted to all Upper Case since variables in make.conf are Upper Case

value

Enforce that the value of the variable is set to the provided value

contains

Enforce that the value of the variable cotains the provided value

excludes

Enforce that the value of the variable does not contain the provided value.

salt.states.module

Execution of Salt modules from within states.

Individual module calls can be made via states. to call a single module function use the run function. One issue exists, since the name argument is present in the state call and is present in many modules, this argument will need to be replaced in the sls data with the argument m_name.
salt.states.module.mod_watch(name, **kwargs): Run a single module function; name
The module function to execute; returner

Specify the returner to send the return of the module execution to

**kwargs

Pass any arguments needed to execute the function

salt.states.module.run(name, **kwargs): Run a single module function; name
The module function to execute; returner

Specify the returner to send the return of the module execution to

**kwargs

Pass any arguments needed to execute the function

salt.states.module.wait(name, **kwargs): Run a single module function only if the watch statement calls it; name
The module function to execute; **kwargs

Pass any arguments needed to execute the function

salt.states.mongodb_database

Management of Mongodb databases Only deletion is supported, creation doesnt make sense and can be done using mongodb_user.present

salt.states.mongodb_database.absent(name, user=None, password=None, host=None, port=None)

Ensure that the named database is absent

name

The name of the database to remove

user

The user to connect as (must be able to create the user)

password

The password of the user

host

The host to connect to

port

The port to connect to

salt.states.mongodb_user

Management of Mongodb users

salt.states.mongodb_user.absent(name, user=None, password=None, host=None, port=None, database='admin')

Ensure that the named user is absent

name

The name of the user to remove

user

The user to connect as (must be able to create the user)

password

The password of the user

host

The host to connect to

port

The port to connect to

database

The database to create the user in (if the db doesn't exist, it will be created)

salt.states.mongodb_user.present(name, passwd, database='admin', user=None, password=None, host=None, port=None)

Ensure that the user is present with the specified properties

name

The name of the user to manage

passwd

The password of the user

user

The user to connect as (must be able to create the user)

password

The password of the user

host

The host to connect to

port

The port to connect to

database

The database to create the user in (if the db doesn't exist, it will be created)

salt.states.mount

Mounting of filesystems.

Mount any type of mountable filesystem with the mounted function: /mnt/sdb: mount.mounted: - device: /dev/sdb1 - fstype: ext4 - mkmnt: True - opts: - defaults

salt.states.mount.mounted(name, device, fstype, mkmnt=False, opts=None, dump=0, pass_num=0, config='/etc/fstab', persist=True)

Verify that a device is mounted

name

The path to the location where the device is to be mounted

device

The device name, typically the device node, such as /dev/sdb1

fstype

The filesystem type, this will be xfs, ext2/3/4 in the case of classic filesystems, and fuse in the case of fuse mounts

mkmnt

If the mount point is not present then the state will fail, set mkmnt to True to create the mount point if it is otherwise not present

opts

A list object of options or a comma delimited list

dump

The dump value to be passed into the fstab, default to 0

pass_num

The pass value to be passed into the fstab, default to 0

config

Set an alternative location for the fstab, default to /etc/fstab

remount

Set if the file system can be remounted with the remount option, default to True

persist

Set if the mount should be saved in the fstab, default to True

salt.states.mysql_database

Management of MySQL databases (schemas).

NOTE: This module requires the MySQLdb python module and the proper settings in the minion config file. See salt.modules.mysql for more information. The mysql_database module is used to create and manage MySQL databases. Databases can be set as either absent or present. frank: mysql_database.present
salt.states.mysql_database.absent(name): Ensure that the named database is absent; name
The name of the database to remove
salt.states.mysql_database.present(name): Ensure that the named database is present with the specified properties; name
The name of the database to manage

salt.states.mysql_grants

Management of MySQL grants (user permissions).

NOTE: This module requires the MySQLdb python module and the proper settings in the minion config file. See salt.modules.mysql for more information.
The mysql_grants module is used to grant and revoke MySQL permissions.
The name you pass in purely symbolic and does not have anything to do with the grant itself.
The database parameter needs to specify a 'priv_level' in the same specification as defined in the MySQL documentation:

• * • *.* • db_name.* • db_name.tbl_name • etc...

frank_exampledb: mysql_grants.present: - grant: select,insert,update - database: exampledb.* - user: frank - host: localhost frank_otherdb: mysql_grants.present: - grant: all privileges - database: otherdb.* - user: frank restricted_singletable: mysql_grants.present: - grant: select - database: somedb.sometable - user: joe

salt.states.mysql_grants.absent(name, grant=None, database=None, user=None, host='localhost', grant_option=False, escape=True)

Ensure that the grant is absent

name

The name (key) of the grant to add

grant

The grant priv_type (ie. select,insert,update OR all privileges)

database

The database priv_level (ie. db.tbl OR db.*)

user

The user to apply the grant to

host

The MySQL server

salt.states.mysql_grants.present(name, grant=None, database=None, user=None, host='localhost', grant_option=False, escape=True)

Ensure that the grant is present with the specified properties

name

The name (key) of the grant to add

grant

The grant priv_type (ie. select,insert,update OR all privileges)

database

The database priv_level (ie. db.tbl OR db.*)

user

The user to apply the grant to

host

The MySQL server

grant_option

Adds the WITH GRANT OPTION to the defined grant. default: False

excape

Defines if the database value gets escaped or not. default: True

salt.states.mysql_user

Management of MySQL users.

NOTE: This module requires the MySQLdb python module and the proper settings in the minion config file. See salt.modules.mysql for more information. The mysql_user module is used to manage MySQL users. frank: mysql_user.present: - host: localhost - password: bobcat
salt.states.mysql_user.absent(name, host='localhost'): Ensure that the named user is absent; name
The name of the user to remove
salt.states.mysql_user.present(name, host='localhost', password=None, password_hash=None): Ensure that the named user is present with the specified properties; name
The name of the user to manage; password

The password

password_hash

The password in hashed form. Be sure to quote the password because YAML does't like the *:

SELECT PASSWORD('mypass') ==> *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4

salt.states.network

Configuration of network interfaces.

The network module is used to create and manage network settings, interfaces can be set as either managed or ignored. By default all interfaces are ignored unless specified. Please note that only Redhat-style networking is currently supported. This module will therefore only work on RH/CentOS/Fedora. system: network.system: - enabled: True - hostname: server1.example.com - gateway: 192.168.0.1 - gatewaydev: eth0 - nozeroconf: True - nisdomain: example.com - require_reboot: True eth0: network.managed: - enabled: True - type: eth - proto: none - ipaddr: 10.1.0.1 - netmask: 255.255.255.0 - dns: - 8.8.8.8 - 8.8.4.4 eth2: network.managed: - type: slave - master: bond0 eth3: network.managed: - type: slave - master: bond0 eth4: network.managed: - enabled: True - type: eth - proto: dhcp - bridge: br0 bond0: network.managed: - type: bond - ipaddr: 10.1.0.1 - netmask: 255.255.255.0 - dns: - 8.8.8.8 - 8.8.4.4 - ipv6: - enabled: False - use_in: - network: eth2 - network: eth3 - require: - network: eth2 - network: eth3 - mode: 802.3ad - miimon: 100 - arp_interval: 250 - downdelay: 200 - lacp_rate: fast - max_bonds: 1 - updelay: 0 - use_carrier: on - xmit_hash_policy: layer2 - mtu: 9000 - autoneg: on - speed: 1000 - duplex: full - rx: on - tx: off - sg: on - tso: off - ufo: off - gso: off - gro: off - lro: off bond0.2: network.managed: - type: vlan - ipaddr: 10.1.0.2 - use: - network: bond0 - require: - network: bond0 bond0.3: network.managed: - type: vlan - ipaddr: 10.1.0.3 - use: - network: bond0 - require: - network: bond0 bond0.10: network.managed: - type: vlan - ipaddr: 10.1.0.4 - use: - network: bond0 - require: - network: bond0 bond0.12: network.managed: - type: vlan - ipaddr: 10.1.0.5 - use: - network: bond0 - require: - network: bond0 br0: network.managed: - enabled: True - type: bridge - proto: dhcp - bridge: br0 - delay: 0 - bypassfirewall: True - use: - network: eth4 - require: - network: eth4

salt.states.network.managed(name, type, enabled=True, **kwargs)

Ensure that the named interface is configured properly.

name

The name of the interface to manage

type

Type of interface and configuration.

enabled

Designates the state of this interface.

kwargs

The IP parameters for this interface.

salt.states.network.system(name, **kwargs)

Ensure that global network settings are configured properly.

name

Custom name to represent this configuration change.

kwargs

The global parameters for the system.

salt.states.pecl

Installation of PHP pecl extensions.

A state module to manage php pecl extensions. mongo: pecl.installed
salt.states.pecl.installed(name): Make sure that a pecl extension is installed.; name
The pecl extension name to install
salt.states.pecl.removed(name): Make sure that a pecl extension is not installed.; name
The pecl exntension name to uninstall

salt.states.pip

Installation of Python packages using pip.

A state module to manage system installed python packages virtualenvwrapper: pip.installed
salt.states.pip.installed(name, pip_bin=None, requirements=None, env=None, bin_env=None, log=None, proxy=None, timeout=None, repo=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, no_deps=False, no_install=False, no_download=False, install_options=None, user=None, cwd=None, __env__='base'): Make sure the package is installed; name
The name of the python package to install; pip_bin

None Deprecated, use bin_env

env

None Deprecated, use bin_env

bin_env

None the pip executable or virtualenv to use

salt.states.pip.removed(name, packages=None, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, user=None, cwd=None, __env__='base'): Make sure that a package is not installed.; name
The name of the package to uninstall; bin_env

None the pip executable or virtualenenv to use

salt.states.pkgng

Manage package remote repo using FreeBSD pkgng.

Salt can manage the url pkgng pulls packages from. ATM the state and module are small so use cases are typically rather simple: pkgng_clients: pkgng: - update_packaging_site - name: "http://192.168.0.2"
salt.states.pkgng.update_packaging_site(name)

salt.states.pkg

Installation of packages using OS package managers such as yum or apt-get.

Salt can manage software packages via the pkg state module, packages can be set up to be installed, latest, removed and purged. Package management declarations are typically rather simple: vim: pkg.installed
salt.states.pkg.installed(name, version=None, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, sources=None, **kwargs): Verify that the package is installed, and that it is the correct version (if specified).; name
The name of the package to be installed. This parameter is ignored if either "pkgs" or "sources" is used. Additionally, please note that this option can only be used to install packages from a software repository. To install a package file manually, use the "sources" option detailed below.; fromrepo

Specify a repository from which to install

skip_verify

Skip the GPG verification check for the package to be installed

version

Install a specific version of a package. This option is ignored if either "pkgs" or "sources" is used. Currently, this option is supported for the following pkg providers: apt, ebuild, pacman, yumpkg, yumpkg5, and zypper.

Usage:

httpd:
  pkg.installed:
    - fromrepo: mycustomrepo
    - skip_verify: True
    - version: 2.0.6~ubuntu3

Multiple Package Installation Options: (not supported in Windows or pkgng)

pkgs

A list of packages to install from a software repository.

Usage:

mypkgs:
  pkg.installed:
    - pkgs:
      - foo
      - bar
      - baz

NOTE: For apt, ebuild, pacman, yumpkg, yumpkg5, and zypper, version numbers can be specified in the pkgs argument. Example:

mypkgs:
  pkg.installed:
    - pkgs:
      - foo
      - bar: 1.2.3-4
      - baz

Additionally, ebuild, pacman and zypper support the <, <=, >=, and > operators for more control over what versions will be installed. Example:

mypkgs:
  pkg.installed:
    - pkgs:
      - foo
      - bar: '>=1.2.3-4'
      - baz

NOTE: When using comparison operators, the expression must be enclosed in quotes to avoid a YAML render error.

sources

A list of packages to install, along with the source URI or local path from which to install each package.

Usage:

mypkgs:
  pkg.installed:
    - sources:
      - foo: salt://rpms/foo.rpm
      - bar: http://somesite.org/bar.rpm
      - baz: ftp://someothersite.org/baz.rpm
      - qux: /minion/path/to/qux.rpm

salt.states.pkg.latest(name, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, **kwargs)

Verify that the named package is installed and the latest available package. If the package can be updated this state function will update the package. Generally it is better for the installed function to be used, as latest will update the package whenever a new package is available.

name

The name of the package to maintain at the latest available version. This parameter is ignored if "pkgs" is used.

fromrepo

Specify a repository from which to install

skip_verify

Skip the GPG verification check for the package to be installed

Multiple Package Installation Options:

(Not yet supported for: Windows, FreeBSD, OpenBSD, MacOS, and Solaris pkgutil)

pkgs

A list of packages to maintain at the latest available version.

Usage:

mypkgs:
  pkg.latest:
    - pkgs:
      - foo
      - bar
      - baz

salt.states.pkg.purged(name, **kwargs)

Verify that the package is purged, this will call the purge function in the salt pkg module for the platform.

name

The name of the package to be purged

salt.states.pkg.removed(name, **kwargs)

Verify that the package is removed, this will remove the package via the remove function in the salt pkg module for the platform.

name

The name of the package to be removed

salt.states.pkgrepo

Management of package repos

Package repositories can be managed with the pkgrepo state: base: pkgrepo.managed: - human_name: CentOS-$releasever - Base - mirrorlist: http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=os - comments: - #http://mirror.centos.org/centos/$releasever/os/$basearch/ - gpgcheck: 1 - gpgkey: file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-6
salt.states.pkgrepo.absent(name): This function deletes the specified repo on the system, if it exists. It is essentially a wrapper around pkg.del_repo.; name
The name of the package repo, as it would be referred to when running the regular package manager commands.
salt.states.pkgrepo.managed(name, **kwargs): This function manages the configuration on a system that points to the repositories for the system's package manager.; name
The name of the package repo, as it would be referred to when running the regular package manager commands.; For yum-based systems, take note of the following configuration values:; humanname

On yum-based systems, this is stored as the "name" value in the .repo file in /etc/yum.repos.d/. On yum-based systems, this is required.

baseurl

On yum-based systems, baseurl refers to a direct URL to be used for this yum repo. One of baseurl or mirrorlist is required.

mirrorlist

a URL which contains a collection of baseurls to choose from. On yum-based systems. One of baseurl or mirrorlist is required.

comments

Sometimes you want to supply additional information, but not as enabled configuration. Anything supplied for this list will be saved in the repo configuration with a comment marker (#) in front.

Additional configuration values, such as gpgkey or gpgcheck, are used verbatim to update the options for the yum repo in question.

For apt-based systems, take note of the following configuration values:

name:

on apt-based systems this must be the complete entry as it would be seen in the sources.list file. This can have a limited subset of components (i.e. 'main') which can be added/modified with the "comps" option.

EXAMPLE: deb http://us.archive.ubuntu.com/ubuntu/ precise main

disabled

On apt-based systems, disabled toggles whether or not the repo is used for resolving dependancies and/or installing packages

comps

On apt-based systems, comps dictate the types of packages to be installed from the repository (e.g. main, nonfree, ...). For purposes of this, comps should be a comma-separated list.

file

The filename for the .list that the repository is configured in. It is important to include the full-path AND make sure it is in a directory that APT will look in when handling packages

dist

This dictates the release of the distro the packages should be built for. (e.g. unstable)

keyid

The KeyID of the GPG key to install. This option also requires the 'keyserver' option to be set.

keyserver

This is the name of the keyserver to retrieve gpg keys from. The keyid option must also be set for this option to work.

key_url

A web url to retreive the GPG key from.

consolidate:

If set to true, this will consolidate all sources definitions to the sources.list file, cleanup the now unused files, consolidate components (e.g. main) for the same uri, type, and architecture to a single line, and finally remove comments from the sources.list file. The consolidate will run every time the state is processed. The option only needs to be set on one repo managed by salt to take effect.

salt.states.postgres_database

Management of PostgreSQL databases.

The postgres_database module is used to create and manage Postgres databases. Databases can be set as either absent or present frank: postgres_database.present

salt.states.postgres_database.absent(name, runas=None)

Ensure that the named database is absent

name

The name of the database to remove

runas

System user all operation should be preformed on behalf of

salt.states.postgres_database.present(name, tablespace=None, encoding=None, locale=None, lc_collate=None, lc_ctype=None, owner=None, template=None, runas=None)

Ensure that the named database is present with the specified properties. For more information about all of these options see man createdb(1)

name

The name of the database to manage

tablespace

Default tablespace for the database

encoding

The character encoding scheme to be used in this database

locale

The locale to be used in this database

lc_collate

The LC_COLLATE setting to be used in this database

lc_ctype

The LC_CTYPE setting to be used in this database

owner

The username of the database owner

template

The template database from which to build this database

runas

System user all operation should be preformed on behalf of

salt.states.postgres_user

Management of PostgreSQL users (roles).

The postgres_users module is used to create and manage Postgres users. frank: postgres_user.present

salt.states.postgres_user.absent(name, runas=None)

Ensure that the named user is absent

name

The username of the user to remove

runas

System user all operation should be preformed on behalf of

salt.states.postgres_user.present(name, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, groups=None, runas=None)

Ensure that the named user is present with the specified privileges

name

The name of the user to manage

createdb

Is the user allowed to create databases?

createuser

Is the user allowed to create other users?

encrypted

Should the password be encrypted in the system catalog?

superuser

Should the new user be a "superuser"

replication

Should the new user be allowed to initiate streaming replication

password

The user's pasword

groups

A string of comma seperated groups the user should be in

runas

System user all operation should be preformed on behalf of

salt.states.postgres_group

Management of PostgreSQL groups (roles).

The postgres_group module is used to create and manage Postgres groups. frank: postgres_group.present

salt.states.postgres_group.absent(name, runas=None)

Ensure that the named group is absent

name

The groupname of the group to remove

runas

System user all operation should be preformed on behalf of

salt.states.postgres_group.present(name, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, groups=None, runas=None)

Ensure that the named group is present with the specified privileges

name

The name of the group to manage

createdb

Is the group allowed to create databases?

createuser

Is the group allowed to create other users?

encrypted

Should the password be encrypted in the system catalog?

superuser

Should the new group be a "superuser"

replication

Should the new group be allowed to initiate streaming replication

password

The group's pasword

groups

A string of comma seperated groups the group should be in

runas

System user all operation should be preformed on behalf of

salt.states.rabbitmq_user

Manage RabbitMQ Users. rabbit_user: rabbitmq_user.present: - password: password - force: True

salt.states.rabbitmq_user.absent(name, runas=None)

Ensure the named user is absent

name

The name of the user to remove

runas

User to run the command

salt.states.rabbitmq_user.present(name, password=None, force=False, runas=None)

Ensure the RabbitMQ user exists.

name

User name

password

User's password, if one needs to be set

force

If user exists, forcibly change the password

runas

Name of the user to run the command

salt.states.rabbitmq_vhost

Manage RabbitMQ Virtual Hosts. virtual_host: rabbitmq_vhost.present: - user: rabbit_user - conf: .* - write: .* - read: .*

salt.states.rabbitmq_vhost.absent(name, runas=None)

Ensure the RabbitMQ Virtual Host is absent

name

Name of the Virtual Host to remove

runas

User to run the command

salt.states.rabbitmq_vhost.present(name, user=None, conf=None, write=None, read=None, runas=None)

Ensure the RabbitMQ VHost exists.

name

VHost name

user

Initial user permission to set on the VHost, if present

conf

Initial conf string to apply to the VHost and user. Defaults to .*

write

Initial write permissions to apply to the VHost and user. Defaults to .*

read

Initial read permissions to apply to the VHost and user. Defaults to .*

runas

Name of the user to run the command

salt.states.rvm

Managing Ruby installations and gemsets with Ruby Version Manager (RVM).

This module is used to install and manage ruby installations and gemsets with RVM, the Ruby Version Manager. Different versions of ruby can be installed and gemsets created. RVM itself will be installed automatically if it's not present. This module will not automatically install packages that RVM depends on or ones that are needed to build ruby. If you want to run RVM as an unprivileged user (recommended) you will have to create this user yourself. This is how a state configuration could look like: rvm: group: - present user.present: - gid: rvm - home: /home/rvm - require: - group: rvm rvm-deps: pkg.installed: - names: - bash - coreutils - gzip - bzip2 - gawk - sed - curl - git-core - subversion mri-deps: pkg.installed: - names: - build-essential - openssl - libreadline6 - libreadline6-dev - curl - git-core - zlib1g - zlib1g-dev - libssl-dev - libyaml-dev - libsqlite3-0 - libsqlite3-dev - sqlite3 - libxml2-dev - libxslt1-dev - autoconf - libc6-dev - libncurses5-dev - automake - libtool - bison - subversion - ruby jruby-deps: pkg.installed: - names: - curl - g++ - openjdk-6-jre-headless ruby-1.9.2: rvm.installed: - default: True - runas: rvm - require: - pkg: rvm-deps - pkg: mri-deps - user: rvm jruby: rvm.installed: - runas: rvm - require: - pkg: rvm-deps - pkg: jruby-deps - user: rvm jgemset: rvm.gemset_present: - ruby: jruby - runas: rvm - require: - rvm: jruby mygemset: rvm.gemset_present: - ruby: ruby-1.9.2 - runas: rvm - require: - rvm: ruby-1.9.2

salt.states.rvm.gemset_present(name, ruby='default', runas=None)

Verify that the gemset is present.

name

The name of the gemset.

ruby

default The ruby version this gemset belongs to.

runas

None The use user to run rvm as.

salt.states.rvm.installed(name, default=False, runas=None)

Verify that the specified ruby is installed with RVM. RVM is installed when necessary.

name

The version of ruby to install

default

False Whether to make this ruby the default.

runas

None The user to run rvm as.

salt.states.selinux

Management of SELinux rules.

If SELinux is available for the running system, the mode can be managed and booleans can be set. enforcing: selinux.mode samba_create_home_dirs: selinux.boolean: - value: True - persist: True

salt.states.selinux.boolean(name, value, persist=False)

Set up an SELinux boolean

name

The name of the boolean to set

value

The value to set on the boolean

persist

Defaults to False, set persist to true to make the boolean apply on a reboot

salt.states.selinux.mode(name): Verifies the mode SELinux is running in, can be set to enforcing or permissive; name
The mode to run SELinux in, permissive or enforcing

salt.states.service

Starting or restarting of services and daemons.

Services are defined as system daemons typically started with system init or rc scripts, services can be defined as running or dead. httpd: service: - running The service can also be set to be started at runtime via the enable option: openvpn: service: - running - enable: True By default if a service is triggered to refresh due to a watch statement the service is by default restarted. If the desired behaviour is to reload the service then set the reload value to True: redis: service: - running - enable: True - reload: True - watch: - pkg: redis

salt.states.service.dead(name, enable=None, sig=None, **kwargs)

Ensure that the named service is dead

name

The name of the init or rc script used to manage the service

enable

Set the service to be enabled at boot time, True sets the service to be enabled, False sets the named service to be disabled. The default is None, which does not enable or disable anything.

sig

The string to search for when looking for the service process with ps

salt.states.service.disabled(name, **kwargs)

Verify that the service is disabled on boot, only use this state if you don't want to manage the running process, remember that if you want to disable a service to use the enable: False option for the running or dead function.

name

The name of the init or rc script used to manage the service

salt.states.service.enabled(name, **kwargs)

Verify that the service is enabled on boot, only use this state if you don't want to manage the running process, remember that if you want to enable a running service to use the enable: True option for the running or dead function.

name

The name of the init or rc script used to manage the service

salt.states.service.mod_watch(name, sig=None, reload=False, full_restart=False)

The service watcher, called to invoke the watch command.

name

The name of the init or rc script used to manage the service

sig

The string to search for when looking for the service process with ps

salt.states.service.running(name, enable=None, sig=None, **kwargs)

Verify that the service is running

name

The name of the init or rc script used to manage the service

enable

Set the service to be enabled at boot time, True sets the service to be enabled, False sets the named service to be disabled. The default is None, which does not enable or disable anything.

sig

The string to search for when looking for the service process with ps

salt.states.ssh_auth

Control of entries in SSH authorized_key files.

The information stored in a user's ssh authorized key file can be easily controlled via the ssh_auth state. Defaults can be set by the enc, options, and comment keys. These defaults can be overridden by including them in the name. AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==: ssh_auth: - present - user: root - enc: ssh-dss thatch: ssh_auth: - present - user: root - source: salt://ssh_keys/thatch.id_rsa.pub sshkeys: ssh_auth: - present - user: root - enc: ssh-rsa - options: - option1="value1" - option2="value2 flag2" - comment: myuser - names: - AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY== - ssh-dss AAAAB3NzaCL0sQ9fJ5bYTEyY== user@domain - option3="value3" ssh-dss AAAAB3NzaC1kcQ9J5bYTEyY== other@testdomain - AAAAB3NzaC1kcQ9fJFF435bYTEyY== newcomment

salt.states.ssh_auth.absent(name, user, config='.ssh/authorized_keys')

Verifies that the specified ssh key is absent

name

The ssh key to manage

user

The user who owns the ssh authorized keys file to modify

config

The location of the authorized keys file relative to the user's home directory, defaults to ".ssh/authorized_keys"

salt.states.ssh_auth.present(name, user, enc='ssh-rsa', comment='', source='', options=None, config='.ssh/authorized_keys', **kwargs)

Verifies that the specified ssh key is present for the specified user

name

The ssh key to manage

user

The user who owns the ssh authorized keys file to modify

enc

Defines what type of key is being used, can be ecdsa ssh-rsa, ssh-dss

comment

The comment to be placed with the ssh public key

source

The source file for the key(s). Can contain any number of public keys, in standard "authorized_keys" format. If this is set, comment, enc, and options will be ignored.

options

The options passed to the key, pass a list object

config

The location of the authorized keys file relative to the user's home directory, defaults to ".ssh/authorized_keys"

salt.states.ssh_known_hosts

Control of SSH known_hosts entries.

Manage the information stored in the known_hosts files github.com: ssh_known_hosts: - present - user: root - fingerprint: 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 example.com: ssh_known_hosts: - absent - user: root

salt.states.ssh_known_hosts.absent(name, user, config='.ssh/known_hosts')

Verifies that the specified host is not known by the given user

name

The host name

user

The user who owns the ssh authorized keys file to modify

config

The location of the authorized keys file relative to the user's home directory, defaults to ".ssh/known_hosts"

salt.states.ssh_known_hosts.present(name, user, fingerprint=None, port=None, enc=None, config='.ssh/known_hosts', hash_hostname=True)

Verifies that the specified host is known by the specified user

On many systems, specifically those running with openssh 4 or older, the enc option must be set, only openssh 5 and above can detect the key type.

name

The name of the remote host (i.e. "github.com")

user

The user who owns the ssh authorized keys file to modify

enc

Defines what type of key is being used, can be ssh-rsa or ssh-dss

fingerprint

The fingerprint of the key which must be presented in the known_hosts file

port

optional parameter, denoting the port of the remote host, which will be used in case, if the public key will be requested from it. By default the port 22 is used.

config

The location of the authorized keys file relative to the user's home directory, defaults to ".ssh/known_hosts"

hash_hostname

True Hash all hostnames and addresses in the output.

salt.states.stateconf

Stateconf System

The stateconf system is intended for use only with the stateconf renderer. This State module presents the set function. This function does not execute any functionality, but is used to interact with the stateconf renderer.
salt.states.stateconf.context(name, **kws): No-op state to support state config via the stateconf renderer.
salt.states.stateconf.set(name, **kws): No-op state to support state config via the stateconf renderer.

salt.states.supervisord

Interaction with the Supervisor daemon.

wsgi_server: supervisord: - running - restart: False - require: - pkg: supervisor

salt.states.supervisord.dead(name, runas=None)

Ensure the named service is dead (not running).

name

Service name as defined in the supervisor configuration file

runas

Name of the user to run the supervisorctl command

salt.states.supervisord.running(name, restart=False, runas=None)

Ensure the named service is running.

name

Service name as defined in the supervisor configuration file

restart

Whether to force a restart e.g. when updating a service

runas

Name of the user to run the supervisorctl command

salt.states.svn

Manage SVN repositories

Manage repositiry checkouts via the svn vcs system: http://unladen-swallow.googlecode.com/svn/trunk/: svn.latest: - target: /tmp/swallow

salt.states.svn.dirty(name, target, user=None, ignore_unversioned=False)

Determine if the working directory has been changed.

salt.states.svn.latest(name, target=None, rev=None, user=None, username=None, force=False, externals=True)

Checkout or update the working directory to the latest revision from the remote repository.

name

Address of the name repository as passed to "svn checkout"

target

Name of the target directory where the checkout will put the working directory

rev

None The name revision number to checkout. Enable "force" if the directory already exists.

user

None Name of the user performing repository management operations

username

None The user to access the name repository with. The svn default is the current user

force

False Continue if conflicts are encountered

externals

True Change to False to not checkout or update externals

salt.states.sysctl

Configuration of the Linux kernel using sysctrl.

Control the kernel sysctl system vm.swappiness: sysctl.present: - value: 20

salt.states.sysctl.present(name, value, config='/etc/sysctl.conf')

Ensure that the named sysctl value is set

name

The name of the sysctl value to edit

value

The sysctl value to apply

config

The location of the sysctl configuration file

salt.states.timezone

Management of timezones

The timezone can be managed for the system: America/Denver: timezone.system: - utc: True

salt.states.timezone.system(name, utc='')

Set the timezone for the system.

name

The name of the timezone to use (e.g.: America/Denver)

utc

Whether or not to use UTC (default is True)

salt.states.user

Management of user accounts.

The user module is used to create and manage user settings, users can be set as either absent or present fred: user.present: - fullname: Fred Jones - shell: /bin/zsh - home: /home/fred - uid: 4000 - gid: 4000 - groups: - wheel - storage - games testuser: user.absent

salt.states.user.absent(name, purge=False, force=False)

Ensure that the named user is absent

name

The name of the user to remove

purge

Set purge to delete all of the user's file as well as the user

force

If the user is logged in the absent state will fail, set the force option to True to remove the user even if they are logged in

salt.states.user.present(name, uid=None, gid=None, gid_from_name=False, groups=None, optional_groups=None, home=True, password=None, enforce_password=True, shell=None, unique=True, system=False, fullname='', roomnumber='', workphone='', homephone='')

Ensure that the named user is present with the specified properties

name

The name of the user to manage

uid

The user id to assign, if left empty then the next available user id will be assigned

gid

The default group id

gid_from_name

If True, the default group id will be set to the id of the group with the same name as the user.

groups

A list of groups to assign the user to, pass a list object. If a group specified here does not exist on the minion, the state will fail. If set to the empty list, the user will be removed from all groups except the default group.

optional_groups

A list of groups to assign the user to, pass a list object. If a group specified here does not exist on the minion, the state will silently ignore it.

NOTE: If the same group is specified in both "groups" and "optional_groups", then it will be assumed to be required and not optional.

home

The location of the home directory to manage

password

A password hash to set for the user

enforce_password

Set to False to keep the password from being changed if it has already been set and the password hash differs from what is specified in the "password" field. This option will be ignored if "password" is not specified.

shell

The login shell, defaults to the system default shell

unique

Require a unique UID, True by default

system

Choose UID in the range of FIRST_SYSTEM_UID and LAST_SYSTEM_UID.

User comment field (GECOS) support (currently Linux and FreeBSD only):

The below values should be specified as strings to avoid ambiguities when the values are loaded. (Especially the phone and room number fields which are likely to contain numeric data)

fullname

The user's full name.

roomnumber

The user's room number

workphone

The user's work phone number

homephone

The user's home phone number

salt.states.virtualenv

Setup of Python virtualenv sandboxes.

salt.states.virtualenv.managed(name, venv_bin='virtualenv', requirements='', no_site_packages=False, system_site_packages=False, distribute=False, clear=False, python='', extra_search_dir='', never_download=False, prompt='', __env__='base', runas=None, cwd=None, index_url=None, extra_index_url=None): Create a virtualenv and optionally manage it with pip; name
Path to the virtualenv; requirements

Path to a pip requirements file. If the path begins with salt:// the file will be transfered from the master file server.

cwd

Path to the working directory where "pip install" is executed.

Also accepts any kwargs that the virtualenv module will.

/var/www/myvirtualenv.com:
  virtualenv.managed:
    - no_site_packages: True
    - requirements: salt://REQUIREMENTS.txt

Renderers

The Salt state system operates by gathering information from simple data structures. The state system was designed in this way to make interacting with it generic and simple. This also means that state files (SLS files) can be one of many formats.

By default SLS files are rendered as Jinja templates and then parsed as YAML documents. But since the only thing the state system cares about is raw data, the SLS files can be any structured format that can be dreamed up.

Currently there is support for Jinja + YAML, Mako + YAML, Wempy + YAML, Jinja + json Mako + json and Wempy + json. But renderers can be written to support anything. This means that the Salt states could be managed by xml files, html files, puppet files, or any format that can be translated into the data structure used by the state system.

Multiple Renderers

When deploying a state tree a default renderer is selected in the master configuration file with the renderer option. But multiple renderers can be used inside the same state tree. When rendering SLS files Salt checks for the presence of a Salt specific shebang line. The shebang line syntax was chosen because it is familiar to the target audience, the systems admin and systems engineer. The shebang line directly calls the name of the renderer as it is specified within Salt. One of the most common reasons to use multiple renderers in to use the Python or py renderer: #!py def run(): ''' Install the python-mako package ''' return {'include': ['python'], 'python-mako': {'pkg': ['installed']}} The first line is a shebang that references the py renderer.

Composing Renderers

A renderer can be composed from other renderers by connecting them in a series of pipes(|). In fact, the default Jinja + YAML renderer is implemented by combining a yaml renderer and a jinja renderer. Such renderer configuration is specified as: jinja | yaml.
Other renderer combinations are possible, here's a few examples:: yaml
i.e, just YAML, no templating.; mako | yaml; pass the input to the mako renderer, whose output is then fed into the yaml renderer.; jinja | mako | yaml; This one allows you to use both jinja and mako templating syntax in the input and then parse the final rendererd output as YAML.
And here's a contrived example sls file using the jinja | mako | yaml renderer:
#!jinja|mako|yaml An_Example: cmd.run: - name: | echo "Using Salt ${grains['saltversion']}" \ "from path {{"{{"}}grains['saltpath']}}." - cwd: / <%doc> ${...} is Mako's notation, and so is this comment. </%doc> {# Similarly, {{"{{"}}...}} is Jinja's notation, and so is this comment. #}
For backward compatibility, jinja | yaml can also be written as yaml_jinja, and similarly, the yaml_mako, yaml_wempy, json_jinja, json_mako, and json_wempy renderers are all supported as well.
Keep in mind that not all renderers can be used alone or with any other renderers. For example, the template renderers shouldn't be used alone as their outputs are just strings, which still need to be parsed by another renderer to turn them into highstate data structures. Also, for example, it doesn't make sense to specify yaml | jinja either, because the output of the yaml renderer is a highstate data structure(a dict in Python), which cannot be used as the input to a template renderer. Therefore, when combining renderers, you should know what each renderer accepts as input and what it returns as output.

Writing Renderers

Writing a renderer is easy, all that is required is that a Python module is placed in the rendered directory and that the module implements the render function. The render function will be passed the path of the SLS file. In the render function, parse the passed file and return the data structure derived from the file. You can place your custom renderers in a _renderers directory within the file_roots specified by the master config file. These custom renderers are distributed when state.highstate is run, or by executing the saltutil.sync_renderers or saltutil.sync_all functions.

Examples

The best place to find examples of renderers is in the Salt source code. The renderers included with Salt can be found here:
https://github.com/saltstack/salt/blob/develop/salt/renderers
Here is a simple YAML renderer example:
import yaml def render(yaml_data, env='', sls='', **kws): if not isinstance(yaml_data, basestring): yaml_data = yaml_data.read() data = yaml.load(yaml_data) return data if data else {}

Full List Of Builtin Renderer Modules

salt.renderers.jinja

Jinja in States

The most basic usage of Jinja in state files is using control structures to wrap conditional or redundant state elements:
{% if grains['os'] != 'FreeBSD' %} tcsh: pkg: - installed {% endif %} motd: file.managed: {% if grains['os'] == 'FreeBSD' %} - name: /etc/motd {% elif grains['os'] == 'Debian' %} - name: /etc/motd.tail {% endif %} - source: salt://motd
In this example, the first if block will only be evaluated on minions that aren't running FreeBSD, and the second block changes the file name based on the os grain.
Writing if-else blocks can lead to very redundant state files however. In this case, using pillars, or using a previously defined variable might be easier:
{% set motd = ['/etc/motd'] %} {% if grains['os'] == 'Debian' %} {% set motd = ['/etc/motd.tail', '/var/run/motd'] %} {% endif %} {% for motdfile in motd %} {{"{{"}} motdfile }}: file.managed: - source: salt://motd {% endfor %}
Using a variable set by the template, the for loop will iterate over the list of MOTD files to update, adding a state block for each file.

Passing Variables

It is also possible to pass additional variable context directly into a template, using the defaults and context mappings of the file.managed state:
/etc/motd: file.managed: - source: salt://motd - template: jinja - defaults: message: 'Foo' {% if grains['os'] == 'FreeBSD' %} - context: message: 'Bar' {% endif %}
The template will receive a variable message, which would be accessed in the template using {{"{{"}} message }}. If the operating system is FreeBSD, the value of the variable message would be Bar, otherwise it is the default Foo

Include and Import

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

Macros

Macros are helpful for eliminating redundant code, however stripping whitespace from the template block, as well as contained blocks, may be necessary to emulate a variable return from the macro. # init.sls {% from 'lib.sls' import pythonpkg with context %} python-virtualenv: pkg.installed: - name: {{"{{"}} pythonpkg('virtualenv') }} python-fabric: pkg.installed: - name: {{"{{"}} pythonpkg('fabric') }} # lib.sls {% macro pythonpkg(pkg) -%} {%- if grains['os'] == 'FreeBSD' -%} py27-{{"{{"}} pkg }} {%- elif grains['os'] == 'Debian' -%} python-{{"{{"}} pkg }} {%- endif -%} {%- endmacro %} This would define a macro that would return a string of the full package name, depending on the packaging system's naming convention. The whitespace of the macro was eliminated, so that the macro would return a string without line breaks, using whitespace control.

Jinja in Files

Jinja can be used in the same way in managed files: # redis.sls /etc/redis/redis.conf: file.managed: - source: salt://redis.conf - template: jinja - context: bind: 127.0.0.1 # lib.sls {% set port = 6379 %} # redis.conf {% from 'lib.sls' import port with context %} port {{"{{"}} port }} bind {{"{{"}} bind }} As an example, configuration was pulled from the file context and from an external template file.
salt.renderers.jinja.render(template_file, env='', sls='', argline='', context=None, tmplpath=None, **kws): Render the template_file, passing the functions and grains into the Jinja rendering system.; Return type

string

salt.renderers.json

salt.renderers.json.render(json_data, env='', sls='', **kws): Accepts JSON as a string or as a file object and runs it through the JSON parser.; Return type

A Python data structure

salt.renderers.mako

salt.renderers.mako.render(template_file, env='', sls='', context=None, tmplpath=None, **kws): Render the template_file, passing the functions and grains into the Mako rendering system.; Return type

string

salt.renderers.py

Pure python state renderer
The sls file should contain a function called run which returns high state data
salt.renderers.py.render(template, env='', sls='', tmplpath=None, **kws): Render the python module's components; Return type

string

salt.renderers.pydsl

maintainer: Jack Kuan <kjkuan@gmail.com>
maturity: new
platform: all
The pydsl renderer allows one to author salt formulas(.sls files) in pure Python using a DSL that's easy to write and easy to read. Here's an example:
#!pydsl apache = state('apache') apache.pkg.installed() apache.service.running() state('/var/www/index.html') \ .file('managed', source='salt://webserver/index.html') \ .require(pkg='apache')
Notice that any Python code is allow in the file as it's really a Python module, so you have the full power of Python at your disposal. In this module, a few objects are defined for you, including the usual(with __ added) __salt__ dictionary, __grains__, __pillar__, __opts__, __env__, and __sls__, plus a few more:: __file__; local file system path to the sls module.; __pydsl__; Salt PyDSL object, useful for configuring DSL behavior per sls rendering.; include; Salt PyDSL function for creating include declaration's.; extend; Salt PyDSL function for creating extend declaration's.; state; Salt PyDSL function for creating ID declaration's.
A state ID declaration is created with a state(id) function call. Subsequent state(id) call with the same id returns the same object. This singleton access pattern applys to all declaration objects created with the DSL.
state('example') assert state('example') is state('example') assert state('example').cmd is state('example').cmd assert state('example').cmd.running is state('example').cmd.running
The id argument is optional. If ommitted, an UUID will be generated and used as the id.
state(id) returns an object under which you can create a state declaration object by accessing an attribute named after any state module available in Salt.
state('example').cmd state('example').file state('example').pkg ...
Then, a function declaration object can be created from a state declaration object by one of the following two ways:
1. by directly calling the attribute named for the state declaration, and supplying the state function name as the first argument.
state('example').file('managed', ...)
2. by calling a method named after the state function on the state declaration object.
state('example').file.managed(...)
With either way of creating a function declaration object, any function arg declaration's can be passed as keyword arguments to the call. Subsequent calls of a function declaration will update the arg declarations.
state('example').file('managed', source='salt://webserver/index.html') state('example').file.managed(source='salt://webserver/index.html')
As a shortcut, the special name argument can also be passed as the first(second if calling using the first way) positional argument.
state('example').cmd('run', 'ls -la', cwd='/') state('example').cmd.run('ls -la', cwd='/')
Finally, a requisite declaration object with its requisite reference's can be created by invoking one of the requisite methods(require, watch, use, require_in, watch_in, and use_in) on either a function declaration object or a state declaration object. The return value of a requisite call is also a function declaration object, so you can chain several requisite calls together.
Arguments to a requisite call can be a list of state declaration objects and/or a set of keyword arguments whose names are state modules and values are IDs of ID declaration's or names of name declaration's.
apache2 = state('apache2') apache2.pkg.installed() state('libapache2-mod-wsgi').pkg.installed() # you can call requisites on function declaration apache2.service.running() \ .require(apache2.pkg, pkg='libapache2-mod-wsgi') \ .watch(file='/etc/apache2/httpd.conf') # or you can call requisites on state declaration. # this actually creates an anonymous function declaration object # to add the requisites. apache2.service.require(state('libapache2-mod-wsgi').pkg, pkg='apache2') \ .watch(file='/etc/apache2/httpd.conf') # we still need to set the name of the function declaration. apache2.service.running()
include declaration objects can be created with the include function, while extend declaration objects can be created with the extend function, whose arguments are just function declaration objects.
include('edit.vim', 'http.server') extend(state('apache2').service.watch(file='/etc/httpd/httpd.conf')
The include function, by default, causes the included sls file to be rendered as soon as the include function is called. It returns a list of rendered module objects; sls files not rendered with the pydsl renderer return None's. This behavior creates no include declaration's in the resulting high state data structure.
import types # including multiple sls returns a list. _, mod = include('a-non-pydsl-sls', 'a-pydsl-sls') assert _ is None assert isinstance(slsmods[1], types.ModuleType) # including a single sls returns a single object mod = include('a-pydsl-sls') # myfunc is a function that calls state(...) to create more states. mod.myfunc(1, 2, "three")
Notice how you can define a reusable function in your pydsl sls module and then call it via the module returned by include.
It's still possible to do late includes by passing the delayed=True keyword argument to include.
include('edit.vim', 'http.server', delayed=True)
Above will just create a include declaration in the rendered result, and such call always returns None.

Special integration with the cmd state

Taking advantage of rendering a Python module, PyDSL allows you to declare a state that calls a pre-defined Python function when the state is executed.
greeting = "hello world" def helper(something, *args, **kws): print greeting # hello world print something, args, kws # test123 ['a', 'b', 'c'] {'x': 1, 'y': 2} state().cmd.call(helper, "test123", 'a', 'b', 'c', x=1, y=2)
The cmd.call state function takes care of calling our helper function with the arguments we specified in the states, and translates the return value of our function into a structure expected by the state system. See salt.states.cmd.call() for more information.

Implicit ordering of states

Salt states are explicitly ordered via requisite declaration's. However, with pydsl it's possible to let the renderer track the order of creation for function declaration objects, and implicitly add require requisites for your states to enforce the ordering. This feature is enabled by setting the ordered option on __pydsl__.
Note this feature is only available if your minions are using Python >= 2.7.
include('some.sls.file') A = state('A').cmd.run(cwd='/var/tmp') extend(A) __pydsl__.set(ordered=True) for i in range(10): i = str(i) state(i).cmd.run('echo '+i, cwd='/') state('1').cmd.run('echo one') state('2').cmd.run(name='echo two')
Notice that the ordered option needs to be set after any extend calls. This is to prevent pydsl from tracking the creation of a state function that's passed to an extend call.
Above example should create states from 0 to 9 that will output 0, one, two, 3, ... 9, in that order.
It's important to know that pydsl tracks the creations of function declaration objects, and automatically adds a require requisite to a function declaration object that requires the last function declaration object created before it in the sls file.
This means later calls(perhaps to update the function's function arg declaration) to a previously created function declaration will not change the order.

Render time state execution

When Salt processes a salt formula file(.sls), the file is rendered to salt's high state data representation by a renderer before the states can be executed. In the case of the pydsl renderer, the .sls file is executed as a python module as it is being rendered which makes it easy to execute a state at render time. In pydsl, executing one or more states at render time can be done by calling a configured ID declaration object. #!pydsl s = state() # save for later invocation # configure it s.cmd.run('echo at render time', cwd='/') s.file.managed('target.txt', source='salt://source.txt') s() # execute the two states now Once an ID declaration is called at render time it is detached from the sls module as if it was never defined.: Note
If implicit ordering is enabled(ie, via __pydsl__.set(ordered=True)) then the first invocation of a ID declaration object must be done before a new function declaration is created.

Integration with the stateconf renderer

The salt.renderers.stateconf renderer offers a few interesting features that can be leveraged by the pydsl renderer. In particular, when using with the pydsl renderer, we are interested in stateconf's sls namespacing feature(via dot-prefixed id declarations), as well as, the automatic start and goal states generation.
Now you can use pydsl with stateconf like this:
#!pydsl|stateconf -ps include('xxx', 'yyy') # ensure that states in xxx run BEFORE states in this file. extend(state('.start').stateconf.require(stateconf='xxx::goal')) # ensure that states in yyy run AFTER states in this file. extend(state('.goal').stateconf.require_in(stateconf='yyy::start')) __pydsl__.set(ordered=True) ...
-s enables the generation of a stateconf start state, and -p lets us pipe high state data rendered by pydsl to stateconf. This example shows that by require-ing or require_in-ing the included sls' start or goal states, it's possible to ensure that the included sls files can be made to execute before or after a state in the including sls file.
salt.renderers.pydsl.render(template, env='', sls='', tmplpath=None, rendered_sls=None, **kws)

salt.renderers.stateconf

maintainer

Jack Kuan <kjkuan@gmail.com>

maturity

new

platform

all

This module provides a custom renderer that process a salt file with a specified templating engine(eg, jinja) and a chosen data renderer(eg, yaml), extract arguments for any stateconf.set state and provide the extracted arguments (including salt specific args, such as 'require', etc) as template context. The goal is to make writing reusable/configurable/ parameterized salt files easier and cleaner.
To use this renderer, either set it as the default renderer via the renderer option in master/minion's config, or use the shebang line in each individual sls file, like so: #!stateconf. Note, due to the way this renderer works, it must be specified as the first renderer in a render pipeline. That is, you cannot specify #!mako|yaml|stateconf, for example. Instead, you specify them as renderer arguments: #!stateconf mako . yaml.
Here's a list of features enabled by this renderer:

• Recognizes the special state function, stateconf.set, that configures a default list of named arguments useable within the template context of the salt file. Example:

sls_params:
  stateconf.set:
    - name1: value1
    - name2: value2
    - name3:
      - value1
      - value2
      - value3
    - require_in:
      - cmd: output

# --- end of state config ---

output:
  cmd.run:
    - name: |
        echo 'name1={{"{{"}}sls_params.name1}}
              name2={{"{{"}}sls_params.name2}}
              name3[1]={{"{{"}}sls_params.name3[1]}}
        '

This even works with include + extend so that you can override the default configured arguments by including the salt file and then extend the stateconf.set states that come from the included salt file.

Notice that the end of configuration marker(# --- end of state config --) is needed to separate the use of 'stateconf.set' form the rest of your salt file. The regex that matches such marker can be configured via the stateconf_end_marker option in your master or minion config file.

Sometimes, you'd like to set a default argument value that's based on earlier arguments in the same stateconf.set. For example, you may be tempted to do something like this:

apache:
  stateconf.set:
    - host: localhost
    - port: 1234
    - url: 'http://{{"{{"}}host}}:{{"{{"}}port}}/'

# --- end of state config ---

test:
  cmd.run:
    - name: echo '{{"{{"}}apache.url}}'
    - cwd: /

However, this won't work, but can be worked around like so:

apache:
  stateconf.set:
    - host: localhost
    - port: 1234
{#  - url: 'http://{{"{{"}}host}}:{{"{{"}}port}}/' #}

# --- end of state config ---
# {{"{{"}} apache.setdefault('url', "http://%(host)s:%(port)s/" % apache) }}

test:
  cmd.run:
    - name: echo '{{"{{"}}apache.url}}'
    - cwd: /

• Adds support for relative include and exclude of .sls files. Example:

include:
  - .apache
  - .db.mysql

exclude:
  - sls: .users

If the above is written in a salt file at salt://some/where.sls then it will include salt://some/apache.sls and salt://some/db/mysql.sls, and exclude salt://some/users.ssl. Actually, it does that by rewriting the above include and exclude into:

include:
  - some.apache
  - some.db.mysql

exclude:
  - sls: some.users

• Adds a sls_dir context variable that expands to the directory containing the rendering salt file. So, you can write salt://${sls_dir}/... to reference templates files used by your salt file.

• Prefixes any state id(declaration or reference) that starts with a dot(.) to avoid duplicated state ids when the salt file is included by other salt files.

For example, in the salt://some/file.sls, a state id such as .sls_params will be turned into some.file::sls_params. Example:

.vim:
  package.installed

Above will be translated into:

some.file::vim:
  package.installed:
    - name: vim

Notice how that if a state under a dot-prefixed state id has no name argument then one will be added automatically by using the state id with the leading dot stripped off.

The leading dot trick can be used with extending state ids as well, so you can include relatively and extend relatively. For example, when extending a state in salt://some/other_file.sls, eg,:

include:
  - .file

extend:
  .file::sls_params:
    stateconf.set:
      - name1: something

Above will be pre-processed into:

include:
  - some.file

extend:
  some.file::sls_params:
    stateconf.set:
      - name1: something

• Optionally(enabled by default, disable via the -G renderer option, eg, in the shebang line: #!stateconf -G), generates a stateconf.set goal state(state id named as .goal by default, configurable via the master/minion config option, stateconf_goal_state) that requires all other states in the salt file. Note, the .goal state id is subject to dot-prefix rename rule mentioned earlier.

Such goal state is intended to be required by some state in an including salt file. For example, in your webapp salt file, if you include a sls file that is supposed to setup Tomcat, you might want to make sure that all states in the Tomcat sls file will be executed before some state in the webapp sls file.

• Optionally(enable via the -o renderer option, eg, in the shebang line: #!stateconf -o), orders the states in a sls file by adding a require requisite to each state such that every state requires the state defined just before it. The order of the states here is the order they are defined in the sls file.(Note: this feature is only available if your minions are using Python >= 2.7. For Python2.6, it should also work if you install the ordereddict module from PyPI)

By enabling this feature, you are basically agreeing to author your sls files in a way that gives up the explicit(or implicit?) ordering imposed by the use of require, watch, require_in or watch_in requisites, and instead, you rely on the order of states you define in the sls files. This may or may not be a better way for you. However, if there are many states defined in a sls file, then it tends to be easier to see the order they will be executed with this feature.

You are still allowed to use all the requisites, with a few restricitons. You cannot require or watch a state defined after the current state. Similarly, in a state, you cannot require_in or watch_in a state defined before it. Breaking any of the two restrictions above will result in a state loop. The renderer will check for such incorrect uses if this feature is enabled.

Additionally, names declarations cannot be used with this feature because the way they are compiled into low states make it impossible to guarantee the order in which they will be executed. This is also checked by the renderer. As a workaround for not being able to use names, you can achieve the same effect, by generate your states with the template engine available within your sls file.

Finally, with the use of this feature, it becomes possible to easily make an included sls file execute all its states after some state(say, with id X) in the including sls file. All you have to do is to make state, X, require_in the first state defined in the included sls file.

When writing sls files with this renderer, you should avoid using what can be defined in a name argument of a state as the state's id. That is, avoid writing your states like this:
/path/to/some/file: file.managed: - source: salt://some/file cp /path/to/some/file file2: cmd.run: - cwd: / - require: - file: /path/to/some/file
Instead, you should define the state id and the name argument separately for each state, and the id should be something meaningful and easy to reference within a requisite(which I think is a good habit anyway, and such extra indirection would also makes your sls file easier to modify later). Thus, the above states should be written like this:
add-some-file: file.managed: - name: /path/to/some/file - source: salt://some/file copy-files: cmd.run: - name: cp /path/to/some/file file2 - cwd: / - require: - file: add-some-file
Moreover, when referencing a state from a requisite, you should reference the state's id plus the state name rather than the state name plus its name argument. (Yes, in the above example, you can actually require the file: /path/to/some/file, instead of the file: add-some-file). The reason is that this renderer will re-write or rename state id's and their references for state id's prefixed with .. So, if you reference name then there's no way to reliably rewrite such reference.

salt.renderers.wempy

salt.renderers.wempy.render(template_file, env='', sls='', argline='', context=None, **kws): Render the data passing the functions and grains into the rendering system; Return type

string

salt.renderers.yaml

salt.renderers.yaml.get_yaml_loader(argline)
salt.renderers.yaml.render(yaml_data, env='', sls='', argline='', **kws): Accepts YAML as a string or as a file object and runs it through the YAML parser.; Return type

A Python data structure

Pillars

Salt includes a number of built-in external pillars, listed at all-salt.pillars.

You may also wish to look at the standard pillar documentation, at pillar-configuration

The source for the built-in Salt pillars can be found here: https://github.com/saltstack/salt/blob/develop/salt/pillar

Full List Of Builtin Pillar Modules

salt.pillar.cmd_json

Execute a command and read the output as JSON. The JSON data is then directly overlaid onto the minion's pillar data
salt.pillar.cmd_json.ext_pillar(pillar, command): Execute a command and read the output as JSON

salt.pillar.cmd_yaml

Execute a command and read the output as YAML. The YAML data is then directly overlaid onto the minion's pillar data
salt.pillar.cmd_yaml.ext_pillar(pillar, command): Execute a command and read the output as YAML

salt.pillar.hiera

Take in a hiera configuration file location and execute it. Adds the hiera data to pillar
salt.pillar.hiera.ext_pillar(pillar, conf): Execute hiera and return the data

salt.pillar.mongo

Read pillar data from a mongodb collection. This module will load a node-specific pillar dictionary from a mongo collection. It uses the node's id for lookups and can load either the whole document, or just a specific field from that document as the pillar dictionary.

Salt Master Mongo Configuration

The module shares the same base mongo connection variables as salt.returners.mongo_return. These variables go in your master config file.

• mongo.db - The mongo database to connect to. Defaults to 'salt'.

• mongo.host - The mongo host to connect to. Supports replica sets by specifying all hosts in the set, comma-delimited. Defaults to 'salt'.

• mongo.port - The port that the mongo database is running on. Defaults to 27017.

• mongo.user - The username for connecting to mongo. Only required if you are using mongo authentication. Defaults to ''.

• mongo.password - The password for connecting to mongo. Only required if you are using mongo authentication. Defaults to ''.

Configuring the Mongo ext_pillar

The Mongo ext_pillar takes advantage of the fact that the Salt Master configuration file is yaml. It uses a sub-dictionary of values to adjust specific features of the pillar. This is the explicit single-line dictionary notation for yaml. One may be able to get the easier-to-read multine dict to work correctly with some experimentation.
ext_pillar: - mongo: {collection: vm, id_field: name, re_pattern: \.example\.com, fields: [customer_id, software, apache_vhosts]}
In the example above, we've decided to use the vm collection in the database to store the data. Minion ids are stored in the name field on documents in that collection. And, since minon ids are FQDNs in most cases, we'll need to trim the domain name in order to find the minon by hostname in the collection. When we find a minion, return only the customer_id, software, and apache_vhosts fields, as that will contain the data we want for a given node. They will be available directly inside the pillar dict in your SLS templates.

Module Documentation

salt.pillar.mongo.ext_pillar(pillar, collection='pillar', id_field='_id', re_pattern=None, re_replace='', fields=None): Connect to a mongo database and read per-node pillar information.; Parameters:

• collection: The mongodb collection to read data from. Defaults to 'pillar'.

• id_field: The field in the collection that represents an individual minon id. Defaults to '_id'.

• re_pattern: If your naming convention in the collection is shorter than the minion id, you can use this to trim the name. re_pattern will be used to match the name, and re_replace will be used to replace it. Backrefs are supported as they are in the Python standard library. If None, no mangling of the name will be performed - the collection will be searched with the entire minion id. Defaults to None.

• re_replace: Use as the replacement value in node ids matched with re_pattern. Defaults to ''. Feel free to use backreferences here.

• fields: The specific fields in the document to use for the pillar data. If None, will use the entire document. If using the entire document, the _id field will be converted to string. Be careful with other fields in the document as they must be string serializable. Defaults to None.

salt.pillar.pillar_ldap

This pillar module parses a config file (specified in the salt master config), and executes a series of LDAP searches based on that config. Data returned by these searches is aggregrated, with data items found later in the LDAP search order overriding data found earlier on. The final result set is merged with the pillar data.
salt.pillar.pillar_ldap.ext_pillar(pillar, config_file): Execute LDAP searches and return the aggregated data

salt.pillar.puppet

Execute a puppet_node_classifier command and read the output as YAML. The YAML data is then directly overlaid onto the minion's pillar data
salt.pillar.puppet.ext_pillar(pillar, command): Execute a puppet_node_classifier command and read the output as YAML

Master Tops

Salt includes a number of built-in subsystems to generate top file data, they are listed listed at all-salt.tops.

The source for the built-in Salt master tops can be found here: https://github.com/saltstack/salt/blob/develop/salt/tops

Full List Of Builtin Master Tops Modules

salt.tops.ext_nodes

External Nodes Classifier

The External Nodes Classifier is a master tops subsystem used to hook into systems used to provide mapping information used by major configuration management systems. One of the most common external nodes classification system is provided by Cobbler and is called cobbler-ext-nodes.
The cobbler-ext-nodes command can be used with this configuration:
master_tops: ext_nodes: cobbler-ext-nodes
It is noteworthy that the Salt system does not directly ingest the data sent from the cobbler-ext-nodes command, but converts the data into information that is used by a Salt top file.
salt.tops.ext_nodes.top(**kwargs): Run the command configured

Salt Runners

Full List Of Runner Modules

salt.runners.cache

Return cached data from minions
salt.runners.cache.grains(minion=None): Return cached grains for all minions or a specific minion
salt.runners.cache.pillar(minion=None): Return cached grains for all minions or a specific minion

salt.runners.jobs

A convenience system to manage jobs, both active and already run
salt.runners.jobs.active(): Return a report on all actively running jobs from a job id centric perspective
salt.runners.jobs.list_jobs(): List all detectable jobs and associated functions
salt.runners.jobs.lookup_jid(jid, ext_source=None): Return the printout from a previously executed job
salt.runners.jobs.print_job(job_id): Print job available details, including return data.

salt.runners.launchd

salt.runners.launchd.write_launchd_plist(program): Write a launchd plist for managing salt-master or salt-minion

salt.runners.manage

General management functions for salt, tools like seeing what hosts are up and what hosts are down
salt.runners.manage.down(): Print a list of all the down or unresponsive salt minions
salt.runners.manage.status(output=True): Print the status of all known salt minions
salt.runners.manage.up(): Print a list of all of the minions that are up
salt.runners.manage.versions(): Check the version of active minions

salt.runners.network

Network tools to run from the Master

salt.runners.network.wol(mac, bcast='255.255.255.255', destport=9)

Send a "Magic Packet" to wake up a Minion

CLI Example:

salt-run network.wol 08-00-27-13-69-77
salt-run network.wol 080027136977 255.255.255.255 7
salt-run network.wol 08:00:27:13:69:77 255.255.255.255 7

salt.runners.network.wollist(maclist, bcast='255.255.255.255', destport=9)

Send a "Magic Packet" to wake up a list of Minions. This list must contain one MAC hardware address per line

CLI Example:

salt-run network.wollist '/path/to/maclist'
salt-run network.wollist '/path/to/maclist' 255.255.255.255 7
salt-run network.wollist '/path/to/maclist' 255.255.255.255 7

salt.runners.search

Runner frontend to search system
salt.runners.search.query(term): Query the search system

salt.runners.state

Execute overstate functions
salt.runners.state.over(env='base', os_fn=None): Execute an overstate sequence to orchestrate the executing of states over a group of systems
salt.runners.state.show_stages(env='base', os_fn=None): Display the stage data to be executed

salt.runners.sysmod

A Salt runner module to mirror and aggregate the Salt execution module of the same name
salt.runners.sysmod.doc(): Collect all the sys.doc output from each minion and return the aggregate

salt.runners.winrepo

Runner to manage Windows software repo
salt.runners.winrepo.genrepo(): Generate win_repo_cachefile based on sls files in the win_repo
salt.runners.winrepo.update_git_repos(): Checkout git repos containing Windows Software Package Definitions

Full List Of Builtin Wheel Modules

salt.wheel.config

Manage the master configuration file
salt.wheel.config.apply(key, value): Set a single key
Note This will strip comments from your config file
salt.wheel.config.values(): Return the raw values of the config file

salt.wheel.file_roots

Read in files from the file_root and save files to the file root
salt.wheel.file_roots.find(path, env='base'): Return a dict of the files located with the given path and environment
salt.wheel.file_roots.list_env(env='base'): Return all of the file paths found in an environment
salt.wheel.file_roots.list_roots(): Return all of the files names in all available environments
salt.wheel.file_roots.read(path, env='base'): Read the contents of a text file, if the file is binary then
salt.wheel.file_roots.write(data, path, env='base', index=0): Write the named file, by default the first file found is written, but the index of the file can be specified to write to a lower priority file root

salt.wheel.key

Wheel system wrapper for key system
salt.wheel.key.accept(match): Accept keys based on a glob match
salt.wheel.key.delete(match): Delete keys based on a glob match
salt.wheel.key.finger(match): Return the matching key fingerprints
salt.wheel.key.key_str(match): Return the key strings
salt.wheel.key.list_all(): List the keys under a named status
salt.wheel.key.reject(match): Delete keys based on a glob match

salt.wheel.pillar_roots

The pillar_roots wheel module is used to manage files under the pillar roots directories on the master server.
salt.wheel.pillar_roots.find(path, env='base'): Return a dict of the files located with the given path and environment
salt.wheel.pillar_roots.list_env(env='base'): Return all of the file paths found in an environment
salt.wheel.pillar_roots.list_roots(): Return all of the files names in all available environments
salt.wheel.pillar_roots.read(path, env='base'): Read the contents of a text file, if the file is binary then
salt.wheel.pillar_roots.write(data, path, env='base', index=0): Write the named file, by default the first file found is written, but the index of the file can be specified to write to a lower priority file root

Full List Of Builtin Output Modules

salt.output.grains

Special outputter for grains
salt.output.grains.output(grains): Output the grains in a clean way

salt.output.highstate

The return data from the Highstate command is a standard data structure which is parsed by the highstate outputter to deliver a clean and readable set of information about the HighState run on minions.
Two configurations can be set to modify the highstate outputter. These values can be set in the master config to change the output of the salt command or set in the minion config to change the output of the salt-call command.
state_verbose:: By default state_verbose is set to True, setting this to False will instruct the highstate outputter to omit displaying anything in green, this means that nothing with a result of True and no changes will not be printed
state_output:: The highstate outputter has two output modes, full and terse. The default is set to full, which will display many lines of detailed information for each executed chunk. If the state_output option is set to terse then the output is greatly simplified and shown in only one line
salt.output.highstate.output(data): The HighState Outputter is only meant to be used with the state.highstate function, or a function that returns highstate return data.

salt.output.json_out

The JSON output module converts the return data into JSON.
salt.output.json_out.output(data): Print the output data in JSON

salt.output.key

Salt Key makes use of the outputter system to format information sent to the salt-key command. This outputter is geared towards ingesting very specific data and should only be used with the salt-key command.
salt.output.key.output(data): Read in the dict structure generated by the salt key api methods and print the structure.

salt.output.nested

Recursively display nested data, this is the default outputter.
class salt.output.nested.NestDisplay: display(ret, indent, prefix, out)

Recursively interate down through data structures to determine output

salt.output.nested.output(ret): Display ret data

salt.output.overstatestage

Display clean output of an overstate stage
salt.output.overstatestage.output(data): Format the data for printing stage information from the overstate system

salt.output.pprint_out

The python pretty print system was the default outputter. This outputter simply passed the data passed into it through the pprint module.
salt.output.pprint_out.output(data): Print out via pretty print

salt.output.raw

The raw outputter outputs the data via the python print function and is shown in a raw state. This was the original outputter used by Salt before the outputter system was developed.
salt.output.raw.output(data): Rather basic....

salt.output.txt

The txt outputter has been developed to make the output from shell commands on minions appear as they do when the command is executed on the minion.
salt.output.txt.output(data): Output the data in lines, very nice for running commands

salt.output.yaml_out

Output data in YAML, this outputter defaults to printing in YAML block mode for better readability.
salt.output.yaml_out.output(data): Print out YAML using the block mode

Salt Client Api Interfaces

class salt.client.LocalClient(c_path='/etc/salt/master', mopts=None)

Connect to the salt master via the local server and via root

cmd(tgt, fun, arg=(), timeout=None, expr_form='glob', ret='', kwarg=None, **kwargs)

Execute a salt command and return.

class salt.runner.RunnerClient(opts): A client for accessing runners; low(fun, low)

Pass in the runner function name and the low data structure

class salt.wheel.Wheel(opts): Manage calls to the salt wheel system; master_call(fun, **kwargs)

Send a function call to a wheel module through the master network interface

Peer Communication

Salt 0.9.0 introduced the capability for Salt minions to publish commands. The intent of this feature is not for Salt minions to act as independent brokers one with another, but to allow Salt minions to pass commands to each other.

In Salt 0.10.0 the ability to execute runners from the master was added. This allows for the master to return collective data from runners back to the minions via the peer interface.

The peer interface is configured through two options in the master configuration file. For minions to send commands from the master the peer configuration is used. To allow for minions to execute runners from the master the peer_run configuration is used.

Since this presents a viable security risk by allowing minions access to the master publisher the capability is turned off by default. The minions can be allowed access to the master publisher on a per minion basis based on regular expressions. Minions with specific ids can be allowed access to certain Salt modules and functions.

Peer Configuration

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

Peer Runner Communication

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

Using Peer Communication

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

Client Acl System

The salt client acl system is a means to allow system users other than root to have access to execute select salt commands on minions from the master.

The client acl system is configured in the master configuration file via the client_acl configuration option. Under the client_acl configuration option the users open to send commands are specified and then a list of regular expressions which specify the minion functions which will be made available to specified user. This configuration is much like the peer configuration:

# Allow thatch to execute anything and allow fred to use ping and pkg
client_acl:
  thatch:
    - .*
  fred:
    - ping.*
    - pkg.*

Permission Issues

Directories required for client_acl must be modified to be readable by the users specified:
chmod 755 /var/cache/salt /var/cache/salt/jobs /var/run/salt
If you are upgrading from earlier versions of salt you must also remove any existing user keys and re-start the Salt master:
rm /var/cache/salt/.*key service salt-master restart

Salt Syndic

The Salt Syndic interface is a powerful tool which allows for the construction of Salt command topologies. A basic Salt setup has a Salt Master commanding a group of Salt Minions. The Syndic interface is a special passthrough minion, it is run on a master and connects to another master, then the master that the Syndic minion is listening to can control the minions attached to the master running the syndic.

The intent for supporting many layouts is not presented with the intent of supposing the use of any single topology, but to allow a more flexible method of controlling many systems.

Configuring the Syndic

Since the Syndic only needs to be attached to a higher level master the configuration is very simple. On a master that is running a syndic to connect to a higher level master the syndic_master option needs to be set in the master config file. The syndic_master option contains the hostname or ip address of the master server that can control the master that the syndic is running on. The master that the syndic connects to sees the syndic as an ordinary minion, and treats it as such. the higher level master will need to accept the syndic's minion key like any other minion. This master will also need to set the order_masters value in the configuration to True. The order_masters option in the config on the higher level master is very important, to control a syndic extra information needs to be sent with the publications, the order_masters option makes sure that the extra data is sent out.

Running the Syndic

The Syndic is a separate daemon that needs to be started on the master that is controlled by a higher master. Starting the Syndic daemon is the same as starting the other Salt daemons. # salt-syndic

Python Client Api

Salt is written to be completely API centric, Salt minions and master can be built directly into third party applications as a communication layer. The Salt client API is very straightforward.

A number of client command methods are available depending on the exact behaviour desired.

Using the LocalClient API

Sending information through the client is simple:
# Import the Salt client library import salt.client # create a local client object client = salt.client.LocalClient() # make calls with the cmd method ret = client.cmd('*', 'cmd.run', ['ls -l'])
The LocalClient object only works running as root on the salt-master, it is the same interface used by the salt command line tool.
LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form='glob', ret=''): The cmd method will execute and wait for the timeout period for all minions to reply, then it will return all minion data at once.
tgt
The tgt option is the target specification, by default a target is passed in as a bash shell glob. The expr_form option allows the tgt to be passed as either a pcre regular expression or as a Python list.
fun
The name of the function to call on the specified minions. The documentation for these functions can be seen by running on the salt-master: salt '*' sys.doc
arg
The optional arg parameter is used to pass a list of options on to the remote function
timeout: The number of seconds to wait after the last minion returns but before all minions return.
expr_form: The type of tgt that is passed in, the allowed values are:
• 'glob' - Bash glob completion - Default
• 'pcre' - Perl style regular expression
• 'list' - Python list of hosts
• 'grain' - Match based on a grain comparison
• 'grain_pcre' - Grain comparison with a regex
• 'pillar' - Pillar data comparison
• 'nodegroup' - Match on nodegroup
• 'range' - Use a Range server for matching
• 'compound' - Pass a compound match string
ret
Specify the returner to use. The value passed can be
single returner, or a comma delimited list of returners to call in order on the minions
LocalClient.cmd_cli(tgt, fun, arg=[], timeout=5, verbose=False, expr_form='glob', ret=''): The cmd_cli method is used by the salt command, it is a generator. This method returns minion returns as the come back and attempts to block until all minions return.
tgt
The tgt option is the target specification, by default a target is passed in as a bash shell glob. The expr_form option allows the tgt to be passed as either a pcre regular expression or as a Python list.
fun
The name of the function to call on the specified minions. The documentation for these functions can be seen by running on the salt-master: salt '*' sys.doc
arg
The optional arg parameter is used to pass a list of options on to the remote function
timeout: The number of seconds to wait after the last minion returns but before all minions return.
expr_form: The type of tgt that is passed in, the allowed values are:
• 'glob' - Bash glob completion - Default
• 'pcre' - Perl style regular expression
• 'list' - Python list of hosts
• 'grain' - Match based on a grain comparison
• 'grain_pcre' - Grain comparison with a regex
• 'pillar' - Pillar data comparison
• 'nodegroup' - Match on nodegroup
• 'range' - Use a Range server for matching
• 'compound' - Pass a compound match string
ret
Specify the returner to use. The value passed can be
single returner, or a comma delimited list of returners to call in order on the minions
verbose: Print extra information about the running command to the terminal
LocalClient.cmd_iter(tgt, fun, arg=[], timeout=5, expr_form='glob', ret=''): The cmd_iter method is a generator which yields the individual minion returns as the come in.
tgt
The tgt option is the target specification, by default a target is passed in as a bash shell glob. The expr_form option allows the tgt to be passed as either a pcre regular expression or as a Python list.
fun
The name of the function to call on the specified minions. The documentation for these functions can be seen by running on the salt-master: salt '*' sys.doc
arg
The optional arg parameter is used to pass a list of options on to the remote function
timeout: The number of seconds to wait after the last minion returns but before all minions return.
expr_form: The type of tgt that is passed in, the allowed values are:
• 'glob' - Bash glob completion - Default
• 'pcre' - Perl style regular expression
• 'list' - Python list of hosts
• 'grain' - Match based on a grain comparison
• 'grain_pcre' - Grain comparison with a regex
• 'pillar' - Pillar data comparison
• 'nodegroup' - Match on nodegroup
• 'range' - Use a Range server for matching
• 'compound' - Pass a compound match string
ret
Specify the returner to use. The value passed can be
single returner, or a comma delimited list of returners to call in order on the minions
LocalClient.cmd_iter_no_block(tgt, fun, arg=[], timeout=5, expr_form='glob', ret=''): The cmd_iter method will block waiting for individual minions to return, the cmd_iter_no_block method will return None until the next minion returns. This allows for actions to be injected in between minion returns
tgt
The tgt option is the target specification, by default a target is passed in as a bash shell glob. The expr_form option allows the tgt to be passed as either a pcre regular expression or as a Python list.
fun
The name of the function to call on the specified minions. The documentation for these functions can be seen by running on the salt-master: salt '*' sys.doc
arg
The optional arg parameter is used to pass a list of options on to the remote function
timeout: The number of seconds to wait after the last minion returns but before all minions return.
expr_form: The type of tgt that is passed in, the allowed values are:
• 'glob' - Bash glob completion - Default
• 'pcre' - Perl style regular expression
• 'list' - Python list of hosts
• 'grain' - Match based on a grain comparison
• 'grain_pcre' - Grain comparison with a regex
• 'pillar' - Pillar data comparison
• 'nodegroup' - Match on nodegroup
• 'range' - Use a Range server for matching
• 'compound' - Pass a compound match string
ret
Specify the returner to use. The value passed can be
single returner, or a comma delimited list of returners to call in order on the minions

Compound Command Execution With the Salt API

The Salt client API can also send what is called a compound command. Often a collection of commands need to be executed on the targeted minions, rather than send the commands one after another, they can be sent in a single publish containing a series of commands. This can dramatically lower overhead and speed up the application communicating with Salt.
When commands are executed with compound execution the minion functions called are executed in serial on the minion and the return value is sent back in a different fashion. The return value is a dict, with the function names as keys to the function returns as values.
Using the compound command execution system via the API requires that the fun value and the arg value are lists matching by index. This ensures that the order of the executions can be controlled. Any function that has no arguments MUST have an empty array in the corresponding arg index.
All client command methods can execute compound commands.
# Import the Salt client library import salt.client # create a local client object client = salt.client.LocalClient() # make compound execution calls with the cmd method ret = client.cmd('*', ['cmd.run', 'test.ping', 'test.echo'], [['ls -l'], [], ['foo']])
This will execute cmd.run ls -l then test.ping and finally test.echo foo. The return data from the minion will look like this:
{'cmd.run': '<output from ls -l>', 'test.ping': True, 'test.echo': 'foo'}

Salt Caller API

The Salt minion caller api can be used to simplify the execution and use of minion elements. The caller api is useful for accessing the Salt api, direct access to the state functions, using the matcher interface on a single minion, and as an api for the peer interface. Using the api is fairly straightforward: # Import the Salt client library import salt.client # Create the caller object caller = salt.client.Caller() # call a function caller.function('test.ping') # Call objects directly: caller.sminion.functions['cmd.run']('ls -l')

File Server Backends

Salt version 0.12.0 introduced the ability for the Salt Master to integrate different file server backends. File server backends allows the Salt file server to act as a transparent bridge to external resources. The primary example of this is the git backend which allows for all of the Salt formulas and files to be maintained in a remote git repository.

The fileserver backend system can accept multiple backends as well. This makes it possible to have the environments listed in the file_roots configuration available in addition to other backends, or the ability to mix multiple backends.

This feature is managed by the fileserver_backend option in the master config. The desired backend systems are listed in order of search priority:

fileserver_backend:
  - roots
  - git

If this configuration the environments and files defined in the file_roots configuration will be searched first, if the referenced environment and file is not found then the git backend will be searched.

Environments

The concept of environments is followed in all backend systems. The environments in the classic roots backend are defined in the file_roots option. Environments map differently based on the backend, for instance the git backend translated branches and tags in git to environments. This makes it easy to define environments in git by just setting a tag or forking a branch.

Dynamic Module Distribution

New in version 0.9.5.

Salt Python modules can be distributed automatically via the Salt file server. Under the root of any environment defined via the file_roots option on the master server directories corresponding to the type of module can be used.

Module sync

Automatically transfer and load modules, grains, renderers, returners, states, etc from the master to the minions.

The directories are prepended with an underscore:

_modules

_grains

_renderers

_returners

_states

The contents of these directories need to be synced over to the minions after Python modules have been created in them. There are a number of ways to sync the modules.

Sync Via States

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

Sync Via the saltutil Module

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

File Server Configuration

The Salt file server is a high performance file server written in ZeroMQ. It manages large files quickly and with little overhead, and has been optimized to handle small files in an extremely efficient manner.

The Salt file server is an environment aware file server. This means that files can be allocated within many root directories and accessed by specifying both the file path and the environment to search. The individual environments can span across multiple directory roots to create overlays and to allow for files to be organized in many flexible ways.

Environments

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

Directory Overlay

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

Local File Server

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

Salt File Server

Salt comes with a simple file server suitable for distributing files to the Salt minions. The file server is a stateless ZeroMQ server that is built into the Salt master.

The main intent of the Salt file server is to present files for use in the Salt state system. With this said, the Salt file server can be used for any general file transfer from the master to the minions.

The cp Module

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

Environments

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

get_file

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

get_dir

The cp.get_dir function can be used on the minion to download an entire directory from the master. The syntax is very similar to get_file: # salt '*' cp.get_dir salt://etc/apache2 /etc cp.get_dir supports template rendering and gzip compression arguments just like get_file: # salt '*' cp.get_dir salt://etc/{{"{{"}}pillar.webserver}} /etc gzip=5 template=jinja

File Server Client API

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

FileClient Class

The FileClient class is used to set up the communication from the minion to the master. When creating a FileClient object the minion configuration needs to be passed in. When using the FileClient from within a minion module the built in __opts__ data can be passed:
import salt.minion def get_file(path, dest, env='base'): ''' Used to get a single file from the Salt master CLI Example: salt '*' cp.get_file salt://vimrc /etc/vimrc ''' # Create the FileClient object client = salt.minion.FileClient(__opts__) # Call get_file return client.get_file(path, dest, False, env)
Using the FileClient class outside of a minion module where the __opts__ data is not available, it needs to be generated:
import salt.minion import salt.config def get_file(path, dest, env='base'): ''' Used to get a single file from the Salt master ''' # Get the configuration data opts = salt.config.minion_config('/etc/salt/minion') # Create the FileClient object client = salt.minion.FileClient(opts) # Call get_file return client.get_file(path, dest, False, env)

Configuration File Examples

• Example master configuration file • Example minion configuration file

Example master configuration file

##### Primary configuration settings ##### ########################################## # This configuration file is used to manage the behavior of the Salt Master # Values that are commented out but have no space after the comment are # defaults that need not be set in the config. If there is a space after the # comment that the value is presented as an example and is not the default. # Per default, the master will automatically include all config files # from master.d/*.conf (master.d is a directory in the same directory # as the main master config file) #default_include: master.d/*.conf # The address of the interface to bind to #interface: 0.0.0.0 # The tcp port used by the publisher #publish_port: 4505 # The user to run the salt-master as. Salt will update all permissions to # allow the specified user to run the master. If the modified files cause # conflicts set verify_env to False. #user: root # Max open files # 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) # # By default this value will be the one of `ulimit -Hn`, ie, the hard limit for # max open files. # # If you wish 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 your OS and/or distribution, # a good way to find the limit is to search the internet for(for example): # raise max open files hard limit debian # #max_open_files: 100000 # The number of worker threads to start, these threads are used to manage # return calls made from minions to the master, if the master seems to be # running slowly, increase the number of threads #worker_threads: 5 # The port used by the communication interface. The ret (return) port is the # interface used for the file server, authentication, job returnes, etc. #ret_port: 4506 # Specify the location of the daemon process ID file #pidfile: /var/run/salt-master.pid # The root directory prepended to these options: pki_dir, cachedir, # sock_dir, log_file, autosign_file, extension_modules, key_logfile, pidfile. #root_dir: / # Directory used to store public key data #pki_dir: /etc/salt/pki/master # Directory to store job and cache data #cachedir: /var/cache/salt/master # Verify and set permissions on configuration directories at startup #verify_env: True # Set the number of hours to keep old job information in the job cache #keep_jobs: 24 # Set the default timeout for the salt command and api, the default is 5 # seconds #timeout: 5 # The loop_interval option controls the seconds for the master's maintinance # process check cycle. This process updates file server backends, cleans the # job cache and executes the scheduler. #loop_interval: 60 # Set the default outputter used by the salt command. The default is "nested" #output: nested # By default output is colored, to disable colored output set the color value # to False #color: True # Set the directory used to hold unix sockets #sock_dir: /var/run/salt/master # The master maintains a 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. # #job_cache: True # Cache minion grains and pillar data in the cachedir. #minion_data_cache: True # 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 master configuration file lives in (this file). 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 a config file from some other path: # include: /etc/salt/extra_config # # Include config from several files and directories: # include: # - /etc/salt/extra_config ##### Security settings ##### ########################################## # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open mode # you do so at your own risk! #open_mode: False # Enable auto_accept, this setting will automatically accept all incoming # public keys from the minions. Note that this is insecure. #auto_accept: False # If the autosign_file is specified only incoming keys specified in # the autosign_file will be automatically accepted. This is insecure. # Regular expressions as well as globing lines are supported. #autosign_file: /etc/salt/autosign.conf # 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 # Allow users on the master access to execute specific commands on minions. # This setting should be treated with care since it opens up execution # capabilities to non root users. By default this capability is completely # disabled. # # client_acl: # larry: # - test.ping # - network.* # # Blacklist any of the following 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. # # client_acl_blacklist: # users: # - root # - '^(?!sudo_).*$' # all non sudo users # modules: # - cmd # 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.* # # Time (in seconds) for a newly generated token to live. Default: 12 hours # token_expire: 43200 ##### Master Module Management ##### ########################################## # Manage how master side modules are loaded # Add any additional locations to look for master runners #runner_dirs: [] # Enable Cython for master side modules #cython_enable: False ##### State System settings ##### ########################################## # 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 as defined in "File Server settings" below. #state_top: top.sls # The master_tops option replaces the external_nodes option by creating # a plugable 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> # #master_tops: {} # The external_nodes option allows Salt to gather data that would normally be # placed in a top file. The external_nodes option is the executable that will # return the ENC data. Remember that Salt will look for external nodes AND top # files and combine the results if both are enabled! #external_nodes: None # The renderer to use on the minions to render the state data #renderer: yaml_jinja # The failhard option tells the minions to stop immediately after the first # failure detected in the state execution, defaults to False #failhard: False # The state_verbose and state_output settings can be used to change the way # state system data is printed to the display. By default all data is printed. # The state_verbose setting can be set to True or False, when set to False # all data that has a result of True and no changes will be suppressed. #state_verbose: True # The state_output setting changes if the output is the full multi line # output for each changed state if set to 'full', but if set to 'terse' # the output will be shortened to a single line. #state_output: full ##### File Server settings ##### ########################################## # 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 #file_roots: # base: # - /srv/salt # The hash_type is the hash to use when discovering the hash of a file on # the master server, the default is md5, but sha1, sha224, sha256, sha384 # and sha512 are also supported. #hash_type: md5 # The buffer size in the file server can be adjusted here: #file_buffer_size: 1048576 # 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($|/)' # 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' # File Server Backend # 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 uses the "file_roots" option. #fileserver_backend: # - roots # To use multiple backends list them in the order they are searched: # fileserver_backend: # - git # - roots # Git fileserver backend configuration # 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. # gitfs_remotes: # - git://github.com/saltstack/salt-states.git # - file:///var/git/saltmaster # 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. # When using the git backend branches and tags are translated into salt # environments. ##### Pillar settings ##### ########################################## # Salt Pillars allow for the building of global data that can be made selectively # available to different minions based on minion grain filtering. The Salt # Pillar is laid out in the same fashion as the file server, with environments, # a top file and sls files. However, pillar data does not need to be in the # highstate format, and is generally just key/value pairs. #pillar_roots: # base: # - /srv/pillar # ext_pillar: # - hiera: /etc/hiera.yaml # - cmd_yaml: cat /etc/salt/yaml # The pillar_opts option adds the master configuration file data to a dict in # the pillar called "master". This is used to set simple configurations in the # master config file that can then be used on minions. #pillar_opts: True ##### Syndic settings ##### ########################################## # The Salt syndic is used to pass commands through a master from a higher # master. 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 # to receive commands from. # Set the order_masters setting to True if this master will command lower # masters' syndic interfaces. #order_masters: False # If this master will be running a salt syndic daemon, syndic_master tells # this master where to receive commands from. #syndic_master: masterofmaster ##### 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. # 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! # Minions can also be allowed to execute runners from the salt master. # Since executing a runner from the minion could be considered a security risk, # it needs to be enabled. This setting functions just like the peer setting # except that it opens up runners instead of module functions. # # All peer runner support is turned off by default and must be enabled before # using. This will enable all peer runners for all minions: # # peer_run: # .*: # - .* # # To enable just the manage.up runner for the minion foo.example.com: # # peer_run: # foo.example.com: # - manage.up ##### Logging settings ##### ########################################## # The location of the master log file # The master log can be sent to a regular file, local path name, or network # location. Remote logging works best when configured to use rsyslogd(8) (e.g.: # ``file:///dev/log``), with rsyslogd(8) configured for network logging. The URI # format is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility> # log_file: /var/log/salt/master # log_file: file:///dev/log # log_file: udp://loghost:10514 #log_file: /var/log/salt/master #key_logfile: /var/log/salt/key # The level of messages to send to the console. # One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'. #log_level: warning # The level of messages to send to the log file. # One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'. #log_level_logfile: warning # The date and time format used in log messages. Allowed date/time formating # can be seen here: http://docs.python.org/library/time.html#time.strftime #log_datefmt: '%H:%M:%S' #log_datefmt_logfile: '%Y-%m-%d %H:%M:%S' # The format of the console logging messages. Allowed formatting options can # be seen here http://docs.python.org/library/logging.html#logrecord-attributes #log_fmt_console: '[%(levelname)-8s] %(message)s' #log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s' # This can be used to control logging levels more specificically. This # example sets the main salt library at the 'warning' level, but sets # 'salt.modules' to log at the 'debug' level: # log_granular_levels: # 'salt': 'warning', # 'salt.modules': 'debug' # #log_granular_levels: {} ##### Node Groups ##### ########################################## # 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 and bl*.domain.com' # group2: 'G@os:Debian and foo.domain.com' ##### Range Cluster settings ##### ########################################## # The range server (and optional port) that serves your cluster information # https://github.com/grierj/range/wiki/Introduction-to-Range-with-YAML-files # # range_server: range:80 ##### Windows Software Repo settings ##### ############################################## # Location of the repo on the master # win_repo: '/srv/salt/win/repo' # Location of the master's repo cache file # win_repo_mastercachefile: '/srv/salt/win/repo/winrepo.p' # List of git repositories to include with the local repo # win_gitrepos: # - 'https://github.com/saltstack/salt-winrepo.git'

Example minion configuration file

##### Primary configuration settings ##### ########################################## # Per default the minion will automatically include all config files # from minion.d/*.conf (minion.d is a directory in the same directory # as the main minion config file). #default_include: minion.d/*.conf # Set the location of the salt master server, if the master server cannot be # resolved, then the minion will fail to start. #master: salt # 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 # Set the port used by the master reply and authentication server #master_port: 4506 # The user to run salt #user: root # Specify the location of the daemon process ID file #pidfile: /var/run/salt-minion.pid # The root directory prepended to these options: pki_dir, cachedir, log_file, # sock_dir, pidfile. #root_dir: / # The directory to store the pki information in #pki_dir: /etc/salt/pki/minion # Explicitly declare the id for this minion to use, if left commented the id # will be the hostname as returned by the python call: socket.getfqdn() # Since salt uses detached ids it is possible to run multiple minions on the # same machine but with different ids, this can be useful for salt compute # clusters. #id: # Append a domain to a hostname in the event that it does not exist. This is # useful for systems where socket.getfqdn() does not actually result in a # FQDN (for instance, Solaris). #append_domain: # Custom static grains for this minion can be specified here and used in SLS # files just like all other grains. This example sets 4 custom grains, with # the 'roles' grain having two values that can be matched against: #grains: # roles: # - webserver # - memcache # deployment: datacenter4 # cabinet: 13 # cab_u: 14-15 # Where cache data goes #cachedir: /var/cache/salt/minion # Verify and set permissions on configuration directories at startup #verify_env: True # The minion can locally cache the return data from jobs sent to it, this # can be a good way to keep track of jobs the minion has executed # (on the minion side). By default this feature is disabled, to enable # set cache_jobs to True #cache_jobs: False # set the directory used to hold unix sockets #sock_dir: /var/run/salt/minion # Set the default outputter used by the salt-call command. The default is # "nested" #output: nested # # By default output is colored, to disable colored output set the color value # to False #color: True # Backup files that are replaced by file.managed and file.recurse under # 'cachedir'/file_backups relative to their original location and appended # with a timestamp. The only valid setting is "minion". Disabled by default. # # Alternatively this can be specified for each file in state files: # # /etc/ssh/sshd_config: # file.managed: # - source: salt://ssh/sshd_config # - backup: minion # #backup_mode: minion # When waiting for a master to accept the minion's public key, salt will # continuously attempt to reconnect until successful. This is the time, in # seconds, between those reconnection attempts. #acceptance_wait_time: 10 # The loop_interval sets how long in seconds the minion will wait between # evaluating the scheduler and running cleanup tasks. This defaults to a # sane 60 seconds, but if the minion scheduler needs to be evaluated more # often lower this value #loop_interval: 60 # When healing, a dns_check is run. This is to make sure that the originally # resolved dns has not changed. If this is something that does not happen in # your environment, set this value to False. #dns_check: True # Windows platforms lack posix IPC and must rely on slower TCP based inter- # process communications. Set ipc_mode to 'tcp' on such systems #ipc_mode: ipc # # Overwrite the default tcp ports used by the minion when in tcp mode #tcp_pub_port: 4510 #tcp_pull_port: 4511 # The minion can include configuration from other files. To enable this, # pass a list of paths to this option. The paths can be either relative or # absolute; if relative, they are considered to be relative to the directory # the main minion configuration file lives in (this file). Paths can make use # of shell-style globbing. If no files are matched by a path passed to this # option then the minion will log a warning message. # # # Include a config file from some other path: # include: /etc/salt/extra_config # # Include config from several files and directories: # include: # - /etc/salt/extra_config # - /etc/roles/webserver ##### Minion module management ##### ########################################## # Disable specific modules. This allows the admin to limit the level of # access the master has to the minion #disable_modules: [cmd,test] #disable_returners: [] # # Modules can be loaded from arbitrary paths. This enables the easy deployment # of third party modules. Modules for returners and minions can be loaded. # Specify a list of extra directories to search for minion modules and # returners. These paths must be fully qualified! #module_dirs: [] #returner_dirs: [] #states_dirs: [] #render_dirs: [] # # A module provider can be statically overwritten or extended for the minion # via the providers option, in this case the default module will be # overwritten by the specified module. In this example the pkg module will # be provided by the yumpkg5 module instead of the system default. # # providers: # pkg: yumpkg5 # # Enable Cython modules searching and loading. (Default: False) #cython_enable: False # ##### State Management Settings ##### ########################################### # The state management system executes all of the state templates on the minion # to enable more granular control of system state management. The type of # template and serialization used for state management needs to be configured # on the minion, the default renderer is yaml_jinja. This is a yaml file # rendered from a jinja template, the available options are: # yaml_jinja # yaml_mako # yaml_wempy # json_jinja # json_mako # json_wempy # #renderer: yaml_jinja # # The failhard option tells the minions to stop immediately after the first # failure detected in the state execution, defaults to False #failhard: False # # autoload_dynamic_modules Turns on automatic loading of modules found in the # environments on the master. This is turned on by default, to turn of # autoloading modules when states run set this value to False #autoload_dynamic_modules: True # # clean_dynamic_modules keeps the dynamic modules on the minion in sync with # the dynamic modules on the master, this means that if a dynamic module is # not on the master it will be deleted from the minion. By default this is # enabled and can be disabled by changing this value to False #clean_dynamic_modules: True # # Normally the minion is not isolated to any single environment on the master # when running states, but the environment can be isolated on the minion side # by statically setting it. Remember that the recommended way to manage # environments is to isolate via the top file. #environment: None # # If using the local file directory, then the state top file name needs to be # defined, by default this is top.sls. #state_top: top.sls # # Run states when the minion daemon starts. To enable, set startup_states to: # 'highstate' -- Execute state.highstate # 'sls' -- Read in the sls_list option and execute the named sls files # 'top' -- Read top_file option and execute based on that file on the Master #startup_states: '' # # list of states to run when the minion starts up if startup_states is 'sls' #sls_list: # - edit.vim # - hyper # # top file to execute if startup_states is 'top' #top_file: '' ##### File Directory Settings ##### ########################################## # The Salt Minion can redirect all file server operations to a local directory, # this allows for the same state tree that is on the master to be used if # copied completely onto the minion. This is a literal copy of the settings on # the master but used to reference a local directory on the minion. # Set the file client, the client defaults to looking on the master server for # files, but can be directed to look at the local file directory setting # defined below by setting it to local. #file_client: remote # The file directory works on environments passed to the minion, 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 # # Default: #file_roots: # base: # - /srv/salt # The hash_type is the hash to use when discovering the hash of a file in # the minion directory, the default is md5, but sha1, sha224, sha256, sha384 # and sha512 are also supported. #hash_type: md5 # The Salt pillar is searched for locally if file_client is set to local. If # this is the case, and pillar data is defined, then the pillar_roots need to # also be configured on the minion: #pillar_roots: # base: # - /srv/pillar ###### Security settings ##### ########################################### # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open mode # you do so at your own risk! #open_mode: 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. #permissive_pki_access: False # The state_verbose and state_output settings can be used to change the way # state system data is printed to the display. By default all data is printed. # The state_verbose setting can be set to True or False, when set to False # all data that has a result of True and no changes will be suppressed. #state_verbose: True # # The state_output setting changes if the output is the full multi line # output for each changed state if set to 'full', but if set to 'terse' # the output will be shortened to a single line. #state_output: full # # Fingerprint of the master public key to double verify the master is valid, # the master fingerprint can be found by running "salt-key -F master" on the # salt master. #master_finger: '' ###### Thread settings ##### ########################################### # Disable multiprocessing support, by default when a minion receives a # publication a new process is spawned and the command is executed therein. #multiprocessing: True ##### Logging settings ##### ########################################## # The location of the minion log file # The minion log can be sent to a regular file, local path name, or network # location. Remote logging works best when configured to use rsyslogd(8) (e.g.: # ``file:///dev/log``), with rsyslogd(8) configured for network logging. The URI # format is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility> # log_file: /var/log/salt/minion # log_file: file:///dev/log # log_file: udp://loghost:10514 # #log_file: /var/log/salt/minion #key_logfile: /var/log/salt/key # # The level of messages to send to the console. # One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'. # Default: 'warning' #log_level: warning # # The level of messages to send to the log file. # One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'. # Default: 'warning' #log_level_logfile: # The date and time format used in log messages. Allowed date/time formating # can be seen here: http://docs.python.org/library/time.html#time.strftime #log_datefmt: '%H:%M:%S' #log_datefmt_logfile: '%Y-%m-%d %H:%M:%S' # # The format of the console logging messages. Allowed formatting options can # be seen here http://docs.python.org/library/logging.html#logrecord-attributes #log_fmt_console: '[%(levelname)-8s] %(message)s' #log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s' # # This can be used to control logging levels more specificically. This # example sets the main salt library at the 'warning' level, but sets # 'salt.modules' to log at the 'debug' level: # log_granular_levels: # 'salt': 'warning', # 'salt.modules': 'debug' # #log_granular_levels: {} ###### Module configuration ##### ########################################### # Salt allows for modules to be passed arbitrary configuration data, any data # passed here in valid yaml format will be passed on to the salt minion modules # for use. It is STRONGLY recommended that a naming convention be used in which # the module name is followed by a . and then the value. Also, all top level # data must be applied via the yaml dict construct, some examples: # # You can specify that all modules should run in test mode: #test: True # # A simple value for the test module: #test.foo: foo # # A list for the test module: #test.bar: [baz,quo] # # A dict for the test module: #test.baz: {spam: sausage, cheese: bread} ###### Update settings ###### ########################################### # Using the features in Esky, a salt minion can both run as a frozen app and # be updated on the fly. These options control how the update process # (saltutil.update()) behaves. # # The url for finding and downloading updates. Disabled by default. #update_url: False # # The list of services to restart after a successful update. Empty by default. #update_restart_services: [] ###### Keepalive settings ###### ############################################ # ZeroMQ now includes support for configuring SO_KEEPALIVE if supported by # the OS. If connections between the minion and the master pass through # a state tracking device such as a firewall or VPN gateway, there is # the risk that it could tear down the connection the master and minion # without informing either party that their connection has been taken away. # Enabling TCP Keepalives prevents this from happening. # # Overall state of TCP Keepalives, enable (1 or True), disable (0 or False) # or leave to the OS defaults (-1), on linux, typically disabled. Default True, enabled. #tcp_keepalive: True # # How long before the first keepalive should be sent in seconds. Default 300 # to send the first keepalive after 5 minutes, OS default (-1) is typically 7200 seconds # on Linux see /proc/sys/net/ipv4/tcp_keepalive_time. #tcp_keepalive_idle: 300 # # How many lost probes are needed to consider the connection lost. Default -1 # to use OS defaults, typically 9 on Linux, see /proc/sys/net/ipv4/tcp_keepalive_probes. #tcp_keepalive_cnt: -1 # # How often, in seconds, to send keepalives after the first one. Default -1 to # use OS defaults, typically 75 seconds on Linux, see # /proc/sys/net/ipv4/tcp_keepalive_intvl. #tcp_keepalive_intvl: -1 ###### Windows Software settings ###### ############################################ # Location of the repository cache file on the master # win_repo_cachefile: 'salt://win/repo/winrepo.p'

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. The available options are as follows:

Primary Master Configuration

interface

Default: 0.0.0.0 (all interfaces)
The local interface to bind to.
interface: 192.168.0.1

publish_port

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

user

Default: root
The user to run the Salt processes
user: root

max_open_files

Default: max_open_files
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)
By default this value will be the one of ulimit -Hn, ie, the hard limit for max open files.
If you wish 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 your OS and/or distribution, a good way to find the limit is to search the internet for(for example):
raise max open files hard limit debian max_open_files: 100000

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

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

pki_dir

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

cachedir

Default: /var/cache/salt
The location used to store cache information, particularly the job information for executed salt commands.
cachedir: /var/cache/salt

keep_jobs

Default: 24 Set the number of hours to keep old job information

job_cache

Default: True
The master maintains a 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

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

sock_dir

Default:: /tmp/salt-unix
Set the location to use for creating Unix sockets for master process communication

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 the minions
auto_accept: False

autosign_file

Default not defined
If the autosign_file is specified incoming keys specified in the autosign_file will be automatically accepted. Regular expressions as well as globbing can be used. This is insecure!

client_acl

Default: {} Enable user accounts on the master to execute specific modules. These modules can be expressed as regular expressions client_acl: fred: - test.ping - pkg.*

Master Module Management

runner_dirs

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

cython_enable

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

Master State System Settings

state_verbose

Default: False
state_verbose allows for the data returned from the minion to be more verbose. Normally only states that fail or states that have changes are returned, but setting state_verbose to True will return all states that were checked
state_verbose: True

state_output

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

state_top

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

external_nodes

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

renderer

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

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

test

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

Master File Server Settings

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 base: - /srv/salt

hash_type

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

file_buffer_size

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

Pillar Configuration

pillar_roots

Set the environments and directories used to hold pillar sls data. This configuration is the same as file_roots:
Default: base: [/srv/pillar]
pillar_roots: base: - /srv/pillar/ dev: - /srv/pillar/dev/ prod: - /srv/pillar/prod/ base: - /srv/pillar

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 are: hiera, cmd_yaml. By default the ext_pillar interface is not configured to run.
Default:: None
ext_pillar: - hiera: /etc/hiera.yaml - cmd_yaml: cat /etc/salt/yaml
There are additional details at salt-pillars

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

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

Default: None
If this master will be running a salt-syndic to connect to a higher level master, specify the higher level master with this configuration value
syndic_master: masterofmasters

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!

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

Node Groups

Default: {} Node groups allow for logical groupings of minion nodes. A group consists of a group name and a compound target. nodegroups: group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com' group2: 'G@os:Debian and foo.domain.com'

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. Remote logging works best when configured to use rsyslogd(8) (e.g.: file:///dev/log), with rsyslogd(8) configured for network logging. The format for remote addresses is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>. 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. One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
log_level: warning

log_level_logfile

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

log_datefmt

Default: %H:%M:%S
The date and time format used in console log messages. Allowed date/time formating can be seen on http://docs.python.org/library/time.html#time.strftime
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. Allowed date/time formating can be seen on http://docs.python.org/library/time.html#time.strftime
log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'

log_fmt_console

Default: [%(levelname)-8s] %(message)s
The format of the console logging messages. Allowed formatting options can be seen on http://docs.python.org/library/logging.html#logrecord-attributes
log_fmt_console: '[%(levelname)-8s] %(message)s'

log_fmt_logfile

Default: %(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s
The format of the log file logging messages. Allowed formatting options can be seen on http://docs.python.org/library/logging.html#logrecord-attributes
log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'

log_granular_levels

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

default_include

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

Configuring The Salt Minion

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 can find its master.

Minion Primary Configuration

master

Default: salt
The hostname or ipv4 of the master.
master: salt

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

user

Default: root
The user to run the Salt processes
user: root

pidfile

Default: /var/run/salt-minion.pid
The location of the daemon's process ID file
pidfie: /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: /

pki_dir

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

Default: hostname (as returned by the Python call: socket.getfqdn())
Explicitly declare the id for this minion to use, if left commented the id will be the hostname as returned by the Python call: socket.getfqdn() Since Salt uses detached ids it is possible to run multiple minions on the same machine but with different ids, this can be useful for Salt compute clusters.
id: foo.bar.com

append_domain

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

cachedir

Default: /var/cache/salt
The location for minion cache data.
cachedir: /var/cache/salt

verify_env

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

cache_jobs

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

sock_dir

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

backup_mode

Default: [] Backup files replaced by file.managed and file.recurse under cachedir. backup_mode: minion

acceptance_wait_time

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

dns_check

Default: True
When healing, a dns_check is run. This is to make sure that the originally resolved dns has not changed. If this is something that does not happen in your environment, set this value to False.
dns_check: True

ipc_mode

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

tcp_pub_port

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

tcp_pull_port

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

Minion Module Management

disable_modules

Default: [] (all modules are enabled by default) The event may occur in which the administrator desires that a minion should not be able to execute a certain module. The sys module is built into the minion and cannot be disabled. This setting can also tune the minion, as all modules are loaded into ram disabling modules will lover the minion's ram footprint. disable_modules: - test - solr

disable_returners

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

module_dirs

Default: [] A list of extra directories to search for Salt modules module_dirs: - /var/lib/salt/modules

returner_dirs

Default: [] A list of extra directories to search for Salt returners returners_dirs: - /var/lib/salt/returners

states_dirs

Default: [] A list of extra directories to search for Salt states states_dirs: - /var/lib/salt/states

render_dirs

Default: [] A list of extra directories to search for Salt renderers render_dirs: - /var/lib/salt/renderers

cython_enable

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

providers

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

State Management Settings

renderer

Default: yaml_jinja
The default renderer used for local state executions
renderer: yaml_jinja

state_verbose

Default: False
state_verbose allows for the data returned from the minion to be more verbose. Normally only states that fail or states that have changes are returned, but setting state_verbose to True will return all states that were checked
state_verbose: True

state_output

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

autoload_dynamic_modules

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

environment

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

Security Settings

open_mode

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

Thread Settings

Default: True
Disable multiprocessing support by default when a minion receives a publication a new process is spawned and the command is executed therein.
multiprocessing: True

Minion Logging Settings

log_file

Default: /var/log/salt/minion
The minion log can be sent to a regular file, local path name, or network location. Remote logging works best when configured to use rsyslogd(8) (e.g.: file:///dev/log), with rsyslogd(8) configured for network logging. The format for remote addresses is: <file|udp|tcp>://<host|socketpath>:<port-if-required>/<log-facility>. Examples:
log_file: /var/log/salt/minion log_file: file:///dev/log log_file: udp://loghost:10514

log_level

Default: warning
The level of messages to send to the console. One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
log_level: warning

log_level_logfile

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

log_datefmt

Default: %H:%M:%S
The date and time format used in console log messages. Allowed date/time formating can be seen on http://docs.python.org/library/time.html#time.strftime
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. Allowed date/time formating can be seen on http://docs.python.org/library/time.html#time.strftime
log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'

log_fmt_console

Default: [%(levelname)-8s] %(message)s
The format of the console logging messages. Allowed formatting options can be seen on http://docs.python.org/library/logging.html#logrecord-attributes
log_fmt_console: '[%(levelname)-8s] %(message)s'

log_fmt_logfile

Default: %(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s
The format of the log file logging messages. Allowed formatting options can be seen on http://docs.python.org/library/logging.html#logrecord-attributes
log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'

log_granular_levels

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

default_include

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

include

Default: not defined
The minion can include configuration from other files. To enable this, pass a list of paths to this option. The paths can be either relative or absolute; if relative, they are considered to be relative to the directory the main minion configuration file lives in. Paths can make use of shell-style globbing. If no files are matched by a path passed to this option then the minion will log a warning message.
# Include files from a minion.d directory in the same # directory as the minion config file include: minion.d/* # Include a single extra file into the configuration include: /etc/roles/webserver # Include several files and the minion.d directory include: - extra_config - minion.d/* - /etc/roles/webserver

Frozen Build Update Settings

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

update_url

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

update_restart_services

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

Salt Code And Internals

Reference documentation on Salt's internal code.

Contents

Exceptions

Salt-specific exceptions should be thrown as often as possible so the various interfaces to Salt (CLI, API, etc) can handle those errors appropriately and display error messages appropriately.
salt.exceptions
This module is a central location for all salt exceptions
exception salt.exceptions.AuthenticationError: If sha256 signature fails during decryption
exception salt.exceptions.CommandExecutionError: Used when a module runs a command which returns an error and wants to show the user the output gracefully instead of dying
exception salt.exceptions.CommandNotFoundError: Used in modules or grains when a required binary is not available
exception salt.exceptions.EauthAuthenticationError: Thrown when eauth authentication fails
exception salt.exceptions.LoaderError: Problems loading the right renderer
exception salt.exceptions.MinionError: Minion problems reading uris such as salt:// or http://
exception salt.exceptions.PkgParseError: Used when of the pkg modules cannot correctly parse the output from the CLI tool (pacman, yum, apt, aptitude, etc)
exception salt.exceptions.SaltClientError: Problem reading the master root key
exception salt.exceptions.SaltException: Base exception class; all Salt-specific exceptions should subclass this
exception salt.exceptions.SaltInvocationError: Used when the wrong number of arguments are sent to modules or invalid arguments are specified on the command line
exception salt.exceptions.SaltMasterError: Problem reading the master root key
exception salt.exceptions.SaltRenderError: Used when a renderer needs to raise an explicit error
exception salt.exceptions.SaltReqTimeoutError: Thrown when a salt master request call fails to return within the timeout
exception salt.exceptions.SaltSystemExit: This exception is raised when an unsolvable problem is found. There's nothing else to do, salt should just exit.

salt.exceptions

This module is a central location for all salt exceptions
exception salt.exceptions.AuthenticationError: If sha256 signature fails during decryption
exception salt.exceptions.CommandExecutionError: Used when a module runs a command which returns an error and wants to show the user the output gracefully instead of dying
exception salt.exceptions.CommandNotFoundError: Used in modules or grains when a required binary is not available
exception salt.exceptions.EauthAuthenticationError: Thrown when eauth authentication fails
exception salt.exceptions.LoaderError: Problems loading the right renderer
exception salt.exceptions.MinionError: Minion problems reading uris such as salt:// or http://
exception salt.exceptions.PkgParseError: Used when of the pkg modules cannot correctly parse the output from the CLI tool (pacman, yum, apt, aptitude, etc)
exception salt.exceptions.SaltClientError: Problem reading the master root key
exception salt.exceptions.SaltException: Base exception class; all Salt-specific exceptions should subclass this
exception salt.exceptions.SaltInvocationError: Used when the wrong number of arguments are sent to modules or invalid arguments are specified on the command line
exception salt.exceptions.SaltMasterError: Problem reading the master root key
exception salt.exceptions.SaltRenderError: Used when a renderer needs to raise an explicit error
exception salt.exceptions.SaltReqTimeoutError: Thrown when a salt master request call fails to return within the timeout
exception salt.exceptions.SaltSystemExit: This exception is raised when an unsolvable problem is found. There's nothing else to do, salt should just exit.

Network Topology

Salt is based on a powerful, asynchronous, network topology using ZeroMQ. Many ZeroMQ systems are in place to enable communication. The central idea is to have the fastest communication possible.

Servers

The Salt Master runs 2 network services. First is the ZeroMQ PUB system. This service by default runs on port 4505 and can be configured via the publish_port option in the master configuration.
Second is the ZeroMQ REP system. This is a seperate interface used for all bi-directional communication with minions. By default this system binds to port 4506 and can be configured via the ret_port option in the master.

PUB/SUB

The commands sent out via the salt client are broadcast out to the minions via ZeroMQ PUB/SUB. This is done by allowing the minions to maintain a connection back to the Salt Master and then all connecions are informed to download the command data at once. The command data is kept extreamly small (usually less than 1K) so it is not a burden on the network.

Return

The PUB/SUB system is a one way communication, so once a publish is sent out the PUB interface on the master has no further communication with the minion. The minion, after running the command, then sends the command's return data back to the master via the ret_port.

Windows Software Repository

The Salt Windows Software Repository provides a package manager and software repository similar to what is provided by yum and apt on Linux.

By default, the Windows software repository is found at /srv/salt/win/repo Each piece of software should have its own directory which contains the installers and a package definition file. This package definition file is a yaml file named init.sls.

The package definition file should look similar to this example for Firefox: /srv/salt/win/repo/firefox/init.sls

firefox:
  17.0.1:
    installer: 'salt://win/repo/firefox/English/Firefox Setup 17.0.1.exe'
    full_name: Mozilla Firefox 17.0.1 (x86 en-US)
    locale: en_US
    reboot: False
    install_flags: ' -ms'
    uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
    uninstall_flags: ' /S'
  16.0.2:
    installer: 'salt://win/repo/firefox/English/Firefox Setup 16.0.2.exe'
    full_name: Mozilla Firefox 16.0.2 (x86 en-US)
    locale: en_US
    reboot: False
    install_flags: ' -ms'
    uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
    uninstall_flags: ' /S'
  15.0.1:
    installer: 'salt://win/repo/firefox/English/Firefox Setup 15.0.1.exe'
    full_name: Mozilla Firefox 15.0.1 (x86 en-US)
    locale: en_US
    reboot: False
    install_flags: ' -ms'
    uninstaller: '%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe'
    uninstall_flags: ' /S'

Generate Repo Cache File

Once the sls file has been created, generate the repository cache file with the winrepo runner: $ salt-run winrepo.genrepo Then update the repository cache file on your minions, exactly how it's done for the Linux package managers: $ salt \* pkg.refresh_db

Install Windows Software

Now you can query the available version of Firefox using the Salt pkg module. $ salt \* pkg.available_version firefox {'davewindows': {'15.0.1': 'Mozilla Firefox 15.0.1 (x86 en-US)', '16.0.2': 'Mozilla Firefox 16.0.2 (x86 en-US)', '17.0.1': 'Mozilla Firefox 17.0.1 (x86 en-US)'}} As you can see, there are three versions of Firefox available for installation. $ salt \* pkg.install firefox The above line will install the latest version of firefox. $ salt \* pkg.install firefox version=16.0.2 The above line will install version 16.0.2 of Firefox. This first release requires you uninstall an application and then install a newer version in order to accomplish an upgrade. This will be fixed very soon.

Uninstall Windows Software

Uninstall software using the pkg module: $ salt \* pkg.remove firefox

Git Hosted Repo

Windows software package definitions can also be hosted in one or more git repositories. The default repo is one hosted on Github.com by SaltStack, which includes package definitions for open source software. This repo points to the http or ftp locations of the installer files. Anyone is welcome to send a pull request to this repo to add new package definitions. Browse the repo here: https://github.com/saltstack/salt-winrepo .
Configure which git repos the master can search for package definitions by modifying or extending the win_gitrepos configuration option list in the master config.
Checkout each git repo in win_gitrepos, compile your package repository cache, and then refresh each minion's package cache:
$ salt-run winrepo.update_git_repos $ salt-run winrepo.genrepo $ salt \* pkg.refresh_db

Command Line Reference

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

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 regular expression to match the value of the grain. 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

Targeting with Executions

As of 0.8.8 targeting with executions is still under heavy development and this documentation is written to reference the behavior of execution matching in the future. Execution matching allows for a primary function to be executed, and then based on the return of the primary function the main function is executed. Execution matching allows for matching minions based on any arbitrary running data on the minions.

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.

Node Group Targeting

New in version 0.9.5. Often the convenience of having a predefined group of minions to execute targets on is desired. This can be accomplished with the new nodegroups feature. Nodegroups allow for predefined compound targets to be declared in the master configuration file: nodegroups: group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com' group2: 'G@os:Debian and foo.domain.com'

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.

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.

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

-h, --help: Print a usage message briefly summarizing these command-line options
-t TIMEOUT, --timeout=TIMEOUT: The timeout in seconds to wait for replies from the Salt minions. The timeout number specifes how long the command line client will wait to query the minions and check on running jobs.
-s STATIC, --static=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. To only return the data with a hard timeout and after all minions have returned then use the static option.
-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. 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.
--version: Print the version of Salt that is running.
--versions-report: Show program's dependencies version number and exit
-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.*'
-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.
-X, --exsel: Instead of using shell globs use the return code of a function.
-N, --nodegroup: Use a predefined compound target defined in the Salt master configuration file.
-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.
-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.
--return: Chose 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.
-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.
-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.
-d, --doc, --documentation: Return the documentation for the module functions available on the minions
--out
Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: grains, highstate, json, key, overstatestage, pprint, raw, txt, yaml Some outputters are formatted only for data returned from specific functions, for instance the grains outputter will not work for non grains data. If an outputter is used that does not support the data passed into it, then Salt will fall back on the pprint outputter and display the return data using the python pprint library.
--out-indent OUTPUT_INDENT, --output-indent OUTPUT_INDENT: Print the output indented by the provided value in spaces. Negative values disables indentation. Only applicable in outputters that support indentation.
--no-color: Disable all colored output

See also

salt(7) salt-master(1) salt-minion(1)

Salt-master

The Salt master daemon, used to control the Salt minions

Synopsis

salt-master [ options ]

Description

The master daemon controls the Salt minions

Options

-h, --help: Print a usage message briefly summarizing these command-line options.
--version: Show program's version number and exit
--versions-report: Show program's dependencies version number and exit
-d, --daemon: Run the Salt master as a daemon
-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.
-u USER, --user=USER: Specify user to run minion
--pid-file PIDFILE: Specify the location of the pidfile.
-l LOG_LEVEL, --log-level=LOG_LEVEL: Console log level. One of info, none, garbage, trace, warning, error, debug. For the logfile settings see the config file. Default: warning.

See also

salt(1) salt(7) salt-minion(1)

Salt-minion

The Salt minion daemon, receives commands from a remote Salt master.

Synopsis

salt-minion [ options ]

Description

The Salt minion receives commands from the central Salt master and replies with the results of said commands.

Options

-h, --help: Print a usage message briefly summarizing these command-line options.
-d, --daemon: Run the Salt minion as a daemon
-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.
-u USER, --user=USER: Specify user to run minion
--pid-file PIDFILE: Specify the location of the pidfile
-l LOG_LEVEL, --log-level=LOG_LEVEL: Console log level. One of info, none, garbage, trace, warning, error, debug. For the logfile settings see the config file. Default: warning.
--version: Show program's version number and exit
--versions-report: Show program's dependencies version number and exit

See also

salt(1) salt(7) salt-master(1)

Salt-key

Synopsis

salt-key [ options ]

Description

Salt-key executes simple management of Salt server public keys used for authentication.

Options

-h, --help: Print a usage message briefly summarizing these command-line options.
-l, --list: List the unaccepted minion public keys.
-L, --list-all: List all public keys on this Salt master: accepted, pending, and rejected.
-a ACCEPT, --accept=ACCEPT: Accept the named minion public key for command execution.
-A, --accept-all: Accepts all pending public keys.
-r REJECT, --reject=REJECT: Reject the named minion public key.
-R, --reject-all: Rejects all pending public keys.
-d DELETE, --delete=DELETE: Delete the named minion key or minion keys matching a glob for command execution.
-D, --delete-all: Delete all keys
-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.
-p PRINT, --print=PRINT: Print the specified public key
-P, --print-all: Print all public keys
-q, --quiet: Supress output
-y, --yes: Answer 'Yes' to all questions presented, defaults to False
--key-logfile=KEY_LOGFILE: Send all output to a file. Default is /var/log/salt/key
--gen-keys=GEN_KEYS: Set a name to generate a keypair for use with salt
--gen-keys-dir=GEN_KEYS_DIR: Set the directory to save the generated keypair. Only works with 'gen_keys_dir' option; default is the current directory.
--keysize=KEYSIZE: Set the keysize for the generated key, only works with the '--gen-keys' option, the key size must be 2048 or higher, otherwise it will be rounded up to 2048. The default is 2048.
--out
Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: grains, highstate, json, key, overstatestage, pprint, raw, txt, yaml Some outputters are formatted only for data returned from specific functions, for instance the grains outputter will not work for non grains data. If an outputter is used that does not support the data passed into it, then Salt will fall back on the pprint outputter and display the return data using the python pprint library.
--out-indent OUTPUT_INDENT, --output-indent OUTPUT_INDENT: Print the output indented by the provided value in spaces. Negative values disables indentation. Only applicable in outputters that support indentation.
--no-color: Disable all colored output
--version: Show program's version number and exit
--versions-report: Show program's dependencies version number and exit

See also

salt(7) salt-master(1) salt-minion(1)

Salt-cp

Copy a file to a set of systems

Synopsis

salt-cp '*' [ options ] SOURCE DEST salt-cp -E '.*' [ options ] SOURCE DEST salt-cp -G 'os:Arch.*' [ options ] SOURCE DEST

Description

Salt copy copies a local file out to all of the Salt minions matched by the given target.

Options

-h, --help: Print a usage message briefly summarizing these command-line options
-t TIMEOUT, --timeout=TIMEOUT: The timeout in seconds to wait for replies from the Salt minions.
-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*'
--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>:<pcre regular expression>'; example: 'os:Arch.*'
-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.
-c CONFIG, --config=CONFIG: The location of the Salt master configuration file, the Salt master settings are required to know where the connections are; default=/etc/salt/master

See also

salt(1) salt-master(1) salt-minion(1)

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.

Options

-h, --help: Print a usage message briefly summarizing these command-line options
-g, --grains: Return the information generated by the Salt grains
-m MODULE_DIRS, --module-dirs=MODULE_DIRS: Specify an additional directories to pull modules from, multiple directories can be delimited by commas
--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.
-d, --doc: Return the documentation for the specified module or for all modules if none are specified
-l LOG_LEVEL, --log-level=LOG_LEVEL: Console log level. One of info, none, garbage, trace, warning, error, debug. For the logfile settings see the config file. Default: info.
-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.
--out
Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: grains, highstate, json, key, overstatestage, pprint, raw, txt, yaml Some outputters are formatted only for data returned from specific functions, for instance the grains outputter will not work for non grains data. If an outputter is used that does not support the data passed into it, then Salt will fall back on the pprint outputter and display the return data using the python pprint library.
--out-indent OUTPUT_INDENT, --output-indent OUTPUT_INDENT: Print the output indented by the provided value in spaces. Negative values disables indentation. Only applicable in outputters that support indentation.
--no-color: Disable all colored output
--version: Show program's version number and exit
--versions-report: Show program's dependencies version number and exit

See also

salt(1) salt-master(1) salt-minion(1)

Salt-run

Execute a Salt runner

Synopsis

salt-run RUNNER

Description

salt-run is the frontend command for executing Salt Runners. Salt runners are simple modules used to execute convenience functions on the master

Options

-h, --help: Print a usage message briefly summarizing these command-line options
--version: Show program's version number and exit
--versions-report: Show program's dependencies version number 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.

See also

salt(1) salt-master(1) salt-minion(1)

Salt-syndic

The Salt syndic daemon, a special minion that passes through commands from a higher master

Synopsis

salt-syndic [ options ]

Description

The Salt syndic daemon, a special minion that passes through commands from a higher master.

Options

-h, --help: Print a usage message briefly summarizing these command-line options.
-d, --daemon: Run the Salt syndic as a daemon
--pid-file PIDFILE: Specify the location of the pidfile
--version: Show program's version number and exit
--versions-report: Show program's dependencies version number 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.

See also

salt(1) salt-master(1) salt-minion(1)

Release Notes And Upgrade Instructions

Salt 0.10.0 Release Notes

0.10.0 has arrived! This release comes with MANY bug fixes, and new capabilities which greatly enhance performance and reliability. This release is primarily a bug fix release with many new tests and many repaired bugs. This release also introduces a few new key features which were brought in primarily to repair bugs and some limitations found in some of the components of the original architecture.

Major Features

Event System

The Salt Master now comes equipped with a new event system. This event system has replaced some of the back end of the Salt client and offers the beginning of a system which will make plugging external applications into Salt. The event system relies on a local zeromq publish socket and other processes can connect to this socket and listen for events. The new events can be easily managed via Salt's event library.

Unprivileged User Updates

Some enhancements have been added to Salt for running as a user other than root. These new additions should make switching the user that the Salt Master is running as very painless, simply change the user option in the master configuration and restart the master, Salt will take care of all of the particulars for you.

Peer Runner Execution

Salt has long had the peer communication system used to allow minions to send commands via the salt master. 0.10.0 adds a new capability here, now the master can be configured to allow for minions to execute Salt runners via the peer_run option in the salt master configuration.

YAML Parsing Updates

In the past the YAML parser for sls files would return the incorrect numbers when the file mode was set with a preceding 0. The yaml parser used in Salt has been modified to no longer convert these number into octal but to keep them as the correct value so that sls files can be a little cleaner to write.

State Call Data Files

It was requested that the minion keep a local cache of the most recent executed state run. This has been added and now with state runs the data is stored in a msgpack file in the minion's cachedir.

Turning Off the Job Cache

A new option has been added to the master configuration file. In previous releases the Salt client would look over the Salt job cache to read in the minion return data. With the addition of the event system the Salt client can now watch for events directly from the master worker processes. This means that the job cache is no longer a hard requirement. Keep in mind though, that turning off the job cache means that historic job execution data cannot be retrieved.

Test Updates

Minion Swarms Are Faster

To continue our efforts with testing Salt's ability to scale the minionswarm script has been updated. The minionswarm can now start up minions much faster than it could before and comes with a new feature allowing modules to be disabled, thus lowering the minion's footprint when making a swarm. These new updates have allows us to test # python minionswarm.py -m 20 --master salt-master

Many Fixes

To get a good idea for the number of bugfixes this release offers take a look at the closed tickets for 0.10.0, this is a very substantial update: https://github.com/saltstack/salt/issues?milestone=12&state=closed

Master and Minion Stability Fixes

As Salt deployments grow new ways to break Salt are discovered. 0.10.0 comes with a number of fixes for the minions and master greatly improving Salt stability.

Salt 0.10.2 Release Notes

0.10.2 is out! This release comes with enhancements to the pillar interface, cleaner ways to access the salt-call capabilities in the API, minion data caching and the event system has been added to salt minions. There have also been updates to the zeromq functions, many more tests (thanks to sponsors, the code sprint and many contributors) and a swath of bug fixes.

Major Features

Ext Pillar Modules

The ranks of available Salt modules directories sees a new member in 0.10.2. With the popularity of pillar a higher demand has arisen for ext_pillar interfaces to be more like regular Salt module additions. Now ext_pillar interfaces can be added in the same way as other modules, just drop it into the pillar directory in the salt source.

Minion Events

In 0.10.0 an event system was added to the Salt master. 0.10.2 adds the event system to the minions as well. Now event can be published on a local minion as well. The minions can also send events back up to the master. This means that Salt is able to communicate individual events from the minions back up to the Master which are not associated with command.

Minion Data Caching

When pillar was introduced the landscape for available data was greatly enhanced. The minion's began sending grain data back to the master on a regular basis.
The new config option on the master called minion_data_cache instructs the Salt master to maintain a cache of the minion's grains and pillar data in the cachedir. This option is turned off by default to avoid hitting the disk more, but when enabled the cache is used to make grain matching from the salt command more powerful, since the minions that will match can be pre determined.

Backup Files

By default all files replaced by the file.managed and file.recurse states we simply deleted. 0.10.2 adds a new option. By setting the backup option to minion the files are backed up before they are replaced.
The backed up files are located in the cachedir under the file_backup directory. On a default system this will be at: /var/cache/salt/file_backup

Configuration files

salt-master and salt-minion automatically load additional configuration files from master.d/*.conf respective minion.d/*.conf where master.d/minion.d is a directory in the same directory as the main configuration file.

Salt Key Verification

A number of users complained that they had inadvertently deleted the wrong salt authentication keys. 0.10.2 now displays what keys are going to be deleted and verifies that they are the keys that are intended for deletion.

Key auto-signing

If autosign_file is specified in the configuration file incoming keys will be compared to the list of keynames in autosign_file. Regular expressions as well as globbing is supported.
The file must only be writable by the user otherwise the file will be ignored. To relax the permission and allow group write access set the permissive_pki_access option.

Module changes

Improved OpenBSD support

New modules for managing services and packages were provided by Joshua Elsasser to further improve the support for OpenBSD. Existing modules like the disk module were also improved to support OpenBSD.

SQL Modules

The MySQL and Postgres modules have both received a number of additions thanks to the work of Avi Marcus and Roman Imankulov.

ZFS Support on FreeBSD

A new ZFS module has been added by Kurtis Velarde for FreeBSD supporting various ZFS operations like creating, extending or removing zpools.

Augeas

A new Augeas module by Ulrich Dangel for editing and verifying config files.

Native Debian Service module

The support for the Debian was further improved with an new service module for Debian by Ahmad Khayyat supporting disable and enable.

Cassandra

Cassandra support has been added by Adam Garside. Currently only status and diagnostic information are supported.

Networking

The networking support for RHEL has been improved and supports bonding support as well as zeroconf configuration.

Monit

Basic monit support by Kurtis Velarde to control services via monit.

nzbget

Basic support for controlling nzbget by Joseph Hall

Bluetooth

Baisc bluez support for managing and controlling Bluetooth devices. Supports scanning as well as pairing/unpairing by Joseph Hall.

Test Updates

Consistency Testing

Another testing script has been added. A bug was found in pillar when many minions generated pillar data at the same time. The new consist.py script is the tests directory was created to reproduce bugs where data should always be consistent.

Many Fixes

To get a good idea for the number of bugfixes this release offers take a look at the closed tickets for 0.10.2, this is a very substantial update: https://github.com/saltstack/salt/issues?milestone=24&page=1&state=closed

Master and Minion Stability Fixes

As Salt deployments grow new ways to break Salt are discovered. 0.10.2 comes with a number of fixes for the minions and master greatly improving Salt stability.

Salt 0.10.3 Release Notes

The latest taste of Salt has come, this release has many fixes and feature additions. Modifications have been made to make ZeroMQ connections more reliable, the beginning of the ACL system is in place, a new command line parsing system has been added, dynamic module distribution has become more environment aware, the new master_finger option and many more!

Major Features

ACL System

The new ACL system has been introduced. The ACL system allows for system users other than root to execute salt commands. Users can be allowed to execute specific commands in the same way that minions are opened up to the peer system.
The configuration value to open up the ACL system is called client_acl and is configured like so:
client_acl: fred: - test..* - pkg.list_pkgs
Where fred is allowed access to functions in the test module and to the pkg.list_pkgs function.

Master Finger Option

The master_finger option has been added to improve the security of minion provisioning. The master_finger option allows for the fingerprint of the master public key to be set in the configuration file to double verify that the master is valid. This option was added in response to a motivation to pre authenticate the master when provisioning new minions to help prevent man in the middle attacks in some situations.

Salt Key Fingerprint Generation

The ability to generate fingerprints of keys used by Salt has been added to salt-key. The new option finger accepts the name of the key to generate and display a fingerprint for.
salt-key -F master
Will display the fingerprints for the master public and private keys.

Parsing System

Pedro Algavio, aka s0undt3ch, has added a substantial update to the command line parsing system that makes the help message output much cleaner and easier to search through. Salt parsers now have --versions-report besides usual --version info which you can provide when reporting any issues found.

Key Generation

We have reduced the requirements needed for salt-key to generate minion keys. You're no longer required to have salt configured and it's common directories created just to generate keys. This might prove useful if you're batch creating keys to pre-load on minions.

Startup States

A few configuration options have been added which allow for states to be run when the minion daemon starts. This can be a great advantage when deploying with Salt because the minion can apply states right when it first runs. To use startup states set the startup_states configuration option on the minion to highstate.

New Exclude Declaration

Some users have asked about adding the ability to ensure that other sls files or ids are excluded from a state run. The exclude statement will delete all of the data loaded from the specified sls file or will delete the specified id: exclude: - sls: http - id: /etc/vimrc

Max Open Files

While we're currently unable to properly handle ZeroMQ's abort signals when the max open files is reached, due to the way that's handled on ZeroMQ's, we have minimized the chances of this happening without at least warning the user.

More State Output Options

Some major changes have been made to the state output system. In the past state return data was printed in a very verbose fashion and only states that failed or made changes were printed by default. Now two options can be passed to the master and minion configuration files to change the behavior of the state output. State output can be set to verbose (default) or non-verbose with the state_verbose option:
state_verbose: False
It is noteworthy that the state_verbose option used to be set to False by default but has been changed to True by default in 0.10.3 due to many requests for the change.
Te next option to be aware of new and called state_output. This option allows for the state output to be set to full (default) or terse.
The full output is the standard state output, but the new terse output will print only one line per state making the output much easier to follow when executing a large state system.
state_output: terse

state.file.append Improvements

The salt state file.append() tries not to append existing text. Previously the matching check was being made line by line. While this kind of check might be enough for most cases, if the text being appended was multi-line, the check would not work properly. This issue is now properly handled, the match is done as a whole ignoring any white space addition or removal except inside commas. For those thinking that, in order to properly match over multiple lines, salt will load the whole file into memory, that's not true. For most cases this is not important but an erroneous order to read a 4GB file, if not properly handled, like salt does, could make salt chew that amount of memory. Salt has a buffered file reader which will keep in memory a maximum of 256KB and iterates over the file in chunks of 32KB to test for the match, more than enough, if not, explain your usage on a ticket. With this change, also salt.modules.file.contains(), salt.modules.file.contains_regex(), salt.modules.file.contains_glob() and salt.utils.find now do the searching and/or matching using the buffered chunks approach explained above. Two new keyword arguments were also added, makedirs and source. The first, makedirs will create the necessary directories in order to append to the specified file, of course, it only applies if we're trying to append to a non-existing file on a non-existing directory: /tmp/salttest/file-append-makedirs: file.append: text: foo makedirs: True The second, source, allows one to append the contents of a file instead of specifying the text. /tmp/salttest/file-append-source: file.append: - source: salt://testfile

Security Fix

A timing vulnerability was uncovered in the code which decrypts the AES messages sent over the network. This has been fixed and upgrading is strongly recommended.

Salt 0.10.4 Release Notes

Salt 0.10.4 is a monumental release for the Salt team, with two new module systems, many additions to allow granular access to Salt, improved platform support and much more. This release is also exciting because we have been able to shorten the release cycle back to under a month. We are working hard to keep up the aggressive pace and look forward to having releases happen more frequently! This release also includes a serious security fix and all users are very strongly recommended to upgrade. As usual, upgrade the master first, and then the minion to ensure that the process is smooth.

Major Features

External Authentication System

The new external authentication system allows for Salt to pass through authentication to any authentication system to determine if a user has permission to execute a Salt command. The Unix PAM system is the first supported system with more to come! The external authentication system allows for specific users to be granted access to execute specific functions on specific minions. Access is configured in the master configuration file, and uses the new access control system: external_auth: pam: thatch: - 'web*': - test.* - network.* The configuration above allows the user thatch to execute functions in the test and network modules on minions that match the web* target.

Access Control System

All Salt systems can now be configured to grant access to non-administrative users in a granular way. The old configuration continues to work. Specific functions can be opened up to specific minions from specific users in the case of external auth and client acls, and for specific minions in the case of the peer system. Access controls are configured like this: client_acl: fred: - web\*: - pkg.list_pkgs - test.* - apache.*

Target by Network

A new matcher has been added to the system which allows for minions to be targeted by network. This new matcher can be called with the -S flag on the command line and is available in all places that the matcher system is available. Using it is simple: $ salt -S '192.168.1.0/24' test.ping $ salt -S '192.168.1.100' test.ping

Nodegroup Nesting

Previously a nodegroup was limited by not being able to include another nodegroup, this restraint has been lifted and now nodegroups will be expanded within other nodegroups with the N@ classifier.

Salt Key Delete by Glob

The ability to delete minion keys by glob has been added to salt-key. To delete all minion keys whose minion name starts with 'web':
$ salt-key -d 'web*'

Master Tops System

The external_nodes system has been upgraded to allow for modular subsystems to be used to generate the top file data for a highstate run. The external_nodes option still works but will be deprecated in the future in favor of the new master_tops option. Example of using master_tops: master_tops: ext_nodes: cobbler-external-nodes

Next Level Solaris Support

A lot of work has been put into improved Solaris support by Romeo Theriault. Packaging modules (pkgadd/pkgrm and pkgutil) and states, cron support and user and group management have all been added and improved upon. These additions along with SMF (Service Management Facility) service support and improved Solaris grain detection in 0.10.3 add up to Salt becoming a great tool to manage Solaris servers with.

Security

A vulnerability in the security handshake was found and has been repaired, old minions should be able to connect to a new master, so as usual, the master should be updated first and then the minions.

Pillar Updates

The pillar communication has been updated to add some extra levels of verification so that the intended minion is the only one allowed to gather the data. Once all minions and the master are updated to salt 0.10.4 please activate pillar 2 by changing the pillar_version in the master config to 2. This will be set to 2 by default in a future release.

Salt 0.10.5 Release Notes

Salt 0.10.5 is ready, and comes with some great new features. A few more interfaces have been modularized, like the outputter system. The job cache system has been made more powerful and can now store and retrieve jobs archived in external databases. The returner system has been extended to allow minions to easily retrieve data from a returner interface. As usual, this is an exciting release, with many noteworthy additions!

Major Features

External Job Cache

The external job cache is a system which allows for a returner interface to also act as a job cache. This system is intended to allow users to store job information in a central location for longer periods of time and to make the act of looking up information from jobs executed on other minions easier. Currently the external job cache is supported via the mongo and redis returners: ext_job_cache: redis redis.host: salt Once the external job cache is turned on the new ret module can be used on the minions to retrieve return information from the job cache. This can be a great way for minions to respond and react to other minions.

OpenStack Additions

OpenStack integration with Salt has been moving forward at a blistering pace. The new nova, glance and keystone modules represent the beginning of ongoing OpenStack integration. The Salt team has had many conversations with core OpenStack developers and is working on linking to OpenStack in powerful new ways.

Wheel System

A new API was added to the Salt Master which allows the master to be managed via an external API. This new system allows Salt API to easily hook into the Salt Master and manage configs, modify the state tree, manage the pillar and more. The main motivation for the wheel system is to enable features needed in the upcoming web ui so users can manage the master just as easily as they manage minions. The wheel system has also been hooked into the external auth system. This allows specific users to have granular access to manage components of the Salt Master.

Render Pipes

Jack Kuan has added a substantial new feature. The render pipes system allows Salt to treat the render system like unix pipes. This new system enables sls files to be passed through specific render engines. While the default renderer is still recommended, different engines can now be more easily merged. So to pipe the output of mako used in YAML use this shebang line: #!mako|yaml

Salt Key Overhaul

The Salt Key system was originally developed as only a cli interface, but as time went on it was pressed into becoming a clumsy API. This release marks a complete overhaul of Salt Key. Salt Key has been rewritten to function purely from an api and to use the outputter system. The benefit here is that the outputter system works much more cleanly with Salt Key now, and the internals of Salt Key can be used much more cleanly.

Modular Outputters

The outputter system is now loaded in a modular way. This means that output systems can be more easily added by dropping a python file down on the master that contains the function output.

Gzip from Fileserver

Gzip compression has been added as an option to the cp.get_file and cp.get_dir commands. This will make file transfers more efficient and faster, especially over slower network links.

Unified Module Configuration

In past releases of Salt, the minions needed to be configured for certain modules to function. This was difficult because it required pre-configuring the minions. 0.10.5 changes this by making all module configs on minions search the master config file for values. Now if a single database server is needed, then it can be defined in the master config and all minions will become aware of the configuration value.

Salt Call Enhancements

The salt-call command has been updated in a few ways. Now, salt-call can take the --return option to send the data to a returner. Also, salt-call now reports executions in the minion proc system, this allows the master to be aware of the operation salt-call is running.

Death to pub_refresh and sub_timeout

The old configuration values pub_refresh and sub_timeout have been removed. These options were in place to alleviate problems found in earlier versions of ZeroMQ which have since been fixed. The continued use of these options has proven to cause problems with message passing and have been completely removed.

Git Revision Versions

When running Salt directly from git (for testing or development, of course) it has been difficult to know exactly what code is being executed. The new versioning system will detect the git revision when building and how many commits have been made since the last release. A release from git will look like this: 0.10.4-736-gec74d69

Svn Module Addition

Anthony Cornehl (twinshadow) contributed a module that adds Subversion support to Salt. This great addition helps round out Salt's VCS support.

Noteworthy Changes

Arch Linux Defaults to Systemd

Arch Linux recently changed to use systemd by default and discontinued support for init scripts. Salt has followed suit and defaults to systemd now for managing services in Arch.

Salt, Salt Cloud and Openstack

With the releases of Salt 0.10.5 and Salt Cloud 0.8.2, OpenStack becomes the first (non-OS) piece of software to include support both on the user level (with Salt Cloud) and the admin level (with Salt). We are excited to continue to extend support of other platforms at this level.

Salt 0.11.0 Release Notes

Salt 0.11.0 is here, with some highly sought after and exciting features. These features include the new overstate system, the reactor system, a new state run scope component called __context__, the beginning of the search system (still needs a great deal of work), multiple package states, the MySQL returner and a better system to arbitrarily reference outputters. It is also noteworthy that we are changing how we mark release numbers. For the life of the project we have been pushing every release with features and fixes as point releases. We will now be releasing point releases for only bug fixes on a more regular basis and major feature releases on a slightly less regular basis. This means that the next release will be a bugfix only release with a version number of 0.11.1. The next feature release will be named 0.12.0 and will mark the end of life for the 0.11 series.

Major Features

OverState

The overstate system is a simple way to manage rolling state executions across many minions. The overstate allows for a state to depend on the successful completion of another state.

Reactor System

The new reactor system allows for a reactive logic engine to be created which can respond to events within a salted environment. The reactor system uses sls files to match events fired on the master with actions, enabling Salt to react to problems in an infrastructure. Your load-balanced group of webservers is under extra load? Spin up a new vm and add it to the group. Your fileserver is filling up? Send a notification to your sysadmin on call. The possibilities are endless!

Module Context

A new component has been added to the module loader system. The module context is a data structure that can hold objects for a given scope within the module. This allows for components that are initialized to be stored in a persistent context which can greatly speed up ongoing connections. Right now the best example can be found in the cp execution module.

Multiple Package Management

A long desired feature has been added to package management. By definition Salt States have always installed packages one at a time. On most platforms this is not the fastest way to install packages. Erik Johnson, aka archtaku, has modified the package modules for many providers and added new capabilities to install groups of packages. These package groups can be defined as a list of packages available in repository servers: python_pkgs: pkg.installed: - pkgs: - python-mako - whoosh - python-git or specify based on the location of specific packages: python_pkgs: pkg.installed: - sources: - python-mako: http://some-rpms.org/python-mako.rpm - whoosh: salt://whoosh/whoosh.rpm - python-git: ftp://companyserver.net/python-git.rpm

Search System

The bones to the search system have been added. This is a very basic interface that allows for search backends to be added as search modules. The first supported search module is the whoosh search backend. Right now only the basic paths for the search system are in place, making this very experimental. Further development will involve improving the search routines and index routines for whoosh and other search backends. The search system has been made to allow for searching through all of the state and pillar files, configuration files and all return data from minion executions.

Notable Changes

All previous versions of Salt have shared many directories between the master and minion. The default locations for keys, cached data and sockets has been shared by master and minion. This has created serious problems with running a master and a minion on the same systems. 0.11.0 changes the defaults to be separate directories. Salt will also attempt to migrate all of the old key data into the correct new directories, but if it is not successful it may need to be done manually. If your keys exhibit issues after updating make sure that they have been moved from /etc/salt/pki to /etc/salt/pki/{master,minion}. The old setup will look like this: /etc/salt/pki |-- master.pem |-- master.pub |-- minions | `-- ragnarok.saltstack.net |-- minions_pre |-- minion.pem |-- minion.pub |-- minion_master.pub |-- minions_pre `-- minions_rejected With the accepted minion keys in /etc/salt/pki/minions, the new setup places the accepted minion keys in /etc/salt/pki/master/minions /etc/salt/pki |-- master | |-- master.pem | |-- master.pub | |-- minions | | `-- ragnarok.saltstack.net | |-- minions_pre | `-- minions_rejected |-- minion | |-- minion.pem | |-- minion.pub | `-- minion_master.pub

Salt 0.12.0 Release Notes

Another feature release of Salt is here! Some exciting additions are included with more ways to make salt modular and even easier management of the salt file server.

Major Features

Modular Fileserver Backend

The new modular fileserver backend allows for any external system to be used as a salt file server. The main benefit here is that it is now possible to tell the master to directly use a git remote location, or many git remote locations, automatically mapping git branches and tags to salt environments.

Windows is First Class!

A new Salt Windows installer is now available! Much work has been put in to improve Windows support. With this much easier method of getting Salt on your Windows machines, we hope even more development and progress will occur. Please file bug reports on the Salt github repo issue tracker so we can continue improving. One thing that is missing on Windows that Salt uses extensively is a software package manager and a software package repository. The Salt pkg state allows sys admins to install software across their infrastructure and across operating systems. Software on Windows can now be managed in the same way. The SaltStack team built a package manager that interfaces with the standard Salt pkg module to allow for installing and removing software on Windows. In addition, a software package repository has been built on top of the Salt fileserver. A small yaml file provides the information necessary for the package manager to install and remove software. An interesting feature of the new Salt Windows software package repository is that one or more remote git repositories can supplement the master's local repository. The repository can point to software on the master's fileserver or on an http, https, or ftp server.

New Default Outputter

Salt displays data to the terminal via the outputter system. For a long time the default outputter for Salt has been the python pretty print library. While this has been a generally reasonable outputter, it did have many failings. The new default outputter is called "nested", it recursively scans return data structures and prints them out cleanly. If the result of the new nested outputter is not desired any other outputter can be used via the --out option, or the output option can be set in the master and minion configs to change the default outputter.

Internal Scheduler

The internal Salt scheduler is a new capability which allows for functions to be executed at given intervals on the minion, and for runners to be executed at given intervals on the master. The scheduler allows for sequences such as executing state runs (locally on the minion or remotely via an overstate) or continually gathering system data to be run at given intervals. The configuration is simple, add the schedule option to the master or minion config and specify jobs to run, this in the master config will execute the state.over runner every 60 minutes: schedule: overstate: function: state.over minutes: 60 This example for the minion configuration will execute a highstate every 30 minutes: schedule: highstate: function: state.highstate minutes: 30

Optional DSL for SLS Formulas

Jack Kuan, our renderer expert, has created something that is astonishing. Salt, now comes with an optional Python based DSL, this is a very powerful interface that makes writing SLS files in pure python easier than it was with the raw py renderer. As usual this can be used with the renderer shebang line, so a single sls can be written with the DSL if pure python power is needed while keeping other sls files simple with YAML.

Set Grains Remotely

A new execution function and state module have been added that allows for grains to be set on the minion. Now grains can be set via a remote execution or via states. Use the grains.present state or the grains.setval execution functions.

Gentoo Additions

Major additions to Gentoo specific components have been made. The encompasses executions modules and states ranging from supporting the make.conf file to tools like layman.

Salt 0.13.0 Release Notes

The lucky number 13 has turned the corner! From cli notifications when quitting a salt command, to substantial improvements on Windows, Salt 0.13.0 has arrived!

Major Features

Improved file.recuse Performance

The file.recurse system has been deployed and used in a vast array of situations. Fixes to the file state and module have led towards opening up new ways of running file.recurse to make it faster. Now the file.recurse state will download fewer files and will run substantially faster.

Windows Improvements

Minion stability on Windows has improved. Many file operations, including file.recurse, have been fixed and improved. The network module works better, to include network.interfaces. Both 32bit and 64bit installers are now available.

Nodegroup Targeting in Peer System

In the past, nodegroups were not available for targeting via the peer system. This has been fixed, allowing the new nodegroup expr_form argument for the publish.publish function:: salt-call publish.publish group1 test.ping expr_form=nodegroup

Blacklist Additions

Additions allowing more granular blacklisting are available in 0.13.0. The ability to blacklist users and functions in client_acl have been added, as well as the ability to exclude state formulas from the command line.

Command Line Pillar Embedding

Pillar data can now be embedded on the command line when calling state.sls and state.highstate. This allows for on the fly changes or settings to pillar and makes parameterizing state formulas even easier. This is done via the keyword argument:: salt * state.highstate pillar='{"cheese": "spam"}'
The above example will extend the existing pillar to hold the cheese key with a value of spam. If the cheese key is already specified in the minion's pillar then it will be overwritten.

CLI Notifications

In the past hitting ctrl-C and quitting from the salt command would just drop to a shell prompt, this caused confusion with users who expected the remote executions to also quit. Now a message is displayed showing what command can be used to track the execution and what the job id is for the execution.

Noteworthy Changes

The configuration subsystem in Salt has been overhauled to make the opts dict used by Salt applications more portable, the problem is that this is an incompatible change with salt-cloud, and salt-cloud will need to be updated to the latest git to work with Salt 0.13.0. Salt Cloud 0.8.5 will also require Salt 0.13.0 or later to function.
The Salt Stack team is sorry for the inconvenience here, we work hard to make sure these sorts of things do not happen, but sometimes hard changes get in.

Salt 0.6.0 release notes

The Salt remote execution manager has reached initial functionality! Salt is a management application which can be used to execute commands on remote sets of servers. The whole idea behind Salt is to create a system where a group of servers can be remotely controlled from a single master, not only can commands be executed on remote systems, but salt can also be used to gather information about your server environment. Unlike similar systems, like Func and MCollective, Salt is extremely simple to setup and use, the entire application is contained in a single package, and the master and minion daemons require no running dependencies in the way that Func requires Certmaster and MCollective requires activeMQ. Salt also manages authentication and encryption. Rather than using ssl for encryption, salt manages encryption on a payload level, so the data sent across the network is encrypted with fast aes encryption, and authentication uses RSA keys. This means that Salt is fast, secure, and very efficient. Messaging in Salt is executed with zeromq, so the message passing interface is built into salt and does not require an external MQ server. This also adds speed to Salt since there is no additional bloat on the networking layer, and zeromq has already proven itself as a very fast networking system. The remote execution in Salt is "Lazy Execution", in that once the command is sent the requesting network connection is closed. This makes it easier to detach the execution from the calling process on the master, it also means that replies are cached, so that information gathered from historic commands can be queried in the future. Salt also allows users to make execution modules in Python. Writers of these modules should also be pleased to know that they have access to the impressive information gathered from PuppetLabs' Facter application, making Salt module more flexible. In the future I hope to also allow Salt to group servers based on facter information as well. All in all Salt is fast, efficient and clean, can be used from a simple command line client or through an api, uses message queue technology to make network execution extremely fast, and encryption is handled in a very fast and efficient manner. Salt is also VERY easy to use and VERY easy to extend. You can find the source code for Salt on my github page, I have also set up a few wiki pages explaining how to use and set up Salt. If you are using Arch Linux there is a package available in the Arch Linux AUR. Salt 0.6.0 Source: https://github.com/downloads/saltstack/salt/salt-0.6.0.tar.gz Github page: https://github.com/saltstack/salt Wiki: https://github.com/saltstack/salt/wiki Arch Linux Package: https://aur.archlinux.org/packages.php?ID=47512 I am very open to contributions, for instance I need packages for more Linux distributions as well as BSD packages and testers. Give Salt a try, this is the initial release and is not a 1.0 quality release, but it has been working well for me! I am eager to get your feedback!

Salt 0.7.0 release notes

I am pleased to announce the release of Salt 0.7.0! This release marks what is the first stable release of salt, 0.7.0 should be suitable for general use. 0.7.0 Brings the following new features to Salt:
• Integration with facter data from puppet labs • Allow for matching minions from the salt client via facter information • Minion job threading, many jobs can be executed from the master at once • Preview of master clustering support - Still experimental • Introduce new minion modules for stats, virtualization, service management and more • Add extensive logging to the master and minion daemons • Add sys.reload_functions for dynamic function reloading • Greatly improve authentication • Introduce the saltkey command for managing public keys • Begin backend development preparatory to introducing butter • Addition of man pages for the core commands • Extended and cleaned configuration
0.7.0 Fixes the following major bugs:
• Fix crash in minions when matching failed • Fix configuration file lookups for the local client • Repair communication bugs in encryption • Numerous fixes in the minion modules
The next release of Salt should see the following features:
• Stabilize the cluster support • Introduce a remote client for salt command tiers • salt-ftp system for distributed file copies • Initial support for "butter"
Coming up next is a higher level management framework for salt called Butter. I want salt to stay as a simple and effective communication framework, and allow for more complicated executions to be managed via Butter. Right now Butter is being developed to act as a cloud controller using salt as the communication layer, but features like system monitoring and advanced configuration control (a puppet manager) are also in the pipe. Special thanks to Joseph Hall for the status and network modules, and thanks to Matthias Teege for tracking down some configuration bugs! Salt can be downloaded from the following locations; Source Tarball: https://github.com/downloads/saltstack/salt/salt-0.7.0.tar.gz Arch Linux Package: https://aur.archlinux.org/packages.php?ID=47512 Please enjoy the latest Salt release!

Salt 0.8.0 release notes

Salt 0.8.0 is ready for general consumption! The source tarball is available on github for download: https://github.com/downloads/saltstack/salt/salt-0.8.0.tar.gz A lot of work has gone into salt since the last release just 2 weeks ago, and salt has improved a great deal. A swath of new features are here along with performance and threading improvements! The main new features of salt 0.8.0 are: Salt-cp Cython minion modules Dynamic returners Faster return handling Lowered required Python version to 2.6 Advanced minion threading Configurable minion modules

Salt-cp -

The salt-cp command introduces the ability to copy simple files via salt to targeted servers. Using salt-cp is very simple, just call salt-cp with a target specification, the source file(s) and where to copy the files on the minions. For instance:
# salt-cp '*' /etc/hosts /etc/hosts
Will copy the local /etc/hosts file to all of the minions.
Salt-cp is very young, in the future more advanced features will be added, and the functionality will much more closely resemble the cp command.

Cython minion modules -

Cython is an amazing tool used to compile Python modules down to c. This is arguably the fastest way to run Python code, and since pyzmq requires cython, adding support to salt for cython adds no new dependencies. Cython minion modules allow minion modules to be written in cython and therefore executed in compiled c. Simply write the salt module in cython and use the file extension ".pyx" and the minion module will be compiled when the minion is started. An example cython module is included in the main distribution called cytest.pyx: https://github.com/saltstack/salt/blob/develop/salt/modules/cytest.pyx

Dynamic Returners -

By default salt returns command data back to the salt master, but now salt can return command data to any system. This is enabled via the new returners modules feature for salt. The returners modules take the return data and sends it to a specific module. The returner modules work like minion modules, so any returner can be added to the minions. This means that a custom data returner can be added to communicate the return data so anything from MySQL, redis, mongodb and more! There are 2 simple stock returners in the returners directory: https://github.com/saltstack/salt/blob/develop/salt/returners The documentation on writing returners will be added to the wiki shortly, and returners can be written in pure Python, or in cython.

Configurable Minion Modules -

Minion modules may need to be configured, now the options passed to the minion configuration file can be accessed inside of the minion modules via the __opt__ dict. Information on how to use this simple addition has been added to the wiki: https://github.com/thatch45/salt/wiki/Writing-Salt-Modules The test module has an example of using the __opts__ dict, and how to set default options: https://github.com/saltstack/salt/blob/develop/salt/modules/test.py

Advanced Minion Threading:

In 0.7.0 the minion would block after receiving a command from the master, now the minion will spawn a thread or multiprocess. By default Python threads are used because for general use they have proved to be faster, but the minion can now be configured to use the Python multiprocessing module instead. Using multiprocessing will cause executions that are cpu bound or would otherwise exploit the negative aspects of the Python GIL to run faster and more reliably, but simple calls will still be faster with Python threading. The configuration option can be found in the minion configuration file: https://github.com/saltstack/salt/blob/develop/conf/minion Lowered Supported Python to 2.6 - The requirement for Python 2.7 has been removed to support Python 2.6. I have received requests to take the minimum Python version back to 2.4, but unfortunately this will not be possible, since the zeromq Python bindings do not support Python 2.4. Salt 0.8.0 is a very major update, it also changes the network protocol slightly which makes communication with older salt daemons impossible, your master and minions need to be upgraded together! I could use some help bringing salt to the people! Right now I only have packages for Arch Linux, Fedora 14 and Gentoo. We need packages for Debian and people willing to help test on more platforms. We also need help writing more minion modules and returner modules. If you want to contribute to salt please hop on the mailing list and send in patches, make a fork on github and send in pull requests! If you want to help but are not sure where you can, please email me directly or post tot he mailing list! I hope you enjoy salt, while it is not yet 1.0 salt is completely viable and usable! -Thomas S. Hatch

Salt 0.8.7 release notes

It has been a month since salt 0.8.0, and it has been a long month! But Salt is still coming along strong. 0.8.7 has a lot of changes and a lot of updates. This update makes Salt's ZeroMQ back end better, strips facter from the dependencies, and introduces interfaces to handle more capabilities. Many of the major updates are in the background, but the changes should shine through to the surface. A number of the new features are still a little thin, but the back end to support expansion is in place. I also recently gave a presentation to the Utah Python users group in Salt Lake City, the slides from this presentation are available here: https://github.com/downloads/saltstack/salt/Salt.pdf The video from this presentation will be available shortly. The major new features and changes in Salt 0.8.7 are:
• Revamp ZeroMQ topology on the master for better scalability • State enforcement • Dynamic state enforcement managers • Extract the module loader into salt.loader • Make Job ids more granular • Replace facter functionality with the new salt grains interface • Support for "virtual" salt
modules
• Introduce the salt-call command • Better debugging for minion modules
The new ZeroMQ topology allows for better scalability, this will be required by the need to execute massive file transfers to multiple machines in parallel and state management. The new ZeroMQ topology is available in the aforementioned presentation. 0.8.7 introduces the capability to declare states, this is similar to the capabilities of Puppet. States in salt are declared via state data structures. This system is very young, but the core feature set is available. Salt states work around rendering files which represent Salt high data. More on the Salt state system will be documented in the near future. The system for loading salt modules has been pulled out of the minion class to be a standalone module, this has enabled more dynamic loading of Salt modules and enables many of the updates in 0.8.7 - https://github.com/saltstack/salt/blob/develop/salt/loader.py Salt Job ids are now microsecond precise, this was needed to repair a race condition unveiled by the speed improvements in the new ZeroMQ topology. The new grains interface replaces the functionality of Facter, the idea behind grains differs from Facter in that the grains are only used for static system data, dynamic data needs to be derived from a call to a salt module. This makes grains much faster to use, since the grains data is generated when the minion starts. Virtual salt modules allows for a salt module to be presented as something other than its module name. The idea here is that based on information from the minion decisions about which module should be presented can be made. The best example is the pacman module. The pacman module will only load on Arch Linux minions, and will be called pkg. Similarly the yum module will be presented as pkg when the minion starts on a Fedora/RedHat system. The new salt-call command allows for minion modules to be executed from the minion. This means that on the minion a salt module can be executed, this is a great tool for testing Salt modules. The salt-call command can also be used to view the grains data. In previous releases when a minion module threw an exception very little data was returned to the master. Now the stack trace from the failure is returned making debugging of minion modules MUCH easier. Salt is nearing the goal of 1.0, where the core feature set and capability is complete! Salt 0.8.7 can be downloaded from github here: https://github.com/downloads/saltstack/salt/salt-0.8.7.tar.gz -Thomas S Hatch

Salt 0.8.8 release notes

Salt 0.8.8 is here! This release adds a great deal of code and some serious new features. The latest release can be downloaded here: https://github.com/downloads/saltstack/salt/salt-0.8.8.tar.gz Improved Documentation has been set up for salt using sphinx thanks to the efforts of Seth House. This new documentation system will act as the back end to the salt website which is still under heavy development. The new sphinx documentation system has also been used to greatly clean up the salt manpages. The salt 7 manpage in particular now contains extensive information which was previously only in the wiki. The new documentation can be found at: http://thatch45.github.com/salt-www/ We still have a lot to add, and when the domain is set up I will post another announcement. More additions have been made to the ZeroMQ setup, particularly in the realm of file transfers. Salt 0.8.8 introduces a built in, stateless, encrypted file server which allows salt minions to download files from the salt master using the same encryption system used for all other salt communications. The main motivation for the salt file server has been to facilitate the new salt state system. Much of the salt code has been cleaned up and a new cleaner logging system has been introduced thanks to the efforts of Pedro Algarvio. These additions will allow for much more flexible logging to be executed by salt, and fixed a great deal of my poor spelling in the salt docstrings! Pedro Algarvio has also cleaned up the api, making it easier to embed salt into another application. The biggest addition to salt found in 0.8.8 is the new state system. The salt module system has received a new front end which allows salt to be used as a configuration management system. The configuration management system allows for system configuration to be defined in data structures. The configuration management system, or as it is called in salt, the "salt state system" supports many of the features found in other configuration managers, but allows for system states to be written in a far simpler format, executes at blazing speeds, and operates via the salt minion matching system. The state system also operates within the normal scope of salt, and requires no additional configuration to use. The salt state system can enforce the following states with many more to come: Packages Files Services Executing commands Hosts The system used to define the salt states is based on a data structure, the data structure used to define the salt states has been made to be as easy to use as possible. The data structure is defined by default using a yaml file rendered via a jinja template. This means that the state definition language supports all of the data structures that yaml supports, and all of the programming constructs and logic that jinja supports. If the user does not like yaml or jinja the states can be defined in yaml-mako, json-jinja, or json-mako. The system used to render the states is completely dynamic, and any rendering system can be added to the capabilities of Salt, this means that a rendering system that renders xml data in a cheetah template, or whatever you can imagine, can be easily added to the capabilities of salt. The salt state system also supports isolated environments, as well as matching code from several environments to a single salt minion. The feature base for Salt has grown quite a bit since my last serious documentation push. As we approach 0.9.0 the goals are becoming very clear, and the documentation needs a lot of work. The main goals for 0.9.0 are to further refine the state system, fix any bugs we find, get Salt running on as many platforms as we can, and get the documentation filled out. There is a lot more to come as Salt moves forward to encapsulate a much larger scope, while maintaining supreme usability and simplicity. If you would like a more complete overview of Salt please watch the Salt presentation: Flash Video: http://blip.tv/thomas-s-hatch/salt-0-8-7-presentation-5180182 OGV Video Download: http://blip.tv/file/get/Thatch45-Salt087Presentation416.ogv Slides: https://github.com/downloads/saltstack/salt/Salt.pdf -Thomas S Hatch

Salt 0.8.9 Release Notes

Salt 0.8.9 has finally arrived! Unfortunately this is much later than I had hoped to release 0.8.9, life has been very crazy over the last month. But despite challenges, Salt has moved forward! This release, as expected, adds few new features and many refinements. One of the most exciting aspect of this release is that the development community for salt has grown a great deal and much of the code is from contributors. Also, I have filled out the documentation a great deal. So information on States is properly documented, and much of the documentation that was out of date has been filled in.

Download!

The Salt source can be downloaded from the salt github site: https://github.com/downloads/saltstack/salt/salt-0.8.9.tar.gz Or from PiPy: http://pypi.python.org/packages/source/s/salt/salt-0.8.9.tar.gz Here s the md5sum: 7d5aca4633bc22f59045f59e82f43b56 For instructions on how to set up Salt please see the installation instructions.

New Features

Salt Run

A big feature is the addition of Salt run, the salt-run command allows for master side execution modules to be made that gather specific information or execute custom routines from the master.
Documentation for salt-run can be found here:
http://saltstack.org/ref/runners.html

Refined Outputters

One problem often complained about in salt was the fact that the output was so messy. Thanks to help from Jeff Schroeder a cleaner interface for the command output for the Salt cli has been made. This new interface makes adding new printout formats easy and additions to the capabilities of minion modules makes it possible to set the printout mode or outputter for functions in minion modules.

Cross Calling Salt Modules

Salt modules can now call each other, the __salt__ dict has been added to the predefined references in minion modules. This new feature is documented in the modules documentation:
http://saltstack.org/ref/modules/index.html

Watch Option Added to Salt State System

Now in Salt states you can set the watch option, this will allow watch enabled states to change based on a change in the other defined states. This is similar to subscribe and notify statements in puppet.

Root Dir Option

Travis Cline has added the ability to define the option root_dir which allows the salt minion to operate in a subdir. This is a strong move in supporting the minion running as an unprivileged user

Config Files Defined in Variables

Thanks again to Travis Cline, the master and minion configuration file locations can be defined in environment variables now.

New Modules

Quite a few new modules, states, returners and runners have been made.

New Minion Modules

apt

Support for apt-get has been added, this adds greatly improved Debian and Ubuntu support to Salt!

useradd and groupadd

Support for manipulating users and groups on Unix-like systems.

moosefs

Initial support for reporting on aspects of the distributed file system, MooseFS. For more information on MooseFS please see: http://moosefs.org Thanks to Joseph Hall for his work on MooseFS support.

mount

Manage mounts and the fstab.

puppet

Execute puppet on remote systems.

shadow

Manipulate and manage the user password file.

ssh

Interact with ssh keys.

New States

user and group

Support for managing users and groups in Salt States.

mount

Enforce mounts and the fstab.

New Returners

mongo_return

Send the return information to a mongodb server.

New Runners

manage

Display minions that are up or down.

Salt 0.9.0 Release Notes

Salt 0.9.0 is here. This is an exciting release, 0.9.0 includes the new network topology features allowing peer salt commands and masters of masters via the syndic interface. 0.9.0 also introduces many more modules, improvements to the api and improvements to the ZeroMQ systems.

Download!

The Salt source can be downloaded from the salt github site: https://github.com/downloads/saltstack/salt/salt-0.9.0.tar.gz Or from PiPy: http://pypi.python.org/packages/source/s/salt/salt-0.9.0.tar.gz Here is the md5sum: 9a925da04981e65a0f237f2e77ddab37 For instructions on how to set up Salt please see the installation instructions.

New Features

Salt Syndic

The new Syndic interface allows a master to be commanded via another higher level salt master. This is a powerful solution allowing a master control structure to exist, allowing salt to scale to much larger levels then before. http://saltstack.org/ref/syndic.html

Peer Communication

0.9.0 introduces the capability for a minion to call a publication on the master and receive the return from another set of minions. This allows salt to act as a communication channel between minions and as a general infrastructure message bus.
Peer communication is turned off by default but can be enabled via the peer option in the master configuration file. Documentation on the new peer interface can be found here:
http://saltstack.org/ref/peer.html

Easily Extensible API

The minion and master classes have been redesigned to allow for specialized minion and master servers to be easily created. An example on how this is done for the master can be found in the master.py salt module:
https://github.com/saltstack/salt/blob/develop/salt/master.py
The Master class extends the SMaster class and set up the main master server.
The minion functions can now also be easily added to another application via the SMinion class, this class can be found in the minion.py module:
https://github.com/saltstack/salt/blob/develop/salt/minion.py

Cleaner Key Management

This release changes some of the key naming to allow for multiple master keys to be held based on the type of minion gathering the master key. The -d option has also been added to the salt-key command allowing for easy removal of accepted public keys. The --gen-keys option is now available as well for salt-key, this allows for a salt specific RSA key pair to be easily generated from the command line.

Improved 0MQ Master Workers

The 0MQ worker system has been further refined to be faster and more robust. This new system has been able to handle a much larger load than the previous setup. The new system uses the ipc protocol in 0MQ instead of tcp.

New Modules

Quite a few new modules have been made.

New Minion Modules

apache

Work directly with apache servers, great for managing balanced web servers

cron

Read out the contents of a systems crontabs

mdadm

Module to manage raid devices in Linux, appears as the raid module

mysql

Gather simple data from MySQL databases

Extensive utilities for managing processes

publish

Used by the peer interface to allow minions to make publications

Salt 0.9.2 Release Notes

Salt 0.9.2 has arrived! 0.9.2 is primarily a bugfix release, the exciting component in 0.9.2 is greatly improved support for salt states. All of the salt states interfaces have been more thoroughly tested and the new salt-states git repo is growing with example of how to use states. This release introduces salt states for early developers and testers to start helping us clean up the states interface and make it ready for the world! 0.9.2 also fixes a number of bugs found on Python 2.6.

Download!

The Salt source can be downloaded from the salt github site: https://github.com/downloads/saltstack/salt/salt-0.9.2.tar.gz Or from PiPy: http://pypi.python.org/packages/source/s/salt/salt-0.9.2.tar.gz For instructions on how to set up Salt please see the installation instructions.

New Features

Salt-Call Additions

The salt-call command has received an overhaul, it now hooks into the outputter system so command output looks clean, and the logging system has been hooked into salt-call, so the -l option allows the logging output from salt minion functions to be displayed. The end result is that the salt-call command can execute the state system and return clean output: # salt-call state.highstate

State System Fixes

The state system has been tested and better refined. As of this release the state system is ready for early testers to start playing with. If you are interested in working with the state system please check out the (still very small) salt-states github repo: https://github.com/thatch45/salt-states This git repo is the active development branch for determining how a clean salt-state database should look and act. Since the salt state system is still very young a lot of help is still needed here. Please fork the salt-states repo and help us develop a truly large and scalable system for configuration management!

Notable Bug Fixes

Python 2.6 String Formatting

Python 2.6 does not support format strings without an index identifier, all of them have been repaired.

Cython Loading Disabled by Default

Cython loading requires a development tool chain to be installed on the minion, requiring this by default can cause problems for most Salt deployments. If Cython auto loading is desired it will need to be turned on in the minion config.

Salt 0.9.3 Release Notes

Salt 0.9.3 is finally arrived. This is another big step forward for Salt, new features range from proper FreeBSD support to fixing issues seen when attaching a minion to a master over the Internet. The biggest improvements in 0.9.3 though can be found in the state system, it has progressed from something ready for early testers to a system ready to compete with platforms such as Puppet and Chef. The backbone of the state system has been greatly refined and many new features are available.

Download!

The Salt source can be downloaded from the salt github site: https://github.com/downloads/saltstack/salt/salt-0.9.3.tar.gz Or from PiPy: http://pypi.python.org/packages/source/s/salt/salt-0.9.3.tar.gz For instructions on how to set up Salt please see the installation instructions.

New Features

WAN Support

Recently more people have been testing Salt minions connecting to Salt Masters over the Internet. It was found that Minions would commonly loose their connection to the master when working over the internet. The minions can now detect if the connection has been lost and reconnect to the master, making WAN connections much more reliable.

State System Fixes

Substantial testing has gone into the state system and it is ready for real world usage. A great deal has been added to the documentation for states and the modules and functions available to states have been cleanly documented. A number of State System bugs have also been founds and repaired, the output from the state system has also been refined to be extremely clear and concise. Error reporting has also been introduced, issues found in sls files will now be clearly reported when executing Salt States.

Extend Declaration

The Salt States have also gained the extend declaration. This declaration allows for states to be cleanly modified in a post environment. Simply said, if there is an apache.sls file that declares the apache service, then another sls can include apache and then extend it:
include: - apache extend: apache: service: - require: - pkg: mod_python mod_python: pkg: - installed
The notable behavior with the extend functionality is that it literally extends or overwrites a declaration set up in another sls module. This means that Salt will behave as though the modifications were made directly to the apache sls. This ensures that the apache service in this example is directly tied to all requirements.

Highstate Structure Specification

This release comes with a clear specification of the Highstate data structure that is used to declare Salt States. This specification explains everything that can be declared in the Salt SLS modules. The specification is extremely simple, and illustrates how Salt has been able to fulfill the requirements of a central configuration manager within a simple and easy to understand format and specification.

SheBang Renderer Switch

It came to our attention that having many renderers means that there may be a situation where more than one State Renderer should be available within a single State Tree. The method chosen to accomplish this was something already familiar to developers and systems administrators, a SheBang. The Python State Renderer displays this new capability.

Python State Renderer

Until now Salt States could only be declared in yaml or json using jinja or mako. A new, very powerful, renderer has been added, making it possible to write Salt States in pure Python: #!py def run(): ''' Install the python-mako package ''' return {'include': ['python'], 'python-mako': {'pkg': ['installed']}} This renderer is used by making a run function that returns the Highstate data structure. Any capabilities of Python can be used in pure Python sls modules. This example of a pure Python sls module is the same as this example in yaml: include: - python python-mako: pkg: - installed

FreeBSD Support

Additional support has been added for FreeBSD, this is Salt's first branch out of the Linux world and proves the viability of Salt on non-Linux platforms. Salt remote execution already worked on FreeBSD, and should work without issue on any Unix-like platform. But this support comes in the form of package management and user support, so Salt States also work on FreeBSD now. The new freebsdpkg module provides package management support for FreeBSD and the new pw_user and pw_group provide user and group management.

Module and State Additions

Cron Support

Support for managing the system crontab has been added, declaring a cron state can be done easily: date > /tmp/datestamp: cron: - present - user: fred - minute: 5 - hour: 3

File State Additions

The file state has been given a number of new features, primarily the directory, recurse, symlink and absent functions.

file.directory

Make sure that a directory exists and has the right permissions.

/srv/foo:
  file:
    - directory
    - user: root
    - group: root
    - mode: 1755

file.symlink

Make a symlink.

/var/lib/www:
  file:
    - symlink
    - target: /srv/www
    - force: True

file.recurse

The recurse state function will recursively download a directory on the master file server and place it on the minion. Any change in the files on the master will be pushed to the minion. The recurse function is very powerful and has been tested by pushing out the full Linux kernel source.

/opt/code:
  file:
    - recurse
    - source: salt://linux

file.absent

Make sure that the file is not on the system, recursively delets directories, files and symlinks.

/etc/httpd/conf.d/somebogusfile.conf:
  file:
    - absent

Sysctl Module and State

The sysctl module and state allows for sysctl components in the kernel to be managed easily. the sysctl module contains the following functions:
sysctl.show: Return a list of sysctl parameters for this minion
sysctl.get: Return a single sysctl parameter for this minion
sysctl.assign: Assign a single sysctl parameter for this minion
sysctl.persist: Assign and persist a simple sysctl parameter for this minion
The sysctl state allows for sysctl parameters to be assigned: vm.swappiness: sysctl: - present - value: 20

Kernel Module Management

A module for managing Linux kernel modules has been added. The new functions are as follows:
kmod.available: Return a list of all available kernel modules
kmod.check_available: Check to see if the specified kernel module is available
kmod.lsmod: Return a dict containing information about currently loaded modules
kmod.load: Load the specified kernel module
kmod.remove: Unload the specified kernel module
The kmod state can enforce modules be either present or absent: kvm_intel: kmod: - present

Ssh Authorized Keys

The ssh_auth state can distribute ssh authorized keys out to minions. Ssh authorized keys can be present or absent. AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyYvlRBsJdDOo49CNfhlWHWXQRqul6rwL4KIuPrhY7hBw0tV7UNC7J9IZRNO4iGod9C+OYutuWGJ2x5YNf7P4uGhH9AhBQGQ4LKOLxhDyT1OrDKXVFw3wgY3rHiJYAbd1PXNuclJHOKL27QZCRFjWSEaSrUOoczvAAAAFQD9d4jp2dCJSIseSkk4Lez3LqFcqQAAAIAmovHIVSrbLbXAXQE8eyPoL9x5C+x2GRpEcA7AeMH6bGx/xw6NtnQZVMcmZIre5Elrw3OKgxcDNomjYFNHuOYaQLBBMosyO++tJe1KTAr3A2zGj2xbWO9JhEzu8xvSdF8jRu0N5SRXPpzSyU4o1WGIPLVZSeSq1VFTHRT4lXB7PQAAAIBXUz6ZO0bregF5xtJRuxUN583HlfQkXvxLqHAGY8WSEVlTnuG/x75wolBDbVzeTlxWxgxhafj7P6Ncdv25Wz9wvc6ko/puww0b3rcLNqK+XCNJlsM/7lB8Q26iK5mRZzNsGeGwGTyzNIMBekGYQ5MRdIcPv5dBIP/1M6fQDEsAXQ==: ssh_auth: - present - user: frank - enc: dsa - comment: 'Frank's key'

Salt 0.9.4 Release Notes

Salt 0.9.4 has arrived. This is a critical update that repairs a number of key bugs found in 0.9.3. But this update is not without feature additions as well! 0.9.4 adds support for Gentoo portage to the pkg module and state system. Also there are 2 major new state additions, the failhard option and the ability to set up finite state ordering with the order option.
This release also sees our largest increase in community contributions. These contributors have and continue to be the life blood of the Salt project, and the team continues to grow. I want to put out a big thanks to our new and existing contributors.

Download!

The Salt source can be downloaded from the salt github site: https://github.com/downloads/saltstack/salt/salt-0.9.4.tar.gz Or from PiPy: http://pypi.python.org/packages/source/s/salt/salt-0.9.4.tar.gz For instructions on how to set up Salt please see the installation instructions.

New Features

Failhard State Option

Normally, when a state fails Salt continues to execute the remainder of the defined states and will only refuse to execute states that require the failed state.
But the situation may exist, where you would want all state execution to stop if a single state execution fails. The capability to do this is called failing hard.

State Level Failhard

A single state can have a failhard set, this means that if this individual state fails that all state execution will immediately stop. This is a great thing to do if there is a state that sets up a critical config file and setting a require for each state that reads the config would be cumbersome. A good example of this would be setting up a package manager early on: /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

Finite Ordering of State Execution

When creating salt sls files, it is often important to ensure that they run in a specific order. While states will always execute in the same order, that order is not necessarily defined the way you want it. A few tools exist in Salt to set up the correct state ordering, these tools consist of requisite declarations and order options.

The Order Option

Before using the order option, remember that the majority of state ordering should be done with requisite statements, and that a requisite statement will override an order option. The order option is used by adding an order number to a state declaration with the option order: vim: pkg: - installed - order: 1 By adding the order option to 1 this ensures that the vim package will be installed in tandem with any other state declaration set to the order 1. Any state declared without an order option will be executed after all states with order options are executed. But this construct can only handle ordering states from the beginning. Sometimes you may want to send a state to the end of the line, to do this set the order to last: vim: pkg: - installed - order: last Substantial testing has gone into the state system and it is ready for real world usage. A great deal has been added to the documentation for states and the modules and functions available to states have been cleanly documented. A number of State System bugs have also been founds and repaired, the output from the state system has also been refined to be extremely clear and concise. Error reporting has also been introduced, issues found in sls files will now be clearly reported when executing Salt States.

Gentoo Support

Additional experimental support has been added for Gentoo. This is found in the contribution from Doug Renn, aka nestegg.

Salt 0.9.5 Release Notes

Salt 0.9.5 is one of the largest steps forward in the development of Salt. 0.9.5 comes with many milestones, this release has seen the community of developers grow out to an international team of 46 code contributors and has many feature additions, feature enhancements, bug fixes and speed improvements.
Warning: Be sure to read the upgrade instructions about the switch to msgpack before upgrading!

Community

Nothing has proven to have more value to the development of Salt that the outstanding community that has been growing at such a great pace around Salt. This has proven not only that Salt has great value, but also the expandability of Salt is as exponential as I originally intended. 0.9.5 has received over 600 additional commits since 0.9.4 with a swath of new commiters. The following individuals have contributed to the development of 0.9.5:
• Aaron Bull Schaefer • Antti Kaihola • Bas Tichelaar • Brad Barden • Brian Wagner • Byron Clark • Chris Scheller • Christer Edwards • Clint Savage • Corey Quinn • David Boucha • Eivind Uggedal • Eric Poelke • Evan Borgstrom • Jed Glazner • Jeff Schroeder • Jeffrey C. Ollie • Jonas Buckner • Kent Tenney • Martin Schnabel • Maxim Burgerhout • Mitch Anderson • Nathaniel Whiteinge • Seth House • Thomas S Hatch • Thomas Schreiber • Tor Hveem • lzyeval • syphernl
This makes 21 new developers since 0.9.4 was released! To keep up with the growing community follow Salt on Ohloh (- http://www.ohloh.net/p/salt), to join the Salt development community, fork Salt on Github, and get coding (- https://github.com/saltstack/salt)!

Major Features

SPEED! Pickle to msgpack

For a few months now we have been talking about moving away from Python pickles for network serialization, but a preferred serialization format had not yet been found. After an extensive performance testing period involving everything from JSON to protocol buffers, a clear winner emerged. Message Pack (http://msgpack.org/) proved to not only be the fastest and most compact, but also the most "salt like". Message Pack is simple, and the code involved is very small. The msgpack library for Python has been added directly to Salt.
This move introduces a few changes to Salt. First off, Salt is no longer a "noarch" package, since the msgpack lib is written in C. Salt 0.9.5 will also have compatibility issues with 0.9.4 with the default configuration.
We have gone through great lengths to avoid backwards compatibility issues with Salt, but changing the serialization medium was going to create issues regardless. Salt 0.9.5 is somewhat backwards compatible with earlier minions. A 0.9.5 master can command older minions, but only if the serial config value in the master is set to pickle. This will tell the master to publish messages in pickle format and will allow the master to receive messages in both msgpack and pickle formats.
Therefore the suggested methods for upgrading are either to just upgrade everything at once, or:
1.
Upgrade the master to 0.9.5
2.
Set serial to pickle in the master config
3.
Upgrade the minions
4.
Remove the serial option from the master config
Since pickles can be used as a security exploit the ability for a master to accept pickles from minions at all will be removed in a future release.

C Bindings for YAML

All of the YAML rendering is now done with the YAML C bindings. This speeds up all of the sls files when running states.

Experimental Windows Support

David Boucha has worked tirelessly to bring initial support to Salt for Microsoft Windows operating systems. Right now the Salt Minion can run as a native Windows service and accept commands. In the weeks and months to come Windows will receive the full treatment and will have support for Salt States and more robust support for managing Windows systems. This is a big step forward for Salt to move entirely outside of the Unix world, and proves Salt is a viable cross platform solution. Big Thanks to Dave for his contribution here!

Dynamic Module Distribution

Many Salt users have expressed the desire to have Salt distribute in-house modules, states, renderers, returners, and grains. This support has been added in a number of ways:

Modules via States

Now when salt modules are deployed to a minion via the state system as a file, then the modules will be automatically loaded into the active running minion - no restart required - and into the active running state. So custom state modules can be deployed and used in the same state run.

Modules via Module Environment Directories

Under the file_roots each environment can now have directories that are used to deploy large groups of modules. These directories sync modules at the beginning of a state run on the minion, or can be manually synced via the Salt module salt.modules.saltutil.sync_all.
The directories are named:
• _modules
• _states
• _grains
• _renderers
• _returners
The modules are pushed to their respective scopes on the minions.

Module Reloading

Modules can now be reloaded without restarting the minion, this is done by calling the salt.modules.sys.reload_modules function.
But wait, there's more! Now when a salt module of any type is added via states the modules will be automatically reloaded, allowing for modules to be laid down with states and then immediately used.
Finally, all modules are reloaded when modules are dynamically distributed from the salt master.

Enable / Disable Added to Service

A great deal of demand has existed for adding the capability to set services to be started at boot in the service module. This feature also comes with an overhaul of the service modules and initial systemd support.
This means that the service state can now accept - enable: True to make sure a service is enabled at boot, and - enable: False to make sure it is disabled.

Compound Target

A new target type has been added to the lineup, the compound target. In previous versions the desired minions could only be targeted via a single specific target type, but now many target specifications can be declared.
These targets can also be separated by and/or operators, so certain properties can be used to omit a node:
salt -C 'webserv* and G@os:Debian or E@db.*' test.ping
will match all minions with ids starting with webserv via a glob and minions matching the os:Debian grain. Or minions that match the db.* regular expression.

Node Groups

Often the convenience of having a predefined group of minions to execute targets on is desired. This can be accomplished with the new nodegroups feature. Nodegroups allow for predefined compound targets to be declared in the master configuration file: nodegroups: group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com' group2: 'G@os:Debian and foo.domain.com' And then used via the -N option: salt -N group1 test.ping

Minion Side Data Store

The data module introduces the initial approach into storing persistent data on the minions, specific to the minions. This allows for data to be stored on minions that can be accessed from the master or from the minion. The Minion datastore is young, and will eventually provide an interface similar to a more mature key/value pair server.

Major Grains Improvement

The Salt grains have been overhauled to include a massive amount of extra data. this includes hardware data, os data and salt specific data.

Salt -Q is Useful Now

In the past the salt query system, which would display the data from recent executions would be displayed in pure Python, and it was unreadable. 0.9.5 has added the outputter system to the -Q option, thus enabling the salt query system to return readable output.

Packaging Updates

Huge strides have been made in packaging Salt for distributions. These additions are thanks to our wonderful community where the work to set up packages has proceeded tirelessly.

FreeBSD

Salt on FreeBSD? There a port for that: http://www.freebsd.org/cgi/cvsweb.cgi/ports/sysutils/salt/pkg-descr This port was developed and added by Christer Edwards. This also marks the first time Salt has been included in an upstream packaging system!

Fedora and Red Hat Enterprise

Salt packages have been prepared for inclusion in the Fedora Project and in EPEL for Red Hat Enterprise 5 and 6. These packages are the result of the efforts made by Clint Savage (herlo).

Debian/Ubuntu

A team of many contributors have assisted in developing packages for Debian and Ubuntu. Salt is still actively seeking inclusion in upstream Debian and Ubuntu and the package data that has been prepared is being pushed through the needed channels for inclusion. These packages have been prepared with the help of:
• Corey • Aaron Toponce • and`

More to Come

We are actively seeking inclusion in more distributions. Primarily getting Salt into Gentoo, Suse, OpenBSD and preparing Solaris support are all turning into higher priorities.

Refinement

Salt continues to be refined into a faster, more stable and more usable application. 0.9.5 comes with more debug logging, more bug fixes and more complete support.

More Testing, More BugFixes

0.9.5 comes with more bugfixes due to more testing than any previous release. The growing community and the introduction a a dedicated QA environment have unearthed many issues that were hiding under the covers. This has further refined and cleaned the state interface, taking care of things from minor visual issues to repairing misleading data.

Custom Exceptions

A custom exception module has been added to throw salt specific exceptions. This allows Salt to give much more granular error information.

New Modules

data

The new data module manages a persistent datastore on the minion. Big thanks to bastichelaar for his help refining this module

freebsdkmod

FreeBSD kernel modules can now be managed in the same way Salt handles Linux kernel modules. This module was contributed thanks to the efforts of Christer Edwards

gentoo_service

Support has been added for managing services in Gentoo. Now Gentoo services can be started, stopped, restarted, enabled, disabled and viewed.

pip

The pip module introduces management for pip installed applications. Thanks goes to whitinge for the addition of the pip module

rh_service

The rh_service module enables Red Hat and Fedora specific service management. Now Red Hat like systems come with extensive management of the classic init system used by Red Hat

saltutil

The saltutil module has been added as a place to hold functions used in the maintenance and management of salt itself. Saltutil is used to salt the salt minion. The saltutil module is presently used only to sync extension modules from the master server.

systemd

Systemd support has been added to Salt, now systems using this next generation init system are supported on systems running systemd.

virtualenv

The virtualenv module has been added to allow salt to create virtual Python environments. Thanks goes to whitinge for the addition of the virtualenv module

win_disk

Support for gathering disk information on Microsoft Windows minions The windows modules come courtesy of Utah_Dave

win_service

The win_service module adds service support to Salt for Microsoft Windows services

win_useradd

Salt can now manage local users on Microsoft Windows Systems

yumpkg5

The yumpkg module introduces in 0.9.4 uses the yum api to interact with the yum package manager. Unfortunately, on Red Hat 5 systems salt does not have access to the yum api because the yum api is running under Python 2.4 and Salt needs to run under Python 2.6. The yumpkg5 module bypasses this issue by shelling out to yum on systems where the yum api is not available.

New States

mysql_database

The new mysql_database state adds the ability to systems running a mysql server to manage the existence of mysql databases. The mysql states are thanks to syphernl

mysql_user

The mysql_user state enables mysql user management.

virtualenv

The virtualenv state can manage the state of Python virtual environments. Thanks to Whitinge for the virtualenv state

New Returners

cassandra_returner

A returner allowing Salt to send data to a cassandra server. Thanks to Byron Clark for contributing this returner

Salt 0.9.6 Release Notes

Salt 0.9.6 is a release targeting a few bugs and changes. This is primarily targeting an issue found in the names declaration in the state system. But a few other bugs were also repaired, like missing support for grains in extmods. Due to a conflict in distribution packaging msgpack will no longer be bundled with Salt, and is required as a dependency.

New Features

http and ftp support in files.managed

Now under the source option in the file.managed state a http or ftp address can be used instead of a file located on the salt master.

Allow Multiple Returners

Now the returner interface can define multiple returners, and will also return data back to the master, making the process less ambiguous.

Minion Memory Improvements

A number of modules have been taken out of the minion if the underlying systems required by said modules are not present on the minion system. A number of other modules need to be stripped out in this same way which should continue to make the minion more efficient.

Minions Can Locally Cache Return Data

A new option, cache_jobs, has been added to the minion to allow for all of the historically run jobs to cache on the minion, allowing for looking up historic returns. By default cache_jobs is set to False.

Pure Python Template Support For file.managed

Templates in the file.managed state can now be defined in a Python script. This script needs to have a run function that returns the string that needs to be in the named file.

Salt 0.9.7 Release Notes

Salt 0.9.7 is here! The latest iteration of Salt brings more features and many fixes. This release is a great refinement over 0.9.6, adding many conveniences under the hood, as well as some features that make working with Salt much better.
A few highlights include the new Job system, refinements to the requisite system in states, the mod_init interface for states, external node classification, search path to managed files in the file state, and refinements and additions to dynamic module loading.
0.9.7 also introduces the long developed (and oft changed) unit test framework and the initial unit tests.

Major Features

Salt Jobs Interface

The new jobs interface makes the management of running executions much cleaner and more transparent. Building on the existing execution framework the jobs system allows clear introspection into the active running state of the running Salt interface.
The Jobs interface is centered in the new minion side proc system. The minions now store msgpack serialized files under /var/cache/salt/proc. These files keep track of the active state of processes on the minion.

Functions in the saltutil Module

A number of functions have been added to the saltutil module to manage and view the jobs:
running - Returns the data of all running jobs that are found in the proc directory.
find_job - Returns specific data about a certain job based on job id.
signal_job - Allows for a given jid to be sent a signal.
term_job - Sends a termination signal (SIGTERM, 15) to the process controlling the specified job.
kill_job Sends a kill signal (SIGKILL, 9) to the process controlling the specified job.

The jobs Runner

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

active

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

lookup_jid

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

list_jobs

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

External Node Classification

Salt can now use external node classifiers like Cobbler's cobbler-ext-nodes.
Salt uses specific data from the external node classifier. In particular the classes value denotes which sls modules to run, and the environment value sets to another environment.
An external node classification can be set in the master configuration file via the external_nodes option: http://salt.readthedocs.org/en/latest/ref/configuration/master.html#external-nodes
External nodes are loaded in addition to the top files. If it is intended to only use external nodes, do not deploy any top files.

State Mod Init System

An issue arose with the pkg state. Every time a package was run Salt would need to refresh the package database. This made systems with slower package metadata refresh speeds much slower to work with. To alleviate this issue the mod_init interface has been added to salt states.
The mod_init interface is a function that can be added to a state file. This function is called with the first state called. In the case of the pkg state, the mod_init function sets up a tag which makes the package database only refresh on the first attempt to install a package.
In a nutshell, the mod_init interface allows a state to run any command that only needs to be run once, or can be used to set up an environment for working with the state.

Source File Search Path

The file state continues to be refined, adding speed and capabilities. This release adds the ability to pass a list to the source option. This list is then iterated over until the source file is found, and the first found file is used. The new syntax looks like this: /etc/httpd/conf/httpd.conf: file: - managed - source: - salt://httpd/httpd.conf - http://myserver/httpd.conf: md5=8c1fe119e6f1fd96bc06614473509bf1 The source option can take sources in the list from the salt file server as well as an arbitrary web source. If using an arbitrary web source the checksum needs to be passed as well for file verification.

Refinements to the Requisite System

A few discrepancies were still lingering in the requisite system, in particular, it was not possible to have a require and a watch requisite declared in the same state declaration.
This issue has been alleviated, as well as making the requisite system run more quickly.

Initial Unit Testing Framework

Because of the module system, and the need to test real scenarios, the development of a viable unit testing system has been difficult, but unit testing has finally arrived. Only a small amount of unit testing coverage has been developed, much more coverage will be in place soon. A huge thanks goes out to those who have helped with unit testing, and the contributions that have been made to get us where we are. Without these contributions unit tests would still be in the dark.

Compound Targets Expanded

Originally only support for and and or were available in the compound target. 0.9.7 adds the capability to negate compound targets with not.

Nodegroups in the Top File

Previously the nodegroups defined in the master configuration file could not be used to match nodes for states. The nodegroups support has been expanded and the nodegroups defined in the master configuration can now be used to match minions in the top file.

Salt 0.9.8 Release Notes

Salt 0.9.8 is a big step forward, with many additions and enhancements, as well as a number of precursors to advanced future developments. This version of Salt adds much more power to the command line, making the old hard timeout issues a thing of the past and adds keyword argument support. These additions are also available in the salt client api, making the available api tools much more powerful. The new pillar system allows for data to be stored on the master and assigned to minions in a granular way similar to the state system. It also allows flexibility for users who want to keep data out of their state tree similar to 'external lookup' functionality in other tools. A new way to extend requisites was added, the "requisite in" statement. This makes adding requires or watch statements to external state decs much easier. Additions to requisites making them much more powerful have been added as well as improved error checking for sls files in the state system. A new provider system has been added to allow for redirecting what modules run in the background for individual states. Support for OpenSUSE has been added and support for Solaris has begun serious development. Windows support has been significantly enhanced as well. The matcher and target systems have received a great deal of attention. The default behavior of grain matching has changed slightly to reflect the rest of salt and the compound matcher system has been refined. A number of impressive features with keyword arguments have been added to both the cli and to the state system. This makes states much more powerful and flexible while maintaining the simple configuration everyone loves. The new batch size capability allows for executions to be rolled through a group of targeted minions a percentage or specific number at a time. This was added to prevent the "thundering herd" problem when targeting large numbers of minions for things like service restarts or file downloads.

Upgrade Considerations

Upgrade Issues

There was a previously missed oversight which could cause a newer minion to crash an older master. That oversight has been resolved so the version incompatibility issue will no longer occur. When upgrading to 0.9.8 make sure to upgrade the master first, followed by the minions.

Debian/Ubuntu Packages

The original Debian/Ubuntu packages were called salt and included all salt applications. New packages in the ppa are split by function. If an old salt package is installed then it should be manually removed and the new split packages need to be freshly installed. On the master: # apt-get purge salt # apt-get install salt-{master,minion} On the minions: # apt-get purge salt # apt-get install salt-minion And on any Syndics: # apt-get install salt-syndic The official salt stack ppa for Ubuntu is located at: https://launchpad.net/~saltstack/+archive/salt

Major Features

Pillar

Pillar offers an interface to declare variable data on the master that is then assigned to the minions. The pillar data is made available to all modules, states, sls files etc. It is compiled on the master and is declared using the existing renderer system. This means that learning pillar should be fairly trivial to those already familiar with salt states.

CLI Additions

The salt command has received a serious overhaul and is more powerful than ever. Data is returned to the terminal as it is received, and the salt command will now wait for all running minions to return data before stopping. This makes adding very large --timeout arguments completely unnecessary and gets rid of long running operations returning empty {} when the timeout is exceeded.
When calling salt via sudo, the user originally running salt is saved to the log for auditing purposes. This makes it easy to see who ran what by just looking through the minion logs.
The salt-key command gained the -D and --delete-all arguments for removing all keys. Be careful with this one!

Running States Without a Master

The addition of running states without a salt-master has been added to 0.9.8. This feature allows for the unmodified salt state tree to be read locally from a minion. The result is that the UNMODIFIED state tree has just become portable, allowing minions to have a local copy of states or to manage states without a master entirely.
This is accomplished via the new file client interface in Salt that allows for the salt:// uri to be redirected to custom interfaces. This means that there are now two interfaces for the salt file server, calling the master or looking in a local, minion defined file_roots.
This new feature can be used by modifying the minion config to point to a local file_roots and setting the file_client option to local.

Keyword Arguments and States

State modules now accept the **kwargs argument. This results in all data in a sls file assigned to a state being made available to the state function.
This passes data in a transparent way back to the modules executing the logic. In particular, this allows adding arguments to the pkg.install module that enable more advanced and granular controls with respect to what the state is capable of.
An example of this along with the new debconf module for installing ldap client packages on Debian:
ldap-client-packages: pkg: - debconf: salt://debconf/ldap-client.ans - installed - names: - nslcd - libpam-ldapd - libnss-ldapd

Keyword Arguments and the CLI

In the past it was required that all arguments be passed in the proper order to the salt and salt-call commands. As of 0.9.8, keyword arguments can be passed in the form of kwarg=argument.
# salt -G 'type:dev' git.clone \ repository=https://github.com/saltstack/salt.git cwd=/tmp/salt user=jeff

Matcher Refinements and Changes

A number of fixes and changes have been applied to the Matcher system. The most noteworthy is the change in the grain matcher. The grain matcher used to use a regular expression to match the passed data to a grain, but now defaults to a shell glob like the majority of match interfaces in Salt. A new option is available that still uses the old style regex matching to grain data called grain-pcre. To use regex matching in compound matches use the letter P.
For example, this would match any ArchLinux or Fedora minions:
# salt --grain-pcre 'os:(Arch:Fed).*' test.ping
And the associated compound matcher suitable for top.sls is P:
P@os:(Arch|Fed).*
NOTE: Changing the grains matcher from pcre to glob is backwards incompatible.
Support has been added for matching minions with Yahoo's range library. This is handled by passing range syntax with -R or --range arguments to salt.
More information at: https://github.com/grierj/range/wiki/Introduction-to-Range-with-YAML-files

Requisite in

A new means to updating requisite statements has been added to make adding watchers and requires to external states easier. Before 0.9.8 the only way to extend the states that were watched by a state outside of the sls was to use an extend statement:
include: - http extend: apache: service: - watch: - pkg: tomcat tomcat: pkg: - installed
But the new Requisite in statement allows for easier extends for requisites:
include: - http tomcat: pkg: - installed - watch_in: - service: apache
Requisite in is part of the extend system, so still remember to always include the sls that is being extended!

Providers

Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management. The apt module maps to pkg on Debian and the yum module maps to pkg on Fedora for instance. Sometimes in states, it may be necessary for a non-default module to be used for the desired functionality. For instance, an Arch Linux system may have been set up with systemd support. Instead of using the default service module detected for Arch Linux, the systemd module can be used: http: service: - running - enable: True - provider: systemd Default providers can also be defined in the minion config file: providers: pkg: yumpkg5 service: systemd When default providers are passed in the minion config, then those providers will be applied to all functionality in Salt, this means that the functions called by the minion will use these modules, as well as states.

Requisite Glob Matching

Requisites can now be defined with glob expansion. This means that if there are many requisites, they can be defined on a single line. To watch all files in a directory: http: service: - running - enable: True - watch: - file: /etc/http/conf.d/* This example will watch all defined files that match the glob /etc/http/conf.d/*

Batch Size

The new batch size option allows commands to be executed while maintaining that only so many hosts are executing the command at one time. This option can take a percentage or a finite number:
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.

Module Updates

This is a list of notable, but non-exhaustive updates with new and existing modules.
Windows support has seen a flurry of support this release cycle. We've gained all new file, network, and shadow modules. Please note that these are still a work in progress.
For our ruby users, new rvm and gem modules have been added along with the associated states
The virt module gained basic Xen support.
The yum pkg modules gained Scientific Linux support.
The pkg module on Debian, Ubuntu, and derivatives force apt to run in a non-interactive mode. This prevents issues when package installation waits for confirmation.
A pkg module for OpenSUSE's zypper was added.
The service module on ubuntu natively supports upstart.
A new debconf module was contributed by our community for more advanced control over deb package deployments on Debian based distributions.
The mysql.user state and mysql module gained a password_hash argument.
The cmd module and state gained a shell keyword argument for specifying a shell other than /bin/sh on Linux / Unix systems.
New git and mercurial modules have been added for fans of distributed version control.

In Progress Development

Master Side State Compiling

While we feel strongly that the advantages gained with minion side state compiling are very critical, it does prevent certain features that may be desired. 0.9.8 has support for initial master side state compiling, but many more components still need to be developed, it is hoped that these can be finished for 0.9.9. The goal is that states can be compiled on both the master and the minion allowing for compilation to be split between master and minion. Why will this be great? It will allow storing sensitive data on the master and sending it to some minions without all minions having access to it. This will be good for handling ssl certificates on front-end web servers for instance.

Solaris Support

Salt 0.9.8 sees the introduction of basic Solaris support. The daemon runs well, but grains and more of the modules need updating and testing.

Windows Support

Salt states on windows are now much more viable thanks to contributions from our community! States for file, service, local user, and local group management are more fully fleshed out along with network and disk modules. Windows users can also now manage registry entries using the new "reg" module.

Salt 0.9.9 Release Notes

0.9.9 is out and comes with some serious bug fixes and even more serious features. This release is the last major feature release before 1.0.0 and could be considered the 1.0.0 release candidate. A few updates include more advanced kwargs support, the ability for salt states to more safely configure a running salt minion, better job directory management and the new state test interface. Many new tests have been added as well, including the new minion swarm test that allows for easier testing of Salt working with large groups of minions. This means that if you have experienced stability issues with Salt before, particularly in larger deployments, that these bugs have been tested for, found, and killed.

Major Features

State Test Interface

Until 0.9.9 the only option when running states to see what was going to be changed was to print out the highstate with state.show_highstate and manually look it over. But now states can be run to discover what is going to be changed.
Passing the option test=True to many of the state functions will now cause the salt state system to only check for what is going to be changed and report on those changes.
# salt \* state.highstate test=True
Now states that would have made changes report them back in yellow.

State Syntax Update

A shorthand syntax has been added to sls files, and it will be the default syntax in documentation going forward. The old syntax is still fully supported and will not be deprecated, but it is recommended to move to the new syntax in the future. This change moves the state function up into the state name using a dot notation. This is in-line with how state functions are generally referred to as well: The new way: /etc/sudoers: file.present: - source: salt://sudo/sudoers - user: root - mode: 400

Use and Use_in Requisites

Two new requisite statements are available in 0.9.9. The use and use_in requisite and requisite-in allow for the transparent duplication of data between states. When a state "uses" another state it copies the other state's arguments as defaults. This was created in direct response to the new network state, and allows for many network interfaces to be configured in the same way easily. A simple example: root_file: file.absent: - name: /tmp/nothing - user: root - mode: 644 - group: root - use_in: - file: /etc/vimrc fred_file: file.absent: - name: /tmp/nothing - user: fred - group: marketing - mode: 660 /files/marketing/district7.rst: file.present: - source: salt://marketing/district7.rst - template: jinja - use: - file: fred_file /etc/vimrc: file.present: - source: salt://edit/vimrc This makes the 2 lower state decs inherit the options from their respectively "used" state decs.

Network State

The new network state allows for the configuration of network devices via salt states and the ip salt module. This addition has been given to the project by Jeff Hutchins and Bret Palsson from Jive Communications. Currently the only network configuration backend available is for Red Hat based systems, like Red Hat Enterprise, CentOS, and Fedora.

Exponential Jobs

Originally the jobs executed were stored on the master in the format: <cachedir>/jobs/jid/{minion ids} But this format restricted the number of jobs in the cache to the number of subdirectories allowed on the filesystem. Ext3 for instance limits subdirectories to 32000. To combat this the new format for 0.9.9 is: <cachedir>/jobs/jid_hash[:2]/jid_hash[2:]/{minion ids} So that now the number of maximum jobs that can be run before the cleanup cycle hits the job directory is substantially higher.

ssh_auth Additions

The original ssh_auth state was limited to accepting only arguments to apply to a public key, and the key itself. This was restrictive due to the way the we learned that many people were using the state, so the key section has been expanded to accept options and arguments to the key that over ride arguments passed in the state. This gives substantial power to using ssh_auth with names: sshkeys: ssh_auth: - present - user: backup - enc: ssh-dss - options: - option1="value1" - option2="value2 flag2" - comment: backup - names: - AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0111== - AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0222== override - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0333== override - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0444== - option3="value3",option4="value4 flag4" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0555== override - option3="value3" ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0666==

LocalClient Additions

To follow up the recent additions in 0.9.8 of additional kwargs support, 0.9.9 also adds the capability to send kwargs into commands via a dict. This addition to the LocalClient api can be used like so: import salt.client client = salt.client.LocalClient('/etc/salt/master') ret = client.cmd('*', 'cmd.run', ['ls -l'], kwarg={'cwd': '/etc'}) This update has been added to all cmd methods in the LocalClient class.

Better Self Salting

One problem faced with running Salt states, is that it has been difficult to manage the Salt minion via states, this is due to the fact that if the minion is called to restart while a state run is happening then the state run would be killed. 0.9.9 slightly changes the process scope of the state runs, so now when salt is executing states it can safely restart the salt-minion daemon. In addition to daemonizing the state run, the apt module also daemonizes. This update makes it possible to cleanly update the salt-minion package on Debian/Ubuntu systems without leaving apt in an inconsistent state or killing the active minion process mid-execution.

Wildcards for SLS Modules

Now, when including sls modules in include statements or in the top file, shell globs can be used. This can greatly simplify listing matched sls modules in the top file and include statements: base: '*': - files* - core* include: - users.dev.* - apache.ser*

External Pillar

Since the pillar data is just, data, it does not need to come expressly from the pillar interface. The external pillar system allows for hooks to be added making it possible to extract pillar data from any arbitrary external interface. The external pillar interface is configured via the ext_pillar option. Currently interfaces exist to gather external pillar data via hiera or via a shell command that sends yaml data to the terminal:
ext_pillar: - cmd_yaml: cat /etc/salt/ext.yaml - hiera: /etc/hirea.yaml
The initial external pillar interfaces and extra interfaces can be added to the file salt/pillar.py, it is planned to add more external pillar interfaces. If the need arises a new module loader interface will be created in the future to manage external pillar interfaces.

Single State Executions

The new state.single function allows for single states to be cleanly executed. This is a great tool for setting up a small group of states on a system or for testing out the behavior of single states: # salt \* state.single user.present name=wade uid=2000 The test interface functions here as well, so changes can also be tested against as: # salt \* state.single user.present name=wade uid=2000 test=True

New Tests

A few exciting new test interfaces have been added, the minion swarm allows not only testing of larger loads, but also allows users to see how Salt behaves with large groups of minions without having to create a large deployment.

Minion Swarm

The minion swarm test system allows for large groups of minions to be tested against easily without requiring large numbers of servers or virtual machines. The minion swarm creates as many minions as a system can handle and roots them in the /tmp directory and connects them to a master. The benefit here is that we were able to replicate issues that happen only when there are large numbers of minions. A number of elusive bugs which were causing stability issues in masters and minions have since been hunted down. Bugs that used to take careful watch by users over several days can now be reliably replicated in minutes, and fixed in minutes. Using the swarm is easy, make sure a master is up for the swarm to connect to, and then use the minionswarm.py script in the tests directory to spin up as many minions as you want. Remember, this is a fork bomb, don't spin up more than your hardware can handle! # python minionswarm.py -m 20 --master salt-master

Shell Tests

The new Shell testing system allows us to test the behavior of commands executed from a high level. This allows for the high level testing of salt runners and commands like salt-key.

Client Tests

Tests have been added to test the aspects of the client apis and ensure that the client calls work, and that they manage passed data, in a desirable way.

Author

Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file

Copyright

2013, Thomas S. Hatch

Referenced By

salt-api(1), salt-cloud(1), salt-key(1)