salt/doc/man/salt.7

.TH "SALT" "7" "January 14, 2012" "0.9.5" "Salt"
.SH NAME
salt \- Salt Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.SH SALT AT A GLANCE
.sp
Learn about the various parts of Salt in five minute increments (or less).
.INDENT 0.0
.IP \(bu 2
\fBWhat is Salt?:\fP
\fBOverview\fP
| \fBCommunity\fP
.IP \(bu 2
\fBThe basics:\fP
\fBInstallation\fP
| \fBConfiguration\fP
| [image: vid]
[image]
 \fI\%Watch the screencast\fP
.IP \(bu 2
\fBRemote execution:\fP
\fBModules\fP
.IP \(bu 2
\fBState management:\fP
\fBPart 1\fP
| \fBPart 2\fP
| \fBPart 3\fP
.UNINDENT
.SH SALT IN DEPTH
.sp
While using and setting up Salt is a simple task, the capabilities of Salt run
much deeper. Gaining a better understanding of how Salt works will allow you to
get much more out of Salt.
.INDENT 0.0
.IP \(bu 2
\fBRemote execution:\fP
\fBWriting modules\fP
| \fBfull list of modules\fP
.IP \(bu 2
\fBSystem info & detection:\fP
\fBGrains\fP
.IP \(bu 2
\fBDisplaying or storing responses:\fP
\fBWriting returners\fP
| \fBfull list of returners\fP
.IP \(bu 2
\fBState enforcement:\fP
\fBStates\fP
| \fBHighstate data structure\fP
| \fBfull list of states\fP
.IP \(bu 2
\fBRenderers:\fP
\fBRenderers\fP
| \fBfull list of renderers\fP
.IP \(bu 2
\fBTransferring & syncing files:\fP
\fBFile Server\fP
.IP \(bu 2
\fBNetwork topology:\fP
\fBref/syndic\fP
| \fBref/peer\fP
.IP \(bu 2
\fBConfiguration:\fP
\fBFull list of minion settings\fP
| \fBFull list of master settings\fP
.IP \(bu 2
\fBUsing Salt:\fP
\fBFrom the command\-line\fP
| \fBThrough the Python API\fP
.UNINDENT
.IP "Screencasts and presentations"
.INDENT 0.0
.IP \(bu 2
Thomas S. Hatch was \fI\%interviewed on episode 191 of FLOSS Weekly\fP.
.IP \(bu 2
Presentation at the Salt Lake Linux User Group (SLLUG) in May 2011
\fI\%video\fP
| \fI\%slides\fP (PDF)
.UNINDENT
.RE
.SH SALT QUICK REFERENCE
.INDENT 0.0
.IP \(bu 2
\fBRelease notes\fP
| \fBRoadmap\fP
.IP \(bu 2
\fImodindex\fP
| \fIgenindex\fP
| \fBFull table of contents\fP
.IP \(bu 2
\fIsearch\fP
.UNINDENT
.SH INTRODUCTION TO SALT
We’re not just talking about NaCl..SS Distributed remote execution
.sp
Salt is a distributed remote execution system used to execute commands and
query data. 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 via its ability to handle larger loads of
information, and not just dozens, but hundreds or even thousands of individual
servers, handle them quickly and through a simple and manageable interface.
.SS Simplicity
.sp
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 disparate 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.
.SS Parallel execution
.sp
The core function of Salt is to enable remote commands to be called in parallel
rather than in serial, to use a secure and encrypted protocol, the smallest and
fastest network payloads possible, and with a simple programmer interface. Salt
also introduces more granular controls to the realm of remote execution,
allowing for commands to be executed in parallel and for systems to be targeted
based on more than just hostname, but by system properties.
.SS Building on proven technology
.sp
Salt takes advantage of a number of technologies and techniques. The networking
layer is built with the excellent \fI\%ZeroMQ\fP networking library, so Salt itself
contains a viable, and transparent, AMQ broker inside the daemon. Salt uses
public keys for authentication with the master daemon, then uses faster AES
encryption for payload communication, this means that authentication and
encryption are also built into Salt. Salt takes advantage of communication via
Python pickles, enabling fast and light network traffic.
.SS Python client interface
.sp
In order to allow for simple expansion, Salt execution routines can be written
as plain Python modules and 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.
.SS Fast, flexible, scalable
.sp
The result is a system that can execute commands across groups of varying size,
from very few to very many servers at considerably high speed. A system that is
very fast, easy to set up and amazingly malleable, able to suit the needs of
any number of servers working within the same system. Salt’s unique
architecture brings together the best of the remote execution world, amplifies
its capabilities and expands its range, resulting in this system that is as
versatile as it is practical, able to suit any network.
.SS Open
.sp
Salt is developed under the \fI\%Apache 2.0 licence\fP, 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.  So, please feel free to
sprinkle some of this around your systems and let the deliciousness come forth.
.SH INSTALLING SALT
.sp
The Salt system setup is amazingly simple, as this is one of the central design
goals of Salt. Setting up Salt only requires that the Salt \fImaster\fP be
running and the Salt \fIminions\fP point to the master.
.IP "Salt dependencies"
.sp
Salt should run on any Unix\-like platform so long as the dependencies are
met.
.INDENT 0.0
.IP \(bu 2
\fI\%Python 2.6\fP
.IP \(bu 2
\fI\%ZeroMQ\fP >= 2.1.9
.IP \(bu 2
\fI\%pyzmq\fP >= 2.1.9 — ZeroMQ Python bindings
.IP \(bu 2
\fI\%M2Crypto\fP — Python OpenSSL wrapper
.IP \(bu 2
\fI\%PyCrypto\fP — The Python cryptography toolkit
.IP \(bu 2
\fI\%YAML\fP — Python YAML bindings
.UNINDENT
.sp
Optional Dependencies:
.INDENT 0.0
.IP \(bu 2
\fI\%Jinja2\fP — parsing Salt States (other renderers can be used via the
\fBrenderer\fP setting).
.IP \(bu 2
gcc — dynamic \fI\%Cython\fP module compiling
.UNINDENT
.RE
.SS Instructions by operating system
.INDENT 0.0
.IP \(bu 2
\fI\%Red Hat\fP
.IP \(bu 2
\fI\%Arch Linux\fP
.IP \(bu 2
\fI\%Debian / Ubuntu\fP
.IP \(bu 2
\fI\%Gentoo\fP
.IP \(bu 2
\fI\%FreeBSD\fP
.IP \(bu 2
\fI\%Installing from source\fP
.UNINDENT
.SS Red Hat
.sp
We are working to get Salt packages into EPEL. In the meantime you can
\fByum install salt\-master salt\-minion\fP via our Fedora People
repository.
.SS Red Hat Enterprise Linux 5 & 6 or CentOS 5 & 6
.INDENT 0.0
.IP 1. 3
Install the \fI\%EPEL\fP repository:
.IP 2. 3
Install our repository on FedoraPeople:
.sp
.nf
.ft C
wget \-O /etc/yum.repos.d/epel\-salt.repo \e
    http://repos.fedorapeople.org/repos/herlo/salt/epel\-salt.repo
.ft P
.fi
.UNINDENT
.SS Fedora 15 & 16
.INDENT 0.0
.IP 1. 3
Install our repository on FedoraPeople:
.sp
.nf
.ft C
wget \-O /etc/yum.repos.d/fedora\-salt.repo \e
    http://repos.fedorapeople.org/repos/herlo/salt/fedora\-salt.repo
.ft P
.fi
.UNINDENT
.SS Arch Linux
.sp
Salt can be easily installed from the Arch Linux AUR in one of two flavors:
.INDENT 0.0
.IP \(bu 2
\fI\%Install a Salt release\fP
.IP \(bu 2
\fI\%Install the latest Salt from Git\fP
.UNINDENT
.SS Debian / Ubuntu
.SS Ubuntu
.sp
We are working to get Salt into apt. In the meantime we have a PPA available
for Lucid:
.sp
.nf
.ft C
aptitude \-y install python\-software\-properties
add\-apt\-repository ppa:chris\-lea/libpgm
add\-apt\-repository ppa:chris\-lea/zeromq
add\-apt\-repository ppa:saltstack/salt
aptitude update
aptitude install salt
.ft P
.fi
.SS Debian
.sp
\fI\%A deb package is currently in testing\fP for inclusion in apt. Until that is
accepted you can install Salt by downloading the latest \fB.deb\fP in the
\fI\%downloads section on GitHub\fP and installing that manually:
.sp
.nf
.ft C
dpkg \-i salt\-0.9.5\&.deb
.ft P
.fi
.IP "Installing ZeroMQ on Squeeze (Debian 6)"
.sp
There is a \fI\%python-zmq\fP package available in Debian "wheezy (testing)".
If you don\(aqt have that repo enabled the best way to install Salt and pyzmq
is by using \fBpip\fP (or \fBeasy_install\fP):
.sp
.nf
.ft C
pip install pyzmq salt
.ft P
.fi
.RE
.SS Gentoo
.sp
Salt can be easily installed on Gentoo:
.sp
.nf
.ft C
emerge pyyaml m2crypto pycrypto jinja pyzmq
.ft P
.fi
.sp
Then download and install from source:
.INDENT 0.0
.IP 1. 3
Download the latest source tarball from the GitHub downloads directory for
the Salt project: \fI\%https://github.com/downloads/saltstack/salt/salt-0.9.5.tar.gz\fP
.IP 2. 3
Untar the tarball and run the \fBsetup.py\fP as root:
.UNINDENT
.sp
.nf
.ft C
tar xvf salt\-0.9.5\&.tar.gz
cd salt\-0.9.5
python2 setup.py install
.ft P
.fi
.SS FreeBSD
.sp
Salt is available in the FreeBSD ports tree:
.sp
.nf
.ft C
cd /usr/ports/sysutils/salt && make install clean
.ft P
.fi
.IP "See also"
.sp
\fBfreebsd installation guide\fP
.RE
.SS Installing from source
.INDENT 0.0
.IP 1. 3
Download the latest source tarball from the GitHub downloads directory for
the Salt project: \fI\%https://github.com/downloads/saltstack/salt/salt-0.9.5.tar.gz\fP
.IP 2. 3
Untar the tarball and run the \fBsetup.py\fP as root:
.UNINDENT
.sp
.nf
.ft C
tar xvf salt\-0.9.5\&.tar.gz
cd salt\-0.9.5
python2 setup.py install
.ft P
.fi
.SH CONFIGURING SALT
.sp
Salt configuration is very simple. The default configuration for the
\fImaster\fP will work for most installations and the only requirement for
setting up a \fIminion\fP is to set the location of the master in the minion
configuration file.
.INDENT 0.0
.TP
.B master
The Salt master is the central server that all minions connect to. You
run commands on the minions through the master and minions send data
back to the master (unless otherwise redirected with a \fBreturner\fP). It is started with the
\fBsalt\-master\fP program.
.TP
.B minion
Salt minions are the potentially hundreds or thousands of servers that
you query and control from the master.
.UNINDENT
.sp
The configuration files will be installed to \fB/etc/salt\fP and are named
after the respective components, \fB/etc/salt/master\fP and
\fB/etc/salt/minion\fP.
.sp
To make a minion check into the correct master simply edit the
\fBmaster\fP variable in the minion configuration file to reference
the master DNS name or IPv4 address.
.SS Running Salt
.INDENT 0.0
.IP 1. 3
Start the master in the foreground (to daemonize the process, pass the
\fI\-d flag\fP):
.sp
.nf
.ft C
salt\-master
.ft P
.fi
.IP 2. 3
Start the minion in the foreground (to daemonize the process, pass the
\fI\-d flag\fP):
.sp
.nf
.ft C
salt\-minion
.ft P
.fi
.UNINDENT
.IP "Having trouble?"
.sp
The simplest way to troubleshoot Salt is to run the master and minion in
the foreground with \fIlog level\fP set to \fBdebug\fP:
.sp
.nf
.ft C
salt\-master \-\-log\-level=debug
.ft P
.fi
.RE
.SS Manage Salt public keys
.sp
Salt manages authentication with RSA public keys. The keys are managed on the
\fImaster\fP via the \fBsalt\-key\fP command. Once a \fIminion\fP
checks into the master the master will save a copy of the minion key. Before
the master can send commands to the minion the key needs to be "accepted".
.INDENT 0.0
.IP 1. 3
List the accepted and unaccepted salt keys:
.sp
.nf
.ft C
salt\-key \-L
.ft P
.fi
.IP 2. 3
Accept a minion key:
.sp
.nf
.ft C
salt\-key \-a <minion id>
.ft P
.fi
.sp
or accept all unaccepted minion keys:
.sp
.nf
.ft C
salt\-key \-A
.ft P
.fi
.UNINDENT
.IP "See also"
.sp
\fBsalt\-key manpage\fP
.RE
.SH REMOTE EXECUTION TUTORIAL
.sp
\fBBefore continuing\fP make sure you have a working Salt installation by
following the \fBinstallation\fP and the
\fBconfiguration\fP instructions.
.IP "Stuck?"
.sp
If you get stuck at any point, there are many ways to \fBget help from
the Salt community\fP including our mailing list and our
IRC channel.
.RE
.SS Order your minions around
.sp
Now that you have a \fImaster\fP and at least one \fIminion\fP
communicating with each other you can perform commands on the minion via the
\fBsalt\fP command. Salt calls are comprised of three main components:
.sp
.nf
.ft C
salt \(aq<target>\(aq <function> [arguments]
.ft P
.fi
.IP "See also"
.sp
\fBsalt manpage\fP
.RE
.SS target
.sp
The target component allows you to filter which minions should run the
following function. The default filter is a glob on the minion id. E.g.:
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
salt \(aq*.example.org\(aq test.ping
.ft P
.fi
.sp
Targets can be based on minion system information using the grains system:
.sp
.nf
.ft C
salt \-G \(aqos:Ubuntu\(aq test.ping
.ft P
.fi
.IP "See also"
.sp
\fBGrains system\fP
.RE
.sp
Targets can be filtered by regular expression:
.sp
.nf
.ft C
salt \-E \(aqvirtmach[0\-9]\(aq test.ping
.ft P
.fi
.sp
Finally, targets can be explicitly specified in a list:
.sp
.nf
.ft C
salt \-L foo,bar,baz,quo test.ping
.ft P
.fi
.SS function
.sp
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:
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
.ft P
.fi
.sp
Here are some examples:
.sp
Show all currently available minions:
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
.ft P
.fi
.sp
Run an arbitrary shell command:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run \(aquname \-a\(aq
.ft P
.fi
.IP "See also"
.sp
\fBthe full list of modules\fP
.RE
.SS arguments
.sp
Space\-delimited arguments to the function:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq
.ft P
.fi
.SH STATES TUTORIAL, PART 1
.sp
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 \fBstates reference\fP.
.sp
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.
.sp
\fBBefore continuing\fP make sure you have a working Salt installation by
following the \fBinstallation\fP and the
\fBconfiguration\fP instructions.
.IP "Stuck?"
.sp
If you get stuck at any point, there are many ways to \fBget help from
the Salt community\fP including our mailing list and our
IRC channel.
.RE
.SS Setting up the Salt State Tree
.sp
States are stored in text files on the master and transfered to the minions on
demand via the master\(aqs File Server. The collection of state files make up the
\fIState Tree\fP.
.sp
To start using a central state system in Salt you must first set up the Salt
File Server. Edit your master config file (\fBfile_roots\fP) and
uncomment the following lines:
.sp
.nf
.ft C
file_roots:
  base:
    \- /srv/salt
.ft P
.fi
.sp
Restart the Salt master in order to pick up this change:
.sp
.nf
.ft C
% pkill salt\-master
% salt\-master \-d
.ft P
.fi
.SS Preparing the Top File
.sp
On the master in the directory you specified in the previous step, create a new
file called \fBtop.sls\fP and add the following:
.sp
.nf
.ft C
base:
  \(aq*\(aq:
    \- webserver
.ft P
.fi
.sp
The \fItop file\fP is separated into environments (discussed later). The
default environment is \fBbase\fP. Under the \fBbase\fP environment a collection of
minion matches is defined; for now simply specify all hosts (\fB*\fP).
.IP "Targeting minions"
.sp
The expressions can use any of the targeting mechanisms used by Salt —
minions can be matched by glob, pcre regular expression, or by \fBgrains\fP. For example:
.sp
.nf
.ft C
base:
  \(aqos:Fedora\(aq:
    \- match: grain
    \- webserver
.ft P
.fi
.RE
.SS Create an \fBsls\fP module
.sp
In the same directory as your \fItop file\fP, create an empty file, called an
\fIsls module\fP, named \fBwebserver.sls\fP. Type the following and save the
file:
.sp
.nf
.ft C
apache:                 # ID declaration
  pkg:                  # state declaration
    \- installed         # function declaration
.ft P
.fi
.sp
The first line, called the \fIID declaration\fP, is an arbitrary identifier.
In this case it defines the name of the package to be installed. \fBNOTE:\fP the
package name for the Apache httpd web server may differ on your OS or distro —
for example, on Fedora it is \fBhttpd\fP but on Debian/Ubuntu it is \fBapache2\fP.
.sp
The second line, called the \fIstate declaration\fP, defines which of the
Salt States we are using. In this example, we are using the \fBpkg state\fP to ensure that a given package is installed.
.sp
The third line, called the \fIfunction declaration\fP defines which function
in the \fBpkg state\fP module to call.
.IP "Renderers"
.sp
States \fIsls\fP 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 \fI\%DSLs\fP are a dime\-a\-dozen and everyone
has a favorite.
.sp
Building the expected data structure is the job of Salt \fBrenderers\fP and they are dead\-simple to write.
.sp
In this tutorial we will be using YAML in Jinja2 templates which is the
default format. You can change the default by changing
\fBrenderer\fP in the master configuration file.
.RE
.SS Install the package
.sp
Next, let\(aqs run the state we created. Open a terminal on the master and run:
.sp
.nf
.ft C
% salt \(aq*\(aq state.highstate
.ft P
.fi
.sp
Our master is instructing all targeted minions to run \fBstate.highstate\fP. When a minion executes a highstate call it
will download the \fItop file\fP and attempt to match the expressions. When
it does match an expression the modules listed for it will be downloaded,
compiled, and executed.
.sp
Once completed, the minion will report back with a summary of all actions taken
and all changes made.
.IP "Troubleshooting Salt"
.sp
In case you don\(aqt see the expected output, the following tips can help you
narrow down the problem.
.INDENT 0.0
.TP
.B Turn up logging
Salt can be quite chatty when you change the logging setting to
\fBdebug\fP:
.sp
.nf
.ft C
salt\-minion \-l debug
.ft P
.fi
.TP
.B Run the minion in the foreground
By not starting the minion in daemon mode (\fI\-d\fP) you can view any output from the minion as it works:
.sp
.nf
.ft C
salt\-minion &
.ft P
.fi
.UNINDENT
.sp
Increase the default timeout value when running \fBsalt\fP. For
example, to change the default timeout to 60 seconds:
.sp
.nf
.ft C
salt \-t 60
.ft P
.fi
.sp
For best results, combine all three:
.sp
.nf
.ft C
salt\-minion \-l debug &          # On the minion
salt \(aq*\(aq state.highstate \-t 60  # On the master
.ft P
.fi
.RE
.SS Next steps
.sp
This tutorial focused on getting a simple Salt States configuration working.
\fBPart 2\fP will build on this example to cover more advanced
\fIsls\fP syntax and will explore more of the states that ship with Salt.
.SH STATES TUTORIAL, PART 2
.sp
This tutorial builds on the topic covered in \fBpart 1\fP. It is
recommended that you begin there.
.sp
In the last Salt States tutorial we covered the basics of installing a package.
In this tutorial we will modify our \fBwebserver.sls\fP file to be more
complicated, have requirements, and use even more Salt States.
.SS Call multiple States
.sp
You can specify multiple \fIstate declarations\fP under
an \fIID declaration\fP. For example, a quick modification to our
\fBwebserver.sls\fP to also start Apache if it is not running:
.sp
.nf
.ft C
apache:
  pkg:
    \- installed
  service:
    \- running
.ft P
.fi
.sp
Try stopping Apache before running \fBstate.highstate\fP once again and observe
the output.
.SS Expand the SLS module
.sp
As you have seen, sls modules are appended with the file extension \fB.sls\fP 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 \fBwebserver\fP and moving and renaming \fBwebserver.sls\fP to
\fBwebserver/init.sls\fP. Your state directory should now resemble:
.sp
.nf
.ft C
|\- top.sls
\(ga\- webserver/
   \(ga\- init.sls
.ft P
.fi
.IP "Organizing SLS modules"
.sp
You can place additional \fB.sls\fP files in a state file directory. This
affords much cleaner organization of your state tree on the filesystem. For
example, if we created a \fBwebserver/django.sls\fP file that module would be
referenced as \fBwebserver.django\fP.
.sp
In addition, States provide powerful includes and extending functionality
which we will cover in \fBPart 3\fP.
.RE
.SS Require other states
.sp
We now have a working installation of Apache so let\(aqs add an HTML file to
customize our website. It isn\(aqt exactly useful to have a website without a
webserver so we don\(aqt want Salt to install our HTML file until Apache is
installed and running. Include the following at the bottom of your
\fBwebserver/init.sls\fP file:
.sp
.nf
.ft C
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
.ft P
.fi
.sp
Again in \fBline 1\fP is the \fIID declaration\fP. In this example it is the
location we want to install our custom HTML file. (\fBNote:\fP the default
location that Apache serves may differ from the above on your OS or distro.
\fB/srv/www\fP could also be a likely place to look.)
.sp
\fBLine 2\fP the \fIstate declaration\fP. This example uses the Salt \fBfile
state\fP.
.sp
\fBLine 3\fP is the \fIfunction declaration\fP. The \fBmanaged function\fP will download a file from the master and install it
in the location specified.
.sp
\fBLine 4\fP is a \fIfunction arg declaration\fP which, in this example, passes
the \fBsource\fP argument to the \fBmanaged function\fP.
.sp
\fBLine 5\fP is a \fIrequisite declaration\fP.
.sp
\fBLine 6\fP is a \fIrequisite reference\fP which refers to a state and an ID.
In this example, it is referring to the \fBID declaration\fP from our example in
\fBpart 1\fP. This declaration tells Salt not to install the HTML
file until Apache is installed.
.sp
Next, create the \fBindex.html\fP file and save it in the \fBwebserver\fP
directory:
.sp
.nf
.ft C
<html>
    <head><title>Salt rocks</title></head>
    <body>
        <h1>This file brought to you by Salt</h1>
    </body>
</html>
.ft P
.fi
.sp
Last, call \fBstate.highstate\fP again and the
minion will fetch and execute the highstate as well as our HTML file from the
master using Salt\(aqs File Server:
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate
.ft P
.fi
.sp
Verify that Apache is now serving your custom HTML.
.IP "\fBrequire\fP vs. \fBwatch\fP"
.sp
There are two \fIrequisite declarations\fP,
“require” and “watch”. Not every state supports “watch”. The \fBservice
state\fP does support “watch” and will restart a
service based on the watch condition.
.sp
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:
.sp
.nf
.ft C
/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
.ft P
.fi
.sp
If the pkg and service names differ on your OS or distro of choice you can
specify each one separately using a \fIname declaration\fP which
explained in \fBPart 3\fP.
.RE
.SS Next steps
.sp
In \fBpart 3\fP we will discuss how to use includes, extends and
templating to make hugely complicated State Tree configurations dead\-simple.
.SH STATES TUTORIAL, PART 3
.sp
This tutorial builds on the topic covered in \fBpart 2\fP. It is
recommended that you begin there.
.sp
This tutorial will cover more advanced templating and configuration techniques
for \fBsls\fP files.
.SS Templating SLS modules
.sp
SLS modules may require programming logic or inline executions. This is
accomplished with module templating. The default module templating system used
is \fI\%Jinja2\fP  and may be configured by changing the \fBrenderer\fP
value in the master config.
.sp
All states are passed through a templating system when they are initially read,
so all that is required to make use of the templating system is to add some
templating code. An example of an sls module with templating may look like
this:
.sp
.nf
.ft C
{% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %}
{{ usr }}:
  user:
    \- present
{% endfor %}
.ft P
.fi
.sp
This templated sls file once generated will look like this:
.sp
.nf
.ft C
moe:
  user:
    \- present
larry:
  user:
    \- present
currly:
  user:
    \- present
.ft P
.fi
.SS Using Grains in SLS modules
.sp
Often times a state will need to behave differently on different systems.
\fBSalt grains\fP can be used from within sls modules. An object
called \fBgrains\fP is made available in the template context:
.sp
.nf
.ft C
apache:
  pkg:
    {% if grains[\(aqos\(aq] == \(aqRedHat\(aq %}
    \- name: httpd
    {% elif grains[\(aqos\(aq] == \(aqUbuntu\(aq %}
    \- name: apache2
    {% endif %}
    \- installed
.ft P
.fi
.SS Calling Salt modules from templates
.sp
All of the Salt modules loaded by the minion ave 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.
.sp
The Salt module functions are also made available in the template context as
\fBsalt\fP:
.sp
.nf
.ft C
{% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %}
{{ usr }}:
  group:
    \- present
  user:
    \- present
    \- gid: {{ salt[\(aqfile.group_to_gid\(aq](usr) }}
    \- require:
      \- group: {{ usr }}
{% endfor %}
.ft P
.fi
.sp
Below is another example that calls an arbitrary command in order to grab the
mac addr for eth0:
.sp
.nf
.ft C
salt[\(aqcmd.run\(aq](\(aqifconfig eth0 | grep HWaddr | cut \-d" " \-f10\(aq)
.ft P
.fi
.SS Advanced SLS module syntax
.sp
Last we will cover some incredibly useful techniques for more complex State
trees.
.SS \fIInclude declaration\fP
.sp
You have seen an example of how to spread a Salt tree across several files but
in order to be able to have \fIrequisite references\fP
span multiple files you must use a \fIinclude declaration\fP. For example:
.sp
\fBpython\-libs.sls\fP:
.sp
.nf
.ft C
python\-dateutil:
  pkg:
    \- installed
.ft P
.fi
.sp
\fBdjango.sls\fP:
.sp
.nf
.ft C
include:
  \- python\-libs

django:
  pkg:
    \- installed
    \- require:
      \- pkg: python\-dateutil
.ft P
.fi
.SS \fIExtend declaration\fP
.sp
You can modify previous declarations by using a \fIextend declaration\fP. For
example the following modifies the Apache tree to also restart Apache when the
vhosts file is changed:
.sp
\fBapache.sls\fP:
.sp
.nf
.ft C
apache:
  pkg:
    \- installed
.ft P
.fi
.sp
\fBmywebsite.sls\fP:
.sp
.nf
.ft C
include:
  \- apache

extend:
  apache
    service:
      \- watch:
        \- file: /etc/httpd/extra/httpd\-vhosts.conf

/etc/httpd/extra/httpd\-vhosts.conf:
  file:
    \- managed
    \- source: salt://httpd\-vhosts.conf
.ft P
.fi
.SS \fIName declaration\fP
.sp
You can override the \fIID declaration\fP by using a \fIname
declaration\fP. For example the previous example is a bit more maintainable if
rewritten as the following:
.sp
\fBmywebsite.sls\fP:
.sp
.nf
.ft C
include:
  \- apache

extend:
  apache
    service:
      \- watch:
        \- file: mywebsite

mywebsite:
  file:
    \- managed
    \- name: /etc/httpd/extra/httpd\-vhosts.conf
    \- source: salt://httpd\-vhosts.conf
.ft P
.fi
.SS \fINames declaration\fP
.sp
Even more powerful is using a \fInames declaration\fP to override the
\fIID declaration\fP 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:
.sp
.nf
.ft C
stooges:
  user:
    \- present
    \- names:
      \- moe
      \- larry
      \- curly
.ft P
.fi
.SS Continue learning
.sp
The best way to continue learing about Salt States is to read through the
\fBreference documentation\fP and to look through examples
of existing \fIstate trees\fP. You can find examples in the
\fI\%salt-states repository\fP and please send a pull\-request on GitHub with any
state trees that you build and want to share!
.sp
If you have any questions, suggestions, or just want to chat with other people
who are using Salt we have an \fBactive community\fP.
.SH COMMUNITY
.sp
Join the Salt!
.sp
There are many ways to participate in and communicate with the Salt community.
.sp
Salt has an active IRC channel and a mailing list.
.SS Mailing List
.sp
Join the \fI\%salt-users mailing list\fP. 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.
.sp
\fI\%http://groups.google.com/group/salt-users\fP
.SS IRC
.sp
The \fB#salt\fP IRC channel is hosted on the popular \fI\%Freenode\fP network. You
can use the \fI\%Freenode webchat client\fP right from your browser.
.SS Follow on Github
.sp
The Salt code is developed via Github. Follow Salt for constant updates on what
is happening in Salt development:
.sp
\fI\%https://github.com/saltstack/salt\fP
.SS The Red45 Blog
.sp
News and thoughts on Salt and related projects is often posted on Thomas\(aq blog
\fI\%The Red45\fP:
.sp
\fI\%http://red45.wordpress.com/\fP
.SS Follow on ohloh
.sp
\fI\%https://www.ohloh.net/p/salt\fP
.SS Developing Salt
.sp
If you want to help develop Salt there is a great need and your patches are
welcome!
.sp
To assist in Salt development, you can help in a number of ways.
.SS Posting patches to the mailing list
.sp
If you have a patch for Salt, please format it via \fBgit format\-patch\fP and
send it to the Salt users mailing list. This allows the patch to give you the
contributor the credit for your patch, and gives the Salt community an archive
of the patch and a place for discussion.
.SS Setting a Github pull request
.sp
This is probably the preferred method for contributions, simply create a Github
fork, commit your changes to the fork, and then open up a pull request.
.SS Contributions Welcome!
.sp
The goal here it to make contributions clear, make sure there is a trail for
where the code has come from, but most importantly, to give credit where credit
is due!
.SH INTRODUCTION TO EXTENDING SALT
.sp
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.
.sp
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.
.SS Client API
.sp
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.
.SS Adding Loadable Plugins
.sp
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.
.sp
The breaking points and helping interfaces span from convenience master side
executions to manipulating the flow of how data is handled by Salt.
.SS Minion Execution Modules
.sp
The minion execution modules or just \fBmodules\fP are the core to what salt is
and does. These modules are found in:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/modules\fP
.sp
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.
.SS Grains
.sp
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.
.sp
The Salt grains are the interface used for auto detection and dynamic assignment
of execution modules and types to specific salt minions.
.sp
The code used to generate the Salt grains can be found here:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/grains\fP
.SS States
.sp
Salt supports state enforcement, this makes Salt a high speed and very efficient
solution for system configuration management.
.sp
States can be easily added to Salt by dropping a new state module in:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/states\fP
.SS Renderers
.sp
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.
.sp
The existing renderers can be found here:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/renderers\fP
.SS Returners
.sp
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.
.sp
The existing returners can be found here:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/returners\fP
.SS Runners
.sp
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.
.sp
Existing Salt runners are located here:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/runners\fP
.SH MODULES
.sp
Salt modules are the functions called by the \fBsalt\fP command.
.IP "See also"
.sp
\fIFull list of builtin modules\fP
.sp
Salt ships with many modules that cover a wide variety of tasks.
.RE
.SS Easy Modules to write
.sp
Salt modules are amazingly simple to write, just write a regular Python module
or a regular Cython module and place it in the \fBsalt/modules\fP directory.
.sp
Since Salt modules are just Python/Cython modules there are no restraints as to
what you can put inside of a salt module, and if a Salt module has errors and
cannot import the Salt minion will continue to load without issue, the module
with errors will simply be omitted.
.sp
If adding a Cython module the file must be named \fB<modulename>.pyx\fP 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 \fB*.pyx\fP file is required.
.SS Cross Calling Modules
.sp
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 which already exist
can be called.
.sp
The variable \fB__salt__\fP 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.
.sp
Salt modules can be cross called by accessing the value in the \fB__salt__\fP
dict:
.sp
.nf
.ft C
def foo(bar):
    return __salt__[\(aqcmd.run\(aq](bar)
.ft P
.fi
.sp
This code will call the Salt cmd module\(aqs run function and pass the argument
\fBbar\fP.
.SS Preloaded Modules Data
.sp
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.
.SS Grains Data
.sp
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 OS. 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 releases after 0.8
.sp
The values detected by the Salt Grains on the minion are available in a dict by
the name of \fB__grains__\fP and can be accessed from within callable objects in
the Python modules.
.sp
To see the contents of the grains dict for a given system in your deployment
run the \fBgrains.items()\fP function:
.sp
.nf
.ft C
salt \(aqhostname\(aq grains.items
.ft P
.fi
.sp
To use the \fB__grains__\fP dict simply call it as a Python dict from within your
code, an excellent example is available in the Grains module:
\fBsalt.modules.grains\fP.
.SS Module Configuration
.sp
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.
.sp
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
\fBstrongly\fP recommended that the values passed in the configuration file match
the module. This means that a value intended for the \fBtest\fP module should be
named \fBtest.<value>\fP.
.sp
Configuration also requires that default configuration parameters need to be
loaded as well. This can be done simply by adding the \fB__opts__\fP dict to the
top level of the module.
.sp
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. \fBsalt.modules.test\fP, \fBconf/minion\fP.
.SS Printout Configuration
.sp
Since module functions can return different data, and the way the data is
printed can greatly change the presentation, Salt has a printout
configuration.
.sp
When writing a module the \fB__outputter__\fP dict can be declared in the module.
The \fB__outputter__\fP dict contains a mapping of function name to Salt
Outputter.
.sp
.nf
.ft C
__outputter__ = {
                \(aqrun\(aq: \(aqtxt\(aq
                }
.ft P
.fi
.sp
This will ensure that the text outputter is used.
.SS Virtual Modules
.sp
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.
.sp
The salt modules for package managers all contain a \fB__virtual__\fP function
which is called to define what systems the module should be loaded on.
.sp
The \fB__virtual__\fP 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.
.sp
This means that the package manager modules can be presented as the pkg module
regardless of what the actual module is named.
.sp
The package manager modules are the best example of using the \fB__virtual__\fP
function:
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/modules/pacman.py\fP
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/modules/yumpkg.py\fP
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/modules/apt.py\fP
.SS Documentation
.sp
Salt modules are self documenting, the \fBsys.doc()\fP function will return the
documentation for all available Facter modules:
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
.ft P
.fi
.sp
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.
.SS Adding Documentation to Salt Modules
.sp
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.
.sp
Documenting Salt modules is easy! Just add a python docstring to the function.
.sp
.nf
.ft C
def spam(eggs):
    \(aq\(aq\(aq
    A function to make some spam with eggs!

    CLI Example:
    salt \(aq*\(aq test.spam eggs
    \(aq\(aq\(aq
    return eggs
.ft P
.fi
.sp
Now when the sys.doc call is executed the docstring will be cleanly returned
to the calling terminal.
.SS How Functions are Read
.sp
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 \fB_\fP.
.SS Objects Loaded Into the Salt Minion
.sp
.nf
.ft C
def foo(bar):
    return bar

class baz:
    def __init__(self, quo):
        return quo
.ft P
.fi
.SS Objects NOT Loaded into the Salt Minion
.sp
.nf
.ft C
def _foobar(baz): # Preceded with an _
    return baz

cheese = {} # Not a callable python object
.ft P
.fi
.SS Examples of Salt Modules
.sp
The existing Salt modules should be fairly easy to read and understand, the
goal of the main distribution\(aqs Salt modules is not only to build a set of
functions for salt, but to stand as examples for building out more Salt
modules.
.sp
The existing modules can be found here:
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/modules\fP
.sp
The most simple module is the test module, it contains the simplest salt
function, test.ping:
.sp
.nf
.ft C
def ping():
    \(aq\(aq\(aq
    Just used to make sure the minion is up and responding
    Return True

    CLI Example:
    salt \(aq*\(aq test.ping
    \(aq\(aq\(aq
    return True
.ft P
.fi
.SH FULL LIST OF BUILTIN MODULES
.TS
center;
|l|l|.
_
T{
\fBapache\fP
T}	T{
Support for Apache
T}
_
T{
\fBapt\fP
T}	T{
Support for APT (Advanced Packaging Tool)
T}
_
T{
\fBarchive\fP
T}	T{
A module to wrap archive calls
T}
_
T{
\fBbutterkvm\fP
T}	T{
Specialized routines used by the butter cloud component
T}
_
T{
\fBcluster\fP
T}	T{
T}
_
T{
\fBcmd\fP
T}	T{
A module for shelling out
T}
_
T{
\fBcp\fP
T}	T{
T}
_
T{
\fBcron\fP
T}	T{
Work with cron
T}
_
T{
\fBdisk\fP
T}	T{
Module for gathering disk information
T}
_
T{
\fBebuild\fP
T}	T{
Support for Portage
T}
_
T{
\fBfile\fP
T}	T{
Manage information about files on the minion, set/read user, group, and mode
T}
_
T{
\fBfreebsdpkg\fP
T}	T{
Package support for FreeBSD
T}
_
T{
\fBgrains\fP
T}	T{
Control aspects of the grains data
T}
_
T{
\fBgroupadd\fP
T}	T{
Manage groups on Linux
T}
_
T{
\fBhosts\fP
T}	T{
Manage the information in the hosts file
T}
_
T{
\fBkmod\fP
T}	T{
Module to manage Linux kernel modules
T}
_
T{
\fBlinux_sysctl\fP
T}	T{
Module for viewing and modifying sysctl parameters
T}
_
T{
\fBmdadm\fP
T}	T{
Salt module to manage RAID arrays with mdadm
T}
_
T{
\fBmoosefs\fP
T}	T{
Module for gathering and managing information about MooseFS
T}
_
T{
\fBmount\fP
T}	T{
Salt module to manage unix mounts and the fstab file
T}
_
T{
\fBmysql\fP
T}	T{
T}
_
T{
\fBnetwork\fP
T}	T{
Module for gathering and managing network information
T}
_
T{
\fBpacman\fP
T}	T{
A module to wrap pacman calls, since Arch is the best
T}
_
T{
\fBps\fP
T}	T{
T}
_
T{
\fBpublish\fP
T}	T{
T}
_
T{
\fBpuppet\fP
T}	T{
Execute puppet routines
T}
_
T{
\fBpw_group\fP
T}	T{
Manage groups on Linux
T}
_
T{
\fBpw_user\fP
T}	T{
Manage users with the useradd command
T}
_
T{
\fBselinux\fP
T}	T{
Execute calls on selinux
T}
_
T{
\fBservice\fP
T}	T{
The default service module, if not otherwise specified salt will fall back
T}
_
T{
\fBshadow\fP
T}	T{
Manage the shadow file
T}
_
T{
\fBsolr\fP
T}	T{
Apache Solr Salt Module
T}
_
T{
\fBssh\fP
T}	T{
Manage client ssh components
T}
_
T{
\fBstate\fP
T}	T{
T}
_
T{
\fBstatus\fP
T}	T{
Module for returning various status data about a minion.
T}
_
T{
\fBtest\fP
T}	T{
Module for running arbitrary tests
T}
_
T{
\fBtomcat\fP
T}	T{
Support for Tomcat
T}
_
T{
\fBuseradd\fP
T}	T{
Manage users with the useradd command
T}
_
T{
\fBvirt\fP
T}	T{
Work with virtual machines managed by libvirt
T}
_
T{
\fByumpkg\fP
T}	T{
T}
_
.TE
.SS salt.modules.apache
.sp
Support for Apache
.INDENT 0.0
.TP
.B salt.modules.apache.directives()
Return list of directives together with expected arguments
and places where the directive is valid (\fBapachectl \-L\fP)
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq apache.directives
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.fullversion()
Return server version from apachectl \-V
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq apache.fullversion
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.modules()
Return list of static and shared modules from apachectl \-M
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq apache.modules
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.servermods()
Return list of modules compiled into the server (apachectl \-l)
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq apache.servermods
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.signal(signal=None)
Signals httpd to start, restart, or stop.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq apache.signal restart
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.version()
Return server version from apachectl \-v
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq apache.version
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.vhosts()
Show the settings as parsed from the config file (currently
only shows the virtualhost settings). (\fBapachectl \-S\fP)
Because each additional virtual host adds to the execution
time, this command may require a long timeout be specified.
.sp
CLI Example:
.sp
.nf
.ft C
salt \-t 10 \(aq*\(aq apache.vhosts
.ft P
.fi
.UNINDENT
.SS salt.modules.apt
.sp
Support for APT (Advanced Packaging Tool)
.INDENT 0.0
.TP
.B salt.modules.apt.available_version(name)
The available version of the package in the repository
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.available_version <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apt.install(pkg, refresh=False, repo=\(aq\(aq, skip_verify=False)
Install the passed package
.INDENT 7.0
.TP
.B pkg
The name of the package to be installed
.TP
.B refresh
False
Update apt before continuing
.TP
.B repo
(default)
Specify a package repository to install from
(e.g., \fBapt\-get \-t unstable install somepackage\fP)
.TP
.B skip_verify
False
Skip the GPG verification check (e.g., \fB\-\-allow\-unauthenticated\fP)
.UNINDENT
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
        \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apt.list_pkgs(regex_string=\(aq\(aq)
List the packages currently installed in a dict:
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apt.purge(pkg)
Remove a package via \fBapt\-get purge\fP along with all configuration
files and unused dependencies.
.sp
Returns a list containing the names of the removed packages
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apt.refresh_db()
Updates the APT database to latest packages based upon repositories
.sp
Returns a dict:
.sp
.nf
.ft C
{\(aq<database name>\(aq: Bool}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apt.remove(pkg)
Remove a single package via \fBapt\-get remove\fP
.sp
Returns a list containing the names of the removed packages.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apt.upgrade(refresh=True)
Upgrades all packages via \fBapt\-get dist\-upgrade\fP
.sp
Returns a list of dicts containing the package names, and the new and old
versions:
.sp
.nf
.ft C
[
    {\(aq<package>\(aq:  {\(aqold\(aq: \(aq<old\-version>\(aq,
                \(aqnew\(aq: \(aq<new\-version>\(aq]
    }\(aq,
    ...
]
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apt.version(name)
Returns a string representing the package version or an empty string if not
installed
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
.ft P
.fi
.UNINDENT
.SS salt.modules.archive
.sp
A module to wrap archive calls
.INDENT 0.0
.TP
.B salt.modules.archive.gunzip(gzipfile)
Uses the gunzip command to unpack gzip files
.sp
CLI Example to create \fB/tmp/sourcefile.txt\fP:
.sp
.nf
.ft C
salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt.gz
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.gzip(sourcefile)
Uses the gzip command to create gzip files
.sp
CLI Example to create \fB/tmp/sourcefile.txt.gz\fP:
.sp
.nf
.ft C
salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.rar(rarfile, *sources)
Uses the rar command to create rar files
Uses rar for Linux from \fI\%http://www.rarlab.com/\fP
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq archive.rar /tmp/rarfile.rar /tmp/sourcefile1 /tmp/sourcefile2
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.tar(options, tarfile, *sources)
Uses the tar command to pack, unpack, etc tar files
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file1 /tmp/file2
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.unrar(rarfile, dest, *xfiles)
Uses the unrar command to unpack rar files
Uses rar for Linux from \fI\%http://www.rarlab.com/\fP
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq archive.unrar /tmp/rarfile.rar /home/strongbad/ file1 file2
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.unzip(zipfile, dest, *xfiles)
Uses the unzip command to unpack zip files
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq archive.unzip /tmp/zipfile.zip /home/strongbad/ file1 file2
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.zip(zipfile, *sources)
Uses the zip command to create zip files
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq archive.zip /tmp/zipfile.zip /tmp/sourcefile1 /tmp/sourcefile2
.ft P
.fi
.UNINDENT
.SS salt.modules.butterkvm
.sp
Specialized routines used by the butter cloud component
.INDENT 0.0
.TP
.B 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\(aqt call this from the command line!
.INDENT 7.0
.TP
.B instance
string
The path to the instance directory for the given vm on shared storage
.TP
.B vda
The location where the virtual machine image needs to be placed
.TP
.B image
The image to move into place
.TP
.B pin
A "pin" data structure defining the myriad of possible vdb\-vbz disk
images to generate
.UNINDENT
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq butterkvm.create <instance dir> <root image location>\e
    <Destination> <pin data>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.butterkvm.full_butter_data(local_path)
Return the full virt info, but add butter data!
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq buttervm.full_butter_data <image_path>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.butterkvm.libvirt_creds()
Returns the user and group that the disk images should be owned by
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq butterkvm.libvirt_creds
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.butterkvm.local_images(local_path)
return the virtual machine names for all of the images located in the
butter cloud\(aqs local_path in a list:
.sp
.nf
.ft C
[\(aqvm1.boo.com\(aq, \(aqvm2.foo.com\(aq]
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq buttervm.local_images <image_path>
.ft P
.fi
.UNINDENT
.SS salt.modules.cmd
.sp
A module for shelling out
.sp
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
.INDENT 0.0
.TP
.B salt.modules.cmd.exec_code(lang, code, cwd=\(aq/home/thatch\(aq)
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
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.exec_code ruby \(aqputs "cheese"\(aq
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmd.has_exec(cmd)
Returns true if the executable is available on the minion, false otherwise
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.has_exec cat
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmd.retcode(cmd, cwd=\(aq/home/thatch\(aq)
Execute a shell command and return the command\(aqs return code.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.retcode "file /bin/bash"
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmd.run(cmd, cwd=\(aq/home/thatch\(aq)
Execute the passed command and return the output as a string
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run "ls \-l | awk \(aq/foo/{print $2}\(aq"
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmd.run_all(cmd, cwd=\(aq/home/thatch\(aq)
Execute the passed command and return a dict of return data
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_all "ls \-l | awk \(aq/foo/{print $2}\(aq"
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmd.run_stderr(cmd, cwd=\(aq/home/thatch\(aq)
Execute a command and only return the standard error
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stderr "ls \-l | awk \(aq/foo/{print $2}\(aq"
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmd.run_stdout(cmd, cwd=\(aq/home/thatch\(aq)
Execute a command, and only return the standard out
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stdout "ls \-l | awk \(aq/foo/{print $2}\(aq"
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmd.which(cmd)
Returns the path of an executable available on the minion, None otherwise
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.which cat
.ft P
.fi
.UNINDENT
.SS salt.modules.cron
.sp
Work with cron
.INDENT 0.0
.TP
.B salt.modules.cron.list_tab(user)
Return the contents of the specified user\(aqs crontab
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cron.list_tab root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.ls(user)
Return the contents of the specified user\(aqs crontab
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cron.list_tab root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.raw_cron(user)
Return the contents of the user\(aqs crontab
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.rm(user, minute, hour, dom, month, dow, cmd)
Remove a cron job up for a specified user.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.rm_job(user, minute, hour, dom, month, dow, cmd)
Remove a cron job up for a specified user.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.set_job(user, minute, hour, dom, month, dow, cmd)
Sets a cron job up for a specified user.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.set_special(user, special, cmd)
Set up a special command in the crontab.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq cron.set_special @hourly \(aqecho foobar\(aq
.ft P
.fi
.UNINDENT
.SS salt.modules.disk
.sp
Module for gathering disk information
.INDENT 0.0
.TP
.B salt.modules.disk.inodeusage()
Return inode usage information for volumes mounted on this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq disk.inodeusage
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.disk.usage()
Return usage information for volumes mounted on this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq disk.usage
.ft P
.fi
.UNINDENT
.SS salt.modules.ebuild
.sp
Support for Portage
.INDENT 0.0
.TP
.B salt.modules.ebuild.available_version(name)
The available version of the package in the repository
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.available_version <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.install(pkg, refresh=False, **kwargs)
Install the passed package
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
        \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.list_pkgs()
List the packages currently installed in a dict:
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.purge(pkg)
Portage does not have a purge, this function calls remove
.sp
Return a list containing the removed packages:
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.refresh_db()
Updates the portage tree (emerge \-\-sync)
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.remove(pkg)
Remove a single package via emerge \-\-unmerge
.sp
Return a list containing the names of the removed packages:
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.update(pkg, refresh=False)
Updates the passed package (emerge \-\-update package)
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
        \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.update <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.upgrade(refresh=False)
Run a full system upgrade (emerge \-\-update world)
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
        \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.version(name)
Returns a version if the package is installed, else returns an empty string
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
.ft P
.fi
.UNINDENT
.SS salt.modules.file
.sp
Manage information about files on the minion, set/read user, group, and mode
data
.INDENT 0.0
.TP
.B salt.modules.file.append(path, *args)
Append text to the end of a file
.sp
Usage:
.sp
.nf
.ft C
salt \(aq*\(aq file.append /etc/motd \e
        "With all thine offerings thou shalt offer salt."\e
        "Salt is what makes things taste bad when it isn\(aqt in them."
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.chgrp(path, group)
Change the group of a file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.chgrp /etc/passwd root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.chown(path, user, group)
Chown a file, pass the file the desired user and group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.chown /etc/passwd root root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.comment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq)
Comment out specified lines in a file
.INDENT 7.0
.TP
.B path
The full path to the file to be edited
.TP
.B 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 \fB^\fP or \fB$\fP characters outside the parenthesis
(e.g., the pattern \fB^foo$\fP will be rewritten as \fB^(foo)$\fP)
.TP
.B char
\fB#\fP
The character to be inserted at the beginning of a line in order to
comment it out
.TP
.B backup
\fB.bak\fP
The file will be backed up before edit with this file extension
.IP Warning
This backup will be overwritten each time \fBsed\fP / \fBcomment\fP /
\fBuncomment\fP is called. Meaning the backup will only be useful
after the first invocation.
.RE
.UNINDENT
.sp
Usage:
.sp
.nf
.ft C
salt \(aq*\(aq file.comment /etc/modules pcspkr
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.contains(path, text, limit=\(aq\(aq)
Return True if the file at \fBpath\fP contains \fBtext\fP
.sp
Usage:
.sp
.nf
.ft C
salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.find(path, *opts)
Approximate the Unix find(1) command and return a list of paths that
meet the specified critera.
.sp
The options include match criteria:
.sp
.nf
.ft C
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
.ft P
.fi
.sp
and/or actions:
.sp
.nf
.ft C
delete [= file\-types]               # default type = \(aqf\(aq
exec    = command [arg ...]         # where {} is replaced by pathname
print  [= print\-opts]
.ft P
.fi
.sp
The default action is \(aqprint=path\(aq.
.sp
file\-glob:
.sp
.nf
.ft C
*                = 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
.ft P
.fi
.sp
path\-regex: a Python re (regular expression) pattern to match pathnames
.sp
file\-types: a string of one or more of the following:
.sp
.nf
.ft C
a: all file types
b: block device
c: character device
d: directory
p: FIFO (named pipe)
f: plain file
l: symlink
s: socket
.ft P
.fi
.sp
users: a space and/or comma separated list of user names and/or uids
.sp
groups: a space and/or comma separated list of group names and/or gids
.sp
size\-unit:
.sp
.nf
.ft C
b: bytes
k: kilobytes
m: megabytes
g: gigabytes
t: terabytes
.ft P
.fi
.sp
interval:
.sp
.nf
.ft C
[<num>w] [<num>[d]] [<num>h] [<num>m] [<num>s]

where:
    w: week
    d: day
    h: hour
    m: minute
    s: second
.ft P
.fi
.sp
print\-opts: a comma and/or space separated list of one or more of the
following:
.sp
.nf
.ft C
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
.ft P
.fi
.sp
CLI Examples:
.sp
.nf
.ft C
salt \(aq*\(aq file.find / type=f name=\e*.bak size=+10m
salt \(aq*\(aq file.find /var mtime=+30d size=+10m print=path,size,mtime
salt \(aq*\(aq file.find /var/log name=\e*.[0\-9] mtime=+30d size=+10m delete
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_gid(path)
Return the id of the group that owns a given file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.get_gid /etc/passwd
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_group(path)
Return the group that owns a given file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.get_group /etc/passwd
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_mode(path)
Return the mode of a file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.get_mode /etc/passwd
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_sum(path, form=\(aqmd5\(aq)
Return the sum for the given file, default is md5, sha1, sha224, sha256,
sha384, sha512 are supported
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.get_sum /etc/passwd sha512
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_uid(path)
Return the id of the user that owns a given file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.get_uid /etc/passwd
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_user(path)
Return the user that owns a given file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.get_user /etc/passwd
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.gid_to_group(gid)
Convert the group id to the group name on this system
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.gid_to_group 0
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.group_to_gid(group)
Convert the group to the gid on this system
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.group_to_gid root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.sed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, options=\(aq\-r \-e\(aq, flags=\(aqg\(aq)
Make a simple edit to a file
.sp
Equivalent to:
.sp
.nf
.ft C
sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"
.ft P
.fi
.INDENT 7.0
.TP
.B path
The full path to the file to be edited
.TP
.B before
A pattern to find in order to replace with \fBafter\fP
.TP
.B after
Text that will replace \fBbefore\fP
.TP
.B limit
\fB\(aq\(aq\fP
An initial pattern to search for before searching for \fBbefore\fP
.TP
.B backup
\fB.bak\fP
The file will be backed up before edit with this file extension;
\fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will
overwrite this backup
.TP
.B options
\fB\-r \-e\fP
Options to pass to sed
.TP
.B flags
\fBg\fP
Flags to modify the sed search; e.g., \fBi\fP for case\-insensitve pattern
matching
.UNINDENT
.sp
Forward slashes and single quotes will be escaped automatically in the
\fBbefore\fP and \fBafter\fP patterns.
.sp
Usage:
.sp
.nf
.ft C
salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.set_mode(path, mode)
Set the mode of a file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.set_mode /etc/passwd 0644
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.touch(name, atime=None, mtime=None)
Just like \(aqnix\(aqs "touch" command, create a file if it
doesn\(aqt exist or simply update the atime and mtime if
it already does.
.INDENT 7.0
.TP
.B atime:
Access time in Unix epoch time
.TP
.B mtime:
Last modification in Unix epoch time
.TP
.B Usage::
salt \(aq*\(aq file.touch /var/log/emptyfile
.UNINDENT
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.uid_to_user(uid)
Convert a uid to a user name
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.uid_to_user 0
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.uncomment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq)
Uncomment specified commented lines in a file
.INDENT 7.0
.TP
.B path
The full path to the file to be edited
.TP
.B regex
A regular expression used to find the lines that are to be uncommented.
This regex should not include the comment character. A leading \fB^\fP
character will be stripped for convenience (for easily switching
between comment() and uncomment()).
.TP
.B char
\fB#\fP
The character to remove in order to uncomment a line; if a single
whitespace character follows the comment it will also be removed
.TP
.B backup
\fB.bak\fP
The file will be backed up before edit with this file extension;
\fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will
overwrite this backup
.UNINDENT
.sp
Usage:
.sp
.nf
.ft C
salt \(aq*\(aq file.uncomment /etc/hosts.deny \(aqALL: PARANOID\(aq
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.user_to_uid(user)
Convert user name to a uid
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq file.user_to_uid root
.ft P
.fi
.UNINDENT
.SS salt.modules.freebsdpkg
.sp
Package support for FreeBSD
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.available_version(name)
The available version of the package in the repository
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.available_version <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.install(name, **kwargs)
Install the passed package
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
           \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.list_pkgs()
List the packages currently installed as a dict:
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.purge(name)
Remove a single package with pkg_delete
.sp
Returns a list containing the removed packages.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.refresh_db()
Update the ports tree with portsnap. If the ports tree does not exist it
will be downloaded and set up.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.remove(name)
Remove a single package with pkg_delete
.sp
Returns a list containing the removed packages.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.upgrade()
Run a full system upgrade, a \fBfreebsd\-update fetch install\fP
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
           \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.version(name)
Returns a version if the package is installed, else returns an empty string
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
.ft P
.fi
.UNINDENT
.SS salt.modules.grains
.sp
Control aspects of the grains data
.INDENT 0.0
.TP
.B salt.modules.grains.item(key=None)
Return a singe component of the grains data
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq grains.item os
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.items()
Return the grains data
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq grains.items
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.ls()
Return a list of all available grains
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq grains.ls
.ft P
.fi
.UNINDENT
.SS salt.modules.groupadd
.sp
Manage groups on Linux
.INDENT 0.0
.TP
.B salt.modules.groupadd.add(name, gid=None)
Add the specified group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.add foo 3456
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.chgid(name, gid)
Change the gid for a named group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.chgid foo 4376
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.delete(name)
Remove the named group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.delete foo
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.getent()
Return info on all groups
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.getent
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.info(name)
Return information about a group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.info foo
.ft P
.fi
.UNINDENT
.SS salt.modules.hosts
.sp
Manage the information in the hosts file
.INDENT 0.0
.TP
.B 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
.INDENT 7.0
.TP
.B CLI Example::
salt \(aq*\(aq hosts.add_host <ip> <alias>
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.get_alias(ip)
Return the list of aliases associated with an ip
.INDENT 7.0
.TP
.B CLI Example::
salt \(aq*\(aq hosts.get_alias <ip addr>
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.get_ip(host)
Return the ip associated with the named host
.INDENT 7.0
.TP
.B CLI Example::
salt \(aq*\(aq hosts.get_ip <hostname>
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.has_pair(ip, alias)
Return true if the alias is set
.INDENT 7.0
.TP
.B CLI Example::
salt \(aq*\(aq hosts.has_pair <ip> <alias>
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.list_hosts()
Return the hosts found in the hosts file in this format:
.sp
.nf
.ft C
{\(aq<ip addr>\(aq: [\(aqalias1\(aq, \(aqalias2\(aq, ...]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq hosts.list_hosts
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.rm_host(ip, alias)
Remove a host entry from the hosts file
.INDENT 7.0
.TP
.B CLI Example::
salt \(aq*\(aq hosts.rm_host <ip> <alias>
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B 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
.INDENT 7.0
.TP
.B CLI Example::
salt \(aq*\(aq hosts.set_host <ip> <alias>
.UNINDENT
.UNINDENT
.SS salt.modules.kmod
.sp
Module to manage Linux kernel modules
.INDENT 0.0
.TP
.B salt.modules.kmod.available()
Return a list of all available kernel modules
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq kmod.available
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.check_available(mod)
Check to see if the specified kernel module is available
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq kmod.check_available kvm
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.load(mod)
Load the specified kernel module
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq kmod.load kvm
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.lsmod()
Return a dict containing information about currently loaded modules
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq kmod.lsmod
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.remove(mod)
Remove the specified kernel module
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq kmod.remove kvm
.ft P
.fi
.UNINDENT
.SS salt.modules.linux_sysctl
.sp
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.sp
CLI Example:
salt \(aq*\(aq sysctl.assign net.ipv4.ip_forward 1
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.get(name)
Return a single sysctl parameter for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.get net.ipv4.ip_forward
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq)
Assign and persist a simple sysctl parameter for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.persist net.ipv4.ip_forward 1
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.show()
Return a list of sysctl parameters for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.show
.ft P
.fi
.UNINDENT
.SS salt.modules.mdadm
.sp
Salt module to manage RAID arrays with mdadm
.INDENT 0.0
.TP
.B salt.modules.mdadm.detail(device=\(aq/dev/md0\(aq)
Show detail for a specified RAID device
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq raid.detail \(aq/dev/md0\(aq
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mdadm.list()
List the RAID devices.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq raid.list
.ft P
.fi
.UNINDENT
.SS salt.modules.moosefs
.sp
Module for gathering and managing information about MooseFS
.INDENT 0.0
.TP
.B salt.modules.moosefs.dirinfo(path, opts=None)
Return information on a directory located on the Moose
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq moosefs.dirinfo /path/to/dir/ [\-[n][h|H]]
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.moosefs.fileinfo(path)
Return information on a file located on the Moose
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq moosefs.fileinfo /path/to/dir/
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.moosefs.getgoal(path, opts=None)
Return goal(s) for a file or directory
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq moosefs.getgoal /path/to/file [\-[n][h|H]]
salt \(aq*\(aq moosefs.getgoal /path/to/dir/ [\-[n][h|H][r]]
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.moosefs.mounts()
Return a list of current MooseFS mounts
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq moosefs.mounts
.ft P
.fi
.UNINDENT
.SS salt.modules.mount
.sp
Salt module to manage unix mounts and the fstab file
.INDENT 0.0
.TP
.B salt.modules.mount.active()
List the active mounts.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq mount.active
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.fstab(config=\(aq/etc/fstab\(aq)
List the contents of the fstab
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq mount.fstab
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.is_fuse_exec(cmd)
Returns true if the command passed is a fuse mountable application.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq mount.is_fuse_exec sshfs
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.mount(name, device, mkmnt=False, fstype=\(aq\(aq, opts=\(aqdefaults\(aq)
Mount a device
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq mount.mount /mnt/foo /dev/sdz1 True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.remount(name, device, mkmnt=False, fstype=\(aq\(aq, opts=\(aqdefaults\(aq)
Attempt to remount a device, if the device is not already mounted, mount
is called
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq mount.remount /mnt/foo /dev/sdz1 True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.rm_fstab(name, config=\(aq/etc/fstab\(aq)
Remove the mount point from the fstab
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq /mnt/foo
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.set_fstab(name, device, fstype, opts=\(aqdefaults\(aq, dump=0, pass_num=0, config=\(aq/etc/fstab\(aq)
Verify that this mount is represented in the fstab, chage the mount point
to match the data passed, or add the mount if it is not present.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq mount.set_fstab /mnt/foo /dev/sdz1 ext4
.ft P
.fi
.UNINDENT
.SS salt.modules.network
.sp
Module for gathering and managing network information
.INDENT 0.0
.TP
.B salt.modules.network.dig(host)
Performs a DNS lookup with dig
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq network.dig archlinux.org
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.isportopen(host, port)
Return status of a port
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq network.isportopen 127.0.0.1 22
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.netstat()
Return information on open ports and states
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq network.netstat
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.ping(host)
Performs a ping to a host
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq network.ping archlinux.org \-c 4
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.traceroute(host)
Performs a traceroute to a 3rd party host
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq network.traceroute archlinux.org
.ft P
.fi
.UNINDENT
.SS salt.modules.pacman
.sp
A module to wrap pacman calls, since Arch is the best
(\fI\%https://wiki.archlinux.org/index.php/Arch_is_the_best\fP)
.INDENT 0.0
.TP
.B salt.modules.pacman.available_version(name)
The available version of the package in the repository
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.available_version <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.install(name, refresh=False, **kwargs)
Install the passed package, add refresh=True to install with an \-Sy
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
           \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.list_pkgs()
List the packages currently installed as a dict:
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.purge(name)
Recursively remove a package and all dependencies which were installed
with it, this will call a \fBpacman \-Rsc\fP
.sp
Return a list containing the removed packages.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.refresh_db()
Just run a \fBpacman \-Sy\fP, return a dict:
.sp
.nf
.ft C
{\(aq<database name>\(aq: Bool}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.remove(name)
Remove a single package with \fBpacman \-R\fP
.sp
Return a list containing the removed packages.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.upgrade()
Run a full system upgrade, a pacman \-Syu
.sp
Return a dict containing the new package names and versions:
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
           \(aqnew\(aq: \(aq<new\-version>\(aq]}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.version(name)
Returns a version if the package is installed, else returns an empty string
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
.ft P
.fi
.UNINDENT
.SS salt.modules.puppet
.sp
Execute puppet routines
.INDENT 0.0
.TP
.B salt.modules.puppet.run()
Execute a puppet run and return a dict with the stderr,stdout,return code
etc.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq puppet.run
.ft P
.fi
.UNINDENT
.SS salt.modules.pw_group
.sp
Manage groups on Linux
.INDENT 0.0
.TP
.B salt.modules.pw_group.add(name, gid=None)
Add the specified group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.add foo 3456
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.chgid(name, gid)
Change the gid for a named group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.chgid foo 4376
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.delete(name)
Remove the named group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.delete foo
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.getent()
Return info on all groups
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.getent
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.info(name)
Return information about a group
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq group.info foo
.ft P
.fi
.UNINDENT
.SS salt.modules.pw_user
.sp
Manage users with the useradd command
.INDENT 0.0
.TP
.B salt.modules.pw_user.add(name, uid=None, gid=None, groups=None, home=False, shell=\(aq/bin/false\(aq)
Add a user to the minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chgid(name, gid)
Change the default group of the user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chgid foo 4376
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chgroups(name, groups, append=False)
Change the groups this user belongs to, add append to append the specified
groups
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chgroups foo wheel,root True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chhome foo /home/users/foo True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chshell(name, shell)
Change the default shell of the user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chshell foo /bin/zsh
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chuid(name, uid)
Change the uid for a named user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chuid foo 4376
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.delete(name, remove=False, force=False)
Remove a user from the minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.delete name True True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.getent()
Return the list of all info for all users
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.getent
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.info(name)
Return user information
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.info root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.list_groups(name)
Return a list of groups the named user belongs to
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.groups foo
.ft P
.fi
.UNINDENT
.SS salt.modules.selinux
.sp
Execute calls on selinux
.INDENT 0.0
.TP
.B salt.modules.selinux.getenforce()
Return the mode selinux is running in
.sp
CLE Example:
.sp
.nf
.ft C
salt \(aq*\(aq selinux.getenforce
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.setenforce(mode)
Set the enforcing mode
.UNINDENT
.SS salt.modules.service
.sp
The default service module, if not otherwise specified salt will fall back
to this basic module
.INDENT 0.0
.TP
.B salt.modules.service.restart(name)
Restart the named service
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.start(name)
Start the specified service
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name> [service signature]
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.stop(name)
Stop the specified service
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.SS salt.modules.shadow
.sp
Manage the shadow file
.INDENT 0.0
.TP
.B salt.modules.shadow.info(name)
Return information for the specified user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq shadow.info root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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:
\fBopenssl passwd \-1 <plaintext password>\fP
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_password root $1$UYCIxa628.9qXjpQCjM4a..
.ft P
.fi
.UNINDENT
.SS salt.modules.solr
.SS Apache Solr Salt Module
.sp
Author: Jed Glazner
Version: 0.2.1
Modified: 12/09/2011
.sp
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\(aqt
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.
.sp
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.
.SS Coming Features in 0.3
.INDENT 0.0
.IP 1. 3
Add command for checking for replication failures on slaves
.IP 2. 3
Improve match_index_versions since it\(aqs pointless on busy solr masters
.IP 3. 3
Add additional local fs checks for backups to make sure they succeeded
.UNINDENT
.SS Override these in the minion config
.INDENT 0.0
.TP
.B solr.cores
A list of core names eg [\(aqcore1\(aq,\(aqcore2\(aq].
An empty list indicates non\-multicore setup.
.TP
.B solr.baseurl
The root level url to access solr via http
.TP
.B 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.
.TP
.B solr.type
Possible values are \(aqmaster\(aq or \(aqslave\(aq
.TP
.B 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.
.TP
.B 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.
.TP
.B solr.init_script
The full path to your init script with start/stop options
.TP
.B solr.dih.options
A list of options to pass to the dih.
.UNINDENT
.SS Required Options for DIH
.INDENT 0.0
.TP
.B clean
False
Clear the index before importing
.TP
.B commit
True
Commit the documents to the index upon completion
.TP
.B optimize
True
Optimize the index after commit is complete
.TP
.B verbose
True
Get verbose output
.UNINDENT
.INDENT 0.0
.TP
.B 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
.INDENT 7.0
.TP
.B handler
str
The name of the data import handler.
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B core
str (None)
The core the handler belongs to.
.TP
.B verbose
boolean (False)
Run the command with verbose output.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.abort_import dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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: \(aqOK\(aq in the response simply means that solr received the
request successfully.
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.backup music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B core_name
str
The name of the core to reload
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.core_status None music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solr.delta_import(handler, host=None, core_name=None, options={}, extra=[])
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
.INDENT 7.0
.TP
.B handler
str
The name of the data import handler.
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B core
str (None)
The core the handler belongs to.
.TP
.B 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__
.TP
.B extra
dict ([])
Extra name value pairs to pass to the handler. eg ["name=value"]
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.delta_import dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solr.full_import(handler, host=None, core_name=None, options={}, extra=[])
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
.INDENT 7.0
.TP
.B handler
str
The name of the data import handler.
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B core
str (None)
The core the handler belongs to.
.TP
.B 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__
.TP
.B extra
dict ([])
Extra name value pairs to pass to the handler. e.g. ["name=value"]
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.full_import dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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: \(aqmaster\(aq
.INDENT 7.0
.TP
.B handler
str
The name of the data import handler.
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B core
str (None)
The core the handler belongs to.
.TP
.B verbose
boolean (False)
Specifies verbose output
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.import_status dataimport None music False
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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.
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.is_replication_enabled music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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.
.INDENT 7.0
.TP
.B 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.
.UNINDENT
.sp
Return: dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.lucene_version
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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.
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.match_index_versions music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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.
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.optimize music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solr.ping(host=None, core_name=None)
Does a health check on solr, makes sure solr can talk to the indexes.
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.ping music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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.
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B core_name
str
The name of the core to reload
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.reload_core None music

{\(aqsuccess\(aq:bool, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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 \(aqmaster\(aq type
.INDENT 7.0
.TP
.B handler
str
The name of the data import handler.
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B core
str (None)
The core the handler belongs to.
.TP
.B verbose
boolean (False)
Run the command with verbose output.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.reload_import_config dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solr.replication_details(host=None, core_name=None)
Get the full replication details.
.INDENT 7.0
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.replication_details music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solr.set_is_polling(polling, host=None, core_name=None)
SLAVE CALL
Prevent the slaves from polling the master for updates.
.INDENT 7.0
.TP
.B polling
boolean
True will enable polling. False will disable it.
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.set_is_polling False
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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\(aqt want the slaves replicating during indexing or when clearing the
index.
.INDENT 7.0
.TP
.B status
boolean
Sets the replication status to the specified state.
.TP
.B host
str (None)
The solr host to query. __opts__[\(aqhost\(aq] is default.
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.set_replication_enabled false, None, music
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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\(aqt ship with an init script so one must be created.
.INDENT 7.0
.TP
.B signal
str (None)
The command to pass to the apache solr init valid values are \(aqstart\(aq,
\(aqstop\(aq, and \(aqrestart\(aq
.UNINDENT
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq solr.signal restart
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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.
.INDENT 7.0
.TP
.B 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.
.UNINDENT
.sp
Return : dict<str,obj>:
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
alt \(aq*\(aq solr.version
.ft P
.fi
.UNINDENT
.SS salt.modules.ssh
.sp
Manage client ssh components
.INDENT 0.0
.TP
.B salt.modules.ssh.auth_keys(user, config=\(aq.ssh/authorized_keys\(aq)
Return the authorized keys for the specified user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq ssh.auth_keys root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.host_keys(keydir=None)
Return the minion\(aqs host keys
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq ssh.host_keys
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.rm_auth_key(user, key, config=\(aq.ssh/authorized_keys\(aq)
Remove an authorized key from the specified user\(aqs authorized key file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq ssh.rm_auth_key <user> <key>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.set_auth_key(user, key, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, options=[], config=\(aq.ssh/authorized_keys\(aq)
Add a key to the authorized_keys file
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq ssh.set_auth_key <user> <key> dsa \(aq[]\(aq .ssh/authorized_keys
.ft P
.fi
.UNINDENT
.SS salt.modules.status
.sp
Module for returning various status data about a minion.
These data can be useful for compiling into stats later.
.INDENT 0.0
.TP
.B salt.modules.status.all_status()
Return a composite of all status data and info for this minion.
Warning: There is a LOT here!
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.all_status
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.cpuinfo()
Return the CPU info for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.cpuinfo
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.cpustats()
Return the CPU stats for this minon
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.cpustats
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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:
.sp
.nf
.ft C
status.cpustats.custom: [ \(aqcpu\(aq, \(aqctxt\(aq, \(aqbtime\(aq, \(aqprocesses\(aq ]
.ft P
.fi
.sp
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.
.sp
This function is meant to replace all_status(), which returns
anything and everything, which we probably don\(aqt want.
.sp
By default, nothing is returned. Warning: Depending on what you
include, there can be a LOT here!
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.custom
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.diskstats()
Return the disk stats for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.diskstats
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.diskusage(*args)
Return the disk usage for this minion
.sp
Usage:
.sp
.nf
.ft C
salt \(aq*\(aq status.diskusage [paths and/or filesystem types]
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.diskusage         # usage for all filesystems
salt \(aq*\(aq status.diskusage / /tmp  # usage for / and /tmp
salt \(aq*\(aq status.diskusage ext?    # usage for ext[234] filesystems
salt \(aq*\(aq status.diskusage / ext?  # usage for / and all ext filesystems
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.loadavg()
Return the load averages for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.loadavg
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.meminfo()
Return the CPU stats for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.meminfo
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.netdev()
Return the network device stats for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.netdev
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.netstats()
Return the network stats for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.netstats
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.uptime()
Return the uptime for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.uptime
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.vmstats()
Return the virtual memory stats for this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.vmstats
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.w()
Return a list of logged in users for this minion, using the w command
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq status.w
.ft P
.fi
.UNINDENT
.SS salt.modules.test
.sp
Module for running arbitrary tests
.INDENT 0.0
.TP
.B 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.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.collatz 3
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.conf_test()
Return the value for test.foo in the minion configuration file, or return
the default value
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.conf_test
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.cross_test(func, args=[])
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
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.cross_test file.gid_to_group 0
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.echo(text)
Return a string \- used for testing the connection
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.echo \(aqfoo bar baz quo qux\(aq
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.fib(num)
Return a Fibonacci sequence up to the passed number, and the time it took
to compute in seconds. Used for performance tests
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.fib 3
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.get_opts()
Return the configuration options passed to this minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.get_opts
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.outputter(data)
Test the outputter, pass in data to return
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.outputter foobar
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.ping()
Just used to make sure the minion is up and responding
Return True
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.version()
Return the version of salt on the minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq test.version
.ft P
.fi
.UNINDENT
.SS salt.modules.tomcat
.sp
Support for Tomcat
.INDENT 0.0
.TP
.B salt.modules.tomcat.fullversion()
Return all server information from catalina.sh version
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.fullversion
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.signal(signal=None)
Signals catalina to start, stop, securestart, forcestop.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.signal start
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.version()
Return server version from catalina.sh version
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.version
.ft P
.fi
.UNINDENT
.SS salt.modules.useradd
.sp
Manage users with the useradd command
.INDENT 0.0
.TP
.B salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=False, shell=\(aq/bin/false\(aq)
Add a user to the minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chgid(name, gid)
Change the default group of the user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chgid foo 4376
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chgroups(name, groups, append=False)
Change the groups this user belongs to, add append to append the specified
groups
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chgroups foo wheel,root True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chhome foo /home/users/foo True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chshell(name, shell)
Change the default shell of the user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chshell foo /bin/zsh
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chuid(name, uid)
Change the uid for a named user
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.chuid foo 4376
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.delete(name, remove=False, force=False)
Remove a user from the minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.delete name True True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.getent()
Return the list of all info for all users
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.getent
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.info(name)
Return user information
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.info root
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.list_groups(name)
Return a list of groups the named user belongs to
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq user.groups foo
.ft P
.fi
.UNINDENT
.SS salt.modules.virt
.sp
Work with virtual machines managed by libvirt
.INDENT 0.0
.TP
.B salt.modules.virt.create(vm_)
Start a defined domain
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.create <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.create_xml_path(path)
Start a defined domain
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.create_xml_path <path to xml file on the node>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.create_xml_str(xml)
Start a domain based on the xml passed to the function
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.create_xml_str <xml in string format>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.destroy(vm_)
Hard power down the virtual machine, this is equivalent to pulling the
power
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.destroy <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.freecpu()
Return an int representing the number of unallocated cpus on this
hypervisor
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.freemem
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.freemem()
Return an int representing the amount of memory that has not been given
to virtual machines on this node
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.freemem
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.full_info()
Return the node_info, vm_info and freemem
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.full_info
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_disks(vm_)
Return the disks of a named vm
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_disks <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_graphics(vm_)
Returns the information on vnc for a given vm
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_graphics <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_xml(vm_)
Returns the xml for a given vm
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_xml <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.is_kvm_hyper()
Returns a bool whether or not this node is a hypervisor
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.is_kvm_hyper
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.list_vms()
Return a list of virtual machine names on the minion
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_vms
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.migrate(vm_, target)
Shared storage migration
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.migrate <vm name> <target hypervisor>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.migrate_non_shared(vm_, target)
Attempt to execute non\-shared storage "all" migration
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.migrate_non_shared <vm name> <target hypervisor>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.migrate_non_shared_inc(vm_, target)
Attempt to execute non\-shared storage "all" migration
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.migrate_non_shared_inc <vm name> <target hypervisor>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.node_info()
Return a dict with information about this node
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.node_info
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.pause(vm_)
Pause the named vm
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.pause <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.purge(vm_, dirs=False)
Recursively destroy and delete a virtual machine, pass True for dir\(aqs to
also delete the directories containing the virtual machine disk images \-
USE WITH EXTREME CAUTION!
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.purge <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.resume(vm_)
Resume the named vm
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.resume <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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.
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.seed_non_shared_migrate <disks>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.set_autostart(vm_, state=\(aqon\(aq)
Set the autostart flag on a VM so that the VM will start with the host
system on reboot.
.INDENT 7.0
.TP
.B CLI Example::
salt "*" virt.enable_autostart <vm name> <on | off>
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.shutdown(vm_)
Send a soft shutdown signal to the named vm
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.shutdown <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B 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
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.undefine <vm name>
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.virt_type()
Returns the virtual machine type as a string
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.virt_type
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.vm_info()
Return detailed information about the vms on this hyper in a dict:
.sp
.nf
.ft C
{\(aqcpu\(aq: <int>,
\(aqmaxMem\(aq: <int>,
\(aqmem\(aq: <int>,
\(aqstate\(aq: \(aq<state>\(aq,
\(aqcputime\(aq <int>}
.ft P
.fi
.sp
CLI Example:
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_info
.ft P
.fi
.UNINDENT
.SH GRAINS
.sp
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.
.sp
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.
.sp
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.
.SS Writing Grains
.sp
Grains are easy to write, the grains interface is derived my executing all of
the "public" functions found in the modules located in the grains package.
The functions in the modules of the grains must return a python dict, the keys
in the dict are the names of the grains, the values are the values.
.sp
This means that the actual grains interface is simply a python dict.
.sp
Before adding a grain to salt, consider what the grain is and remember that
grains need to be static data.
.SS Examples of Grains
.sp
The core module in the grains package is where the main grains are loaded by
the salt minion and the principal example of how to write grains:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/grains/core.py\fP
.SH RETURNERS
.sp
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 detatched from the call on the salt master, there is no need for
the minion to return the data to the salt master.
.sp
This is where the returner interface comes in. Returners are modules called
in place of returning the data to the salt master.
.sp
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!
.IP "See also"
.sp
\fIFull list of builtin returners\fP
.RE
.SS Writing a Returner
.sp
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 \fBtest.ping\fP is called
the value of the argument will be \fBTrue\fP.
.sp
A simple returner is implimented here:
.sp
.nf
.ft C
import redis
import json

def returner(ret):
    \(aq\(aq\(aq
    Return information to a redis server
    \(aq\(aq\(aq
    # Get a redis commection
    serv = redis.Redis(
                host=\(aqredis\-serv.example.com\(aq,
                port=6379,
                db=\(aq0\(aq)
    serv.sadd("%(id)s:jobs" % ret, ret[\(aqjid\(aq])
    serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret[\(aqreturn\(aq]))
    serv.sadd(\(aqjobs\(aq, ret[\(aqjid\(aq])
    serv.sadd(ret[\(aqjid\(aq], ret[\(aqid\(aq])
.ft P
.fi
.sp
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.
.SS Examples
.sp
The collection of builtin salt returners can be found here:
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/returners\fP
.SH FULL LIST OF BUILTIN RETURNERS
.TS
center;
|l|l|.
_
T{
\fBlocal\fP
T}	T{
The local returner is used to test the returner interface, it just prints the
T}
_
T{
\fBmongo_return\fP
T}	T{
T}
_
T{
\fBredis_return\fP
T}	T{
T}
_
.TE
.SS salt.returners.local
.sp
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
.INDENT 0.0
.TP
.B salt.returners.local.returner(ret)
Print the return data to the terminal to verify functionality
.UNINDENT
.SH FAILHARD GLOBAL OPTION
.sp
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.
.sp
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
\fBfailing hard\fP.
.SS State Level Failhard
.sp
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:
.sp
.nf
.ft C
/etc/yum.repos.d/company.repo:
  file:
    \- managed
    \- source: salt://company/yumrepo.conf
    \- user: root
    \- group: root
    \- mode: 644
    \- order: 1
    \- failhard: True
.ft P
.fi
.sp
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.
.SS Global Failhard
.sp
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.
.sp
This is NOT the default behavior, normally Salt will only fail states that
require a failed state.
.sp
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.
.sp
To use the global failhard set failhard: True in the master configuration
file.
.SH HIGHSTATE DATA STRUCTURE DEFINITIONS
.SS The Salt State Tree
.INDENT 0.0
.TP
.B Top file
The main state file that instructs minions what environment and modules
to use during state execution.
.sp
Configurable via \fBstate_top\fP.
.TP
.B State tree
A collection of \fBsls\fP files.
.UNINDENT
.SS Include declaration
.INDENT 0.0
.TP
.B Include declaration
Defines a list of \fImodule reference\fP strings to include in this
\fIsls\fP.
.sp
Occurs only in the top level of the highstate structure.
.sp
Example:
.sp
.nf
.ft C
include:
  \- edit.vim
  \- http.server
.ft P
.fi
.UNINDENT
.SS Module reference
.INDENT 0.0
.TP
.B Module reference
The name of a SLS module defined by a separate SLS file and residing on
the Salt Master. A module named \fBedit.vim\fP is a reference to the sls
file \fBsalt://edit/vim.sls\fP.
.UNINDENT
.SS ID declaration
.INDENT 0.0
.TP
.B ID declaration
Defines an individual highstate component. Always references a value of
a dictionary containing keys referencing \fIstate declarations\fP and \fIrequisite declarations\fP. Can be overridden by a \fIname declaration\fP or a
\fInames declaration\fP.
.sp
Occurs on the top level or under the \fIextend declaration\fP.
.UNINDENT
.SS Extend declaration
.INDENT 0.0
.TP
.B Extend declaration
Used to extend a \fIname declaration\fP from an included \fBsls
module\fP. The keys of the extend declaration always define existing
\fIID declarations\fP which have been defined in
included \fBsls modules\fP.
.sp
Occurs only in the top level and defines a dictionary.
.UNINDENT
.SS State declaration
.INDENT 0.0
.TP
.B State declaration
A list which contains one string defining the \fIfunction
declaration\fP and any number of \fIfunction arg declaration\fP
dictionaries.
.sp
Can, optionally, contain a number of additional components like the
name override components — \fIname\fP and
\fInames\fP. Can also contain \fIrequisite
declarations\fP.
.sp
Occurs under an \fIID declaration\fP.
.UNINDENT
.SS Requisite declaration
.INDENT 0.0
.TP
.B Requisite declaration
A list containing \fIrequisite references\fP.
.sp
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.
.sp
Occurs as a list component under a \fIstate declaration\fP or as a
key under an \fIID declaration\fP.
.UNINDENT
.SS Requisite reference
.INDENT 0.0
.TP
.B Requisite reference
A single key dictionary. The key is the name of the referenced
\fIstate declaration\fP and the value is the ID of the referenced
\fIID declaration\fP.
.sp
Occurs as a single index in a \fIrequisite declaration\fP list.
.UNINDENT
.SS Function declaration
.INDENT 0.0
.TP
.B Function declaration
The name of the function to call within the state. Any given state
declaration can only have a single function.
.sp
Occurs as the only index in the \fIstate declaration\fP list.
.UNINDENT
.SS Function arg declaration
.INDENT 0.0
.TP
.B Function arg declaration
A single key dictionary referencing a Python type which is to be passed
to the named \fIfunction declaration\fP as a parameter. The type must
be the data type expected by the function.
.sp
Occurs under a \fIfunction declaration\fP.
.UNINDENT
.SS Name declaration
.INDENT 0.0
.TP
.B Name declaration
Used to override the name argument relative the \fIstate
declaration\fP. If the name is not specified then the \fIID
declaration\fP satisfies the name argument. The name is always a single
key dictionary referencing a string.
.UNINDENT
.SS Names declaration
.INDENT 0.0
.TP
.B Names declaration
Used to apply the contents of the \fIstate declaration\fP to multiple
states, each with its own name.
.sp
Example:
.sp
.nf
.ft C
python\-pkgs:
  pkg:
    \- installed
    \- names:
      \- python\-django
      \- python\-crypto
      \- python\-yaml
.ft P
.fi
.UNINDENT
.SS Large example
.sp
Here is the layout in yaml using the names of the highdata structure
components.
.sp
.nf
.ft C
<Include Declaration>:
  \- <Module Reference>
  \- <Module Reference>
<Extend Declaration>:
  <ID Declaration>:
    <State Declaration>:
      \- <Function>
      \- <Function Arg>
      \- <Function Arg>
      \- <Function Arg>
      \- <Name>: <name>
      \- <Requisite Declaration>:
        \- <Requisite Reference>
        \- <Requisite Reference>
  <ID Declaration>:
    <State Declaration>:
      \- <Function>
      \- <Function Arg>
      \- <Function Arg>
      \- <Function Arg>
      \- <Names>:
        \- <name>
        \- <name>
        \- <name>
      \- <Requisite Declaration>:
        \- <Requisite Reference>
        \- <Requisite Reference>
<ID Declaration>:
  <State Declaration>:
    \- <Function>
    \- <Function Arg>
    \- <Function Arg>
    \- <Function Arg>
    \- <Name>
    \- <Requisite Declaration>:
      \- <Requisite Reference>
      \- <Requisite Reference>
<ID Declaration>:
  <State Declaration>:
    \- <Function>
    \- <Function Arg>
    \- <Function Arg>
    \- <Function Arg>
    \- <Names>:
      \- <name>
      \- <name>
      \- <name>
    \- <Requisite Declaration>:
      \- <Requisite Reference>
      \- <Requisite Reference>
.ft P
.fi
.SH STATE ENFORCEMENT
.sp
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.
.sp
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.
.SS State management
.sp
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.
.sp
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.
.sp
Salt States is an extension of the Salt Modules that we discussed in the
previous \fBremote execution\fP tutorial. Instead
of calling one\-off executions the state of a system can be easily defined and
then enforced.
.SS Understanding the Salt State System Components
.sp
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, as well as understanding salt states and how
to write the states used by salt.
.SS Salt SLS System
.INDENT 0.0
.TP
.B sls
The primary system used by the Salt state system is the SLS system. SLS
stands for \fBS\fPa\fBL\fPt \fBS\fPtate.
.sp
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.
.sp
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.
.UNINDENT
.SS SLS File Layout
.sp
SLS files are laid out in the Salt file server. A simple layout can look like
this:
.sp
.nf
.ft C
top.sls
ssh.sls
sshd_config
users/init.sls
users/admin.sls
salt/init.sls
salt/master.sls
.ft P
.fi
.sp
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 \fB.sls\fP files are states. The rest of the files are seen by the salt
master as just files that can be downloaded.
.sp
The states are translated into dot notation, so the \fBssh.sls\fP file is
seen as the ssh state, the \fBusers/admin.sls\fP file is seen as the
users.admin states.
.sp
The init.sls files are translated to be the state name of the parent
directory, so the \fBsalt/init.sls\fP file translates to the salt state.
.sp
The plain files are visible to the minions, as well as the state files, in
salt, everything is a file, there is not "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.
.SS SLS Files
.sp
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 the translate down to yaml, or just
plain and simple yaml files!
.sp
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.
.sp
Here is an example of a Salt State:
.sp
.nf
.ft C
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
.ft P
.fi
.sp
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.
.SS The Top File
.sp
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.
.sp
The top file works by specifying the environment, containing matchers with
lists of Salt states sent to the matching minions:
.sp
.nf
.ft C
base:
    \(aq*\(aq:
        \- salt
        \- users
        \- users.admin
    \(aqsaltmaster.*\(aq:
        \- match: pcre
        \- salt.master
.ft P
.fi
.sp
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 \(aq*\(aq will match all minions. Then the regular expression
matcher will match all minions\(aq with an id matching saltmaster.* and add the
salt.master state.
.SS Renderer System
.sp
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 file.
.sp
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.
.sp
The available renderers can be found in the renderers directory in the Salt
source code:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/renderers\fP
.sp
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.
.sp
In the future xml and raw python will be added, as well as many other formats.
.SH ORDERING STATES
.sp
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 nessisarily defined the way you want it.
.sp
A few tools exist in Salt to set up the corect state ordering, these tools
consist of requisite declarations and order options.
.SS The Order Option
.sp
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.
.sp
The order option is used by adding an order number to a state declaration
with the option \fIorder\fP:
.sp
.nf
.ft C
vim:
  pkg:
    \- installed
    \- order: 1
.ft P
.fi
.sp
By adding the order option to \fI1\fP this ensures that the vim package will be
installed in tandem with any other state declaration set to the order \fI1\fP.
.sp
Any state declared without an order option will be executed after all states
with order options are executed.
.sp
But this construct can only handle ordering states from the beggining.
Sometimes you may want to send a state to the end of the line, to do this
set the order to last:
.sp
.nf
.ft C
vim:
  pkg:
    \- installed
    \- order: last
.ft P
.fi
.SH STATE MODULES
.sp
State Modules are the components that map to actual enforcement and management
of salt states.
.SS States are \- Easy to Write!
.sp
State Modules should be easy to write and straightforward. The information
passed to the SLS data structures will map directly to the states modules.
.sp
Mapping the information from the SLS data is simple, this example should
illustrate:
.sp
SLS file
.. code\-block:: yaml
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B /etc/salt/master: # maps to "name"
.INDENT 7.0
.TP
.B file: # maps to State module filename eg \fI\%https://github.com/saltstack/salt/blob/develop/salt/states/file.py\fP
.INDENT 7.0
.IP \(bu 2
managed # maps to the managed function in the file State module
.IP \(bu 2
user: root # one of many options passed to the manage function
.IP \(bu 2
group: root
.IP \(bu 2
mode: 644
.IP \(bu 2
source: salt://salt/master
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Therefore this SLS data can be directly linked to a module, function and
arguments passed to that function.
.sp
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.
.SS Cross Calling Modules
.sp
As with Execution Modules State Modules can also make use of the \fB__salt__\fP
and \fB__grains__\fP data.
.sp
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.
.sp
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.
.SH FULL LIST OF BUILTIN STATES
.TS
center;
|l|l|.
_
T{
\fBcmd\fP
T}	T{
Command Executions
T}
_
T{
\fBcron\fP
T}	T{
Cron Management
T}
_
T{
\fBfile\fP
T}	T{
File Management
T}
_
T{
\fBgroup\fP
T}	T{
Group Management
T}
_
T{
\fBhost\fP
T}	T{
Hosts File Management
T}
_
T{
\fBkmod\fP
T}	T{
Kernel Module Management
T}
_
T{
\fBmount\fP
T}	T{
Mount Management
T}
_
T{
\fBpkg\fP
T}	T{
Package Management
T}
_
T{
\fBservice\fP
T}	T{
Service Management
T}
_
T{
\fBssh_auth\fP
T}	T{
SSH Authorized Key Management
T}
_
T{
\fBsysctl\fP
T}	T{
Kernel Sysctl Management
T}
_
T{
\fBuser\fP
T}	T{
User Management
T}
_
.TE
.SS salt.states.cmd
.SS Command Executions
.sp
The cmd state module manages the enforcement of executed commands, this
state can tell a command to run under certain circumstances.
.SS Available Functions
.sp
The cmd state only has a single function, the \fBrun\fP function
.INDENT 0.0
.TP
.B run
Execute a command given certain conditions
.sp
A simple example:
.sp
.nf
.ft C
date > /tmp/salt\-run:
cmd:
    \- run
.ft P
.fi
.UNINDENT
.sp
Only run if another execution returns successfully, in this case truncate
syslog if there is no disk space:
.sp
.nf
.ft C
> /var/log/messages:
  cmd:
    \- run
    \- unless: echo \(aqfoo\(aq > /tmp/.test
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.cmd.run(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None)
Run a command if certain circumstances are met
.INDENT 7.0
.TP
.B name
The command to execute, remember that the command will execute with the
path and permissions of the salt\-minion.
.TP
.B onlyif
A command to run as a check, run the named command only if the command
passed to the \fBonlyif\fP option returns true
.TP
.B unless
A command to run as a check, only run the named command if the command
passed to the \fBunless\fP option returns false
.TP
.B cwd
The current working directory to execute the command in, defaults to
/root
.TP
.B user
The user name to run the command as
.TP
.B group
The group context to run the command as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.wait(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None)
Run the given command only if the watch statement calls it
.INDENT 7.0
.TP
.B name
The command to execute, remember that the command will execute with the
path and permissions of the salt\-minion.
.TP
.B onlyif
A command to run as a check, run the named command only if the command
passed to the \fBonlyif\fP option returns true
.TP
.B unless
A command to run as a check, only run the named command if the command
passed to the \fBunless\fP option returns false
.TP
.B cwd
The current working directory to execute the command in, defaults to
/root
.TP
.B user
The user name to run the command as
.TP
.B group
The group context to run the command as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.watcher(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None)
Run a command if certain circumstances are met
.INDENT 7.0
.TP
.B name
The command to execute, remember that the command will execute with the
path and permissions of the salt\-minion.
.TP
.B onlyif
A command to run as a check, run the named command only if the command
passed to the \fBonlyif\fP option returns true
.TP
.B unless
A command to run as a check, only run the named command if the command
passed to the \fBunless\fP option returns false
.TP
.B cwd
The current working directory to execute the command in, defaults to
/root
.TP
.B user
The user name to run the command as
.TP
.B group
The group context to run the command as
.UNINDENT
.UNINDENT
.SS salt.states.cron
.SS Cron Management
.sp
The cron state module allows for user crontabs to be cleanly managed.
.sp
Cron declarations require a number of parameters. The timing parameters, need
to be declared, minute, hour, daymonth, month and dayweek. The  user who\(aqs
crontab is to be edited also needs to be defined.
.sp
By default the timing arguments are all \fB*\fP 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:
.sp
.nf
.ft C
date > /tmp/crontest:
  cron:
    \- present
    \- user: root
    \- minute: 5
.ft P
.fi
.sp
Is changed to this:
.sp
.nf
.ft C
date > /tmp/crontest:
  cron:
    \- present
    \- user: root
    \- minute: 7
    \- hour: 2
.ft P
.fi
.sp
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\(aqs crontab.
.INDENT 0.0
.TP
.B salt.states.cron.absent(name, user=\(aqroot\(aq, minute=\(aq*\(aq, hour=\(aq*\(aq, daymonth=\(aq*\(aq, month=\(aq*\(aq, dayweek=\(aq*\(aq)
Verifies that the specified cron job is absent for the specified user, only
the name is matched when removing a cron job.
.INDENT 7.0
.TP
.B name
The command that should be absent in the user crontab.
.TP
.B user
The name of the user who\(aqs crontab needs to be modified, defaults to
the root user
.TP
.B minute
The information to be set into the minute section, this can be any
string supported by your cron system\(aqs the minute field. Default is
\fB*\fP
.TP
.B hour
The information to be set in the hour section. Default is \fB*\fP
.TP
.B daymonth
The information to be set in the day of month section. Default is \fB*\fP
.TP
.B month
The information to be set in the month section. Default is \fB*\fP
.TP
.B dayweek
The information to be set in the day of day of week section. Default is
\fB*\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cron.present(name, user=\(aqroot\(aq, minute=\(aq*\(aq, hour=\(aq*\(aq, daymonth=\(aq*\(aq, month=\(aq*\(aq, dayweek=\(aq*\(aq)
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\(aqs documentation. Most Unix\-like
systems\(aq cron documentation can be found via the crontab man page:
\fBman 5 crontab\fP.
.INDENT 7.0
.TP
.B name
The command that should be executed by the cron job.
.TP
.B user
The name of the user who\(aqs crontab needs to be modified, defaults to
the root user
.TP
.B minute
The information to be set into the minute section, this can be any
string supported by your cron system\(aqs the minute field. Default is
\fB*\fP
.TP
.B hour
The information to be set in the hour section. Default is \fB*\fP
.TP
.B daymonth
The information to be set in the day of month section. Default is \fB*\fP
.TP
.B month
The information to be set in the month section. Default is \fB*\fP
.TP
.B dayweek
The information to be set in the day of day of week section. Default is
\fB*\fP
.UNINDENT
.UNINDENT
.SS salt.states.file
.SS File Management
.sp
Salt States can aggressively manipulate files on a system. There are a number of
ways in which files can be managed.
.sp
Regular files can be enforced with the \fBmanaged\fP 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 or mako template adding
a dynamic component to file management. An example of \fBfile.managed\fP which
makes use of the jinja templating system would look like this:
.sp
.nf
.ft C
/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
.ft P
.fi
.sp
Directories can be managed via the \fBdirectory\fP function. This function can
create and enforce the permissions on a directory. A directory statement will
look like this:
.sp
.nf
.ft C
/srv/stuff/substuf:
  file:
    \- directory
    \- user: fred
    \- group: users
    \- mode: 755
    \- makedirs: True
.ft P
.fi
.sp
Symlinks can be easily created, the symlink function is very simple and only
takes a few arguments
.sp
.nf
.ft C
/etc/grub.conf:
  file:
    \- symlink
    \- target: /boot/grub/grub.conf
.ft P
.fi
.sp
Recursive directory management can also be set via the \fBrecurse\fP
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 recuse state would look
something like this:
.sp
.nf
.ft C
/opt/code/flask:
  file:
    \- recurse
    \- source: salt://code/flask
.ft P
.fi
.INDENT 0.0
.TP
.B 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.
.INDENT 7.0
.TP
.B name
The path which should be deleted
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.append(name, text)
Ensure that some text appears at the end of a file
.sp
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.
.sp
Multi\-line example:
.sp
.nf
.ft C
/etc/motd:
  file:
    \- append
    \- text: |
        Thou hadst better eat salt with the Philosophers of Greece,
        than sugar with the Courtiers of Italy.
        \- Benjamin Franklin
.ft P
.fi
.sp
Multiple lines of text:
.sp
.nf
.ft C
/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.
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.comment(name, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq)
Usage:
.sp
.nf
.ft C
/etc/fstab:
  file:
    \- comment
    \- regex: ^//10.10.20.5
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.directory(name, user=None, group=None, mode=None, makedirs=False, clean=False, require=None)
Ensure that a named directory is present and has the right perms
.INDENT 7.0
.TP
.B name
The location to create or manage a directory
.TP
.B user
The user to own the directory, this defaults to the user salt is
running as on the minion
.TP
.B group
The group ownership set for the directory, this defaults to the group
salt is running as on the minion
.TP
.B mode
The permissions to set on this directory, aka 755
.TP
.B 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.
.TP
.B 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.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.managed(name, source=None, user=None, group=None, mode=None, template=None, makedirs=False, context=None, defaults=None, __env__=\(aqbase\(aq)
Manage a given file, this function allows for a file to be downloaded from
the salt master and potentially run through a templating system.
.INDENT 7.0
.TP
.B name
The location of the file to manage
.TP
.B source
The source file, this file is located on the salt master file server
and is specified with the salt:// protocol. 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
.TP
.B user
The user to own the file, this defaults to the user salt is running as
on the minion
.TP
.B group
The group ownership set for the file, this defaults to the group salt
is running as on the minion
.TP
.B mode
The permissions to set on this file, aka 644, 0775, 4664
.TP
.B 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
.TP
.B 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.
.TP
.B context
Overrides default context variables passed to the template.
.TP
.B defaults
Default context passed to the template.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.recurse(name, source, clean=False, require=None, __env__=\(aqbase\(aq)
Recurse through a subdirectory on the master and copy said subdirecory
over to the specified path.
.INDENT 7.0
.TP
.B name
The directory to set the recursion in
.TP
.B 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
.TP
.B 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.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.sed(name, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, options=\(aq\-r \-e\(aq, flags=\(aqg\(aq)
Maintain a simple edit to a file
.sp
Usage:
.sp
.nf
.ft C
# Disable the epel repo by default
/etc/yum.repos.d/epel.repo:
  file:
    \- sed
    \- before: 1
    \- after: 0
    \- limit: ^enabled=
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.symlink(name, target, force=False, makedirs=False)
Create a symlink
.INDENT 7.0
.TP
.B name
The location of the symlink to create
.TP
.B target
The location that the symlink points to
.TP
.B 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
.TP
.B 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
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.touch(name, atime=None, mtime=None)
Replicate the \(aqnix "touch" command to create a new empty
file or update the atime and mtime of an existing  file.
.sp
Usage:
.sp
.nf
.ft C
/var/log/httpd/logrotate.empty
  file:
    \- touch
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.uncomment(name, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq)
Usage:
.sp
.nf
.ft C
/etc/adduser.conf:
  file:
    \- uncomment
    \- regex: EXTRA_GROUPS
.ft P
.fi
.sp
New in version 0.9.5.
.UNINDENT
.SS salt.states.group
.SS Group Management
.sp
The group module is used to create and manage unix group settings, groups
can be either present or absent:
.sp
.nf
.ft C
cheese:
  group:
    \- present
    \- gid: 7648
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.group.absent(name)
Ensure that the named group is absent
.INDENT 7.0
.TP
.B name
The name of the group to remove
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.group.present(name, gid=None)
Ensure that a group is present
.INDENT 7.0
.TP
.B name
The name of the group to manage
.TP
.B gid
The group id to assign to the named group, if left empty then the next
available group id will be assigned
.UNINDENT
.UNINDENT
.SS salt.states.host
.SS Hosts File Management
.sp
The hosts file can be managed to contain definitions for specific hosts:
.sp
.nf
.ft C
salt\-master:
  host:
    \- present
    \- ip: 192.168.0.42
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.host.absent(name, ip)
Ensure that the named host is absent
.INDENT 7.0
.TP
.B name
The host to remove
.TP
.B ip
The ip addr of the host to remove
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.host.present(name, ip)
Ensures that the named host is present with the given ip
.INDENT 7.0
.TP
.B name
The host to assign an ip to
.TP
.B ip
The ip addr to apply to the host
.UNINDENT
.UNINDENT
.SS salt.states.kmod
.SS Kernel Module Management
.sp
The Kernel modules on a system can be managed cleanly with the kmod state
module:
.sp
.nf
.ft C
kvm_amd:
  kmod:
    \- present
pcspkr:
  kmod:
    \- absent
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.kmod.absent(name)
Verify that the named kernel module is not loaded
.INDENT 7.0
.TP
.B name
The name of the kernel module to verify is not loaded
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.kmod.present(name)
Ensure that the specified kernel module is loaded
.INDENT 7.0
.TP
.B name
The name of the kernel module to verify is loaded
.UNINDENT
.UNINDENT
.SS salt.states.mount
.SS Mount Management
.sp
Mount any type of mountable filesystem with the mounted function:
.sp
.nf
.ft C
/mnt/sdb:
  mount:
    \- mounted
    \- device: /dev/sdb1
    \- fstype: ext4
    \- mkmnt: True
    \- opts:
      \- defaults
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.mount.mounted(name, device, fstype, mkmnt=False, opts=[\(aqdefaults\(aq], dump=0, pass_num=0, config=\(aq/etc/fstab\(aq, remount=True, persist=True)
Verify that a device is mounted
.INDENT 7.0
.TP
.B name
The path to the location where the device is to be mounted
.TP
.B device
The device name, typically the device node, such as /dev/sdb1
.TP
.B 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
.TP
.B 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
.TP
.B opts
A list object of options or a comma delimited list
.TP
.B dump
The dump value to be passed into the fstab, default to 0
.TP
.B pass_num
The pass value to be passed into the fstab, default to 0
.TP
.B config
Set an alternative location for the fstab, default to /etc/fstab
.TP
.B remount
Set if the file system can be remounted with the remount option,
default to True
.TP
.B persist
Set if the mount should be saved in the fstab, default to True
.UNINDENT
.UNINDENT
.SS salt.states.pkg
.SS Package Management
.sp
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:
.sp
.nf
.ft C
vim:
  pkg:
    \- installed
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.pkg.installed(name, repo=\(aq\(aq, skip_verify=False)
Verify that the package is installed, and only that it is installed. This
state will not upgrade an existing package and only verify that it is
installed
.INDENT 7.0
.TP
.B name
The name of the package to install
.TP
.B repo
Specify a non\-default repository to install from
.TP
.B skip_verify
False
Skip the GPG verification check for the package to be installed
.UNINDENT
.sp
Usage:
.sp
.nf
.ft C
httpd:
  \- pkg
  \- installed
  \- repo: mycustomrepo
  \- skip_verify: True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.latest(name, repo=\(aq\(aq, skip_verify=False)
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 \fBlatest\fP will update the package the package whenever a new
package is available
.INDENT 7.0
.TP
.B name
The name of the package to maintain at the latest available version
.TP
.B repo
(default)
Specify a non\-default repository to install from
.TP
.B skip_verify
False
Skip the GPG verification check for the package to be installed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.purged(name)
Verify that the package is purged, this will call the purge function in the
salt pkg module for the platform.
.INDENT 7.0
.TP
.B name
The name of the package to be purged
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.removed(name)
Verify that the package is removed, this will remove the package via
the remove function in the salt pkg module for the platform.
.INDENT 7.0
.TP
.B name
The name of the package to be removed
.UNINDENT
.UNINDENT
.SS salt.states.service
.SS Service Management
.sp
Services are defined as system daemons typically started with system init or
rc scripts, services can be defined as running or dead.
.sp
.nf
.ft C
httpd:
  service:
    \- running
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.service.dead(name, enable=None, sig=None)
Ensure that the named service is dead
.INDENT 7.0
.TP
.B name
The name of the init or rc script used to manage the service
.TP
.B 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.
.TP
.B sig
The string to search for when looking for the service process with ps
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.service.running(name, enable=None, sig=None)
Verify that the service is running
.INDENT 7.0
.TP
.B name
The name of the init or rc script used to manage the service
.TP
.B 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.
.TP
.B sig
The string to search for when looking for the service process with ps
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.service.watcher(name, sig=None)
The service watcher, called to invoke the watch command.
.INDENT 7.0
.TP
.B name
The name of the init or rc script used to manage the service
.TP
.B sig
The string to search for when looking for the service process with ps
.UNINDENT
.UNINDENT
.SS salt.states.ssh_auth
.SS SSH Authorized Key Management
.sp
The information stored in a user\(aqs ssh authorized key file can be easily
controlled via the ssh_auth state:
.sp
.nf
.ft C
AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==:
  ssh_auth:
    \- present
    \- user: root
    \- enc: ssh\-dss
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.ssh_auth.absent(name, user, config=\(aq.ssh/authorized_keys\(aq)
Verifies that the specified ssh key is absent
.INDENT 7.0
.TP
.B name
The ssh key to manage
.TP
.B user
The user who owns the ssh authorized keys file to modify
.TP
.B config
The location of the authorized keys file relative to the user\(aqs home
directory, defaults to ".ssh/authorized_keys"
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ssh_auth.present(name, user, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, options=[], config=\(aq.ssh/authorized_keys\(aq)
Verifies that the specified ssh key is present for the specified user
.INDENT 7.0
.TP
.B name
The ssh key to manage
.TP
.B user
The user who owns the ssh authorized keys file to modify
.TP
.B enc
Defines what type of key is being used, can be ssh\-rsa or ssh\-dss
.TP
.B comment
The comment to be placed with the ssh public key
.TP
.B options
The options passed to the key, pass a list object
.TP
.B config
The location of the authorized keys file relative to the user\(aqs home
directory, defaults to ".ssh/authorized_keys"
.UNINDENT
.UNINDENT
.SS salt.states.sysctl
.SS Kernel Sysctl Management
.sp
Control the kernel sysctl system
.sp
.nf
.ft C
vm.swappines:
  sysctl:
    \- present
    \- value: 20
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.sysctl.present(name, value, config=\(aq/etc/sysctl.conf\(aq)
Ensure that the named sysctl value is set
.INDENT 7.0
.TP
.B name
The name of the sysctl value to edit
.TP
.B value
The sysctl value to apply
.TP
.B config
The location of the sysctl configuration file
.UNINDENT
.UNINDENT
.SS salt.states.user
.SS User Management
.sp
The user module is used to create and manage user settings, users can be set
as either absent or present
.sp
.nf
.ft C
fred:
  user:
    \- present
    \- shell: /bin/zsh
    \- home: /home/fred
    \- uid: 4000
    \- gid: 4000
    \- groups:
      \- wheel
      \- storage
      \- games
.ft P
.fi
.INDENT 0.0
.TP
.B salt.states.user.absent(name, purge=False, force=False)
Ensure that the named user is absent
.INDENT 7.0
.TP
.B name
The name of the user to remove
.TP
.B purge
Set purge to delete all of the user\(aqs file as well as the user
.TP
.B 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
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.user.present(name, uid=None, gid=None, groups=None, home=False, password=None, shell=\(aq/bin/bash\(aq)
Ensure that the named user is present with the specified properties
.INDENT 7.0
.TP
.B name
The name of the user to manage
.TP
.B uid
The user id to assign, if left empty then the next available user id
will be assigned
.TP
.B gid
The default group id
.TP
.B groups
A list of groups to assign the user to, pass a list object
.TP
.B home
The location of the home directory to manage
.TP
.B password
A password hash to set for the user
.TP
.B shell
The login shell, defaults to /bin/bash
.UNINDENT
.UNINDENT
.SH RENDERERS
.sp
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.
.sp
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.
.sp
Currently there is support for \fBjinja + yaml\fP, \fBmako + yaml\fP,
\fBjinja + json\fP and \fBmako + json\fP. 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.
.SS Writing Renderers
.sp
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.
.SS Examples
.sp
The best place to find examples of renderers is in the Salt source code. The
renderers included with Salt can be found here:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/renderers\fP
.sp
Here is a simple jinja + yaml example:
.sp
.nf
.ft C
# Import python libs
import os

# Import Third Party libs
import yaml
from jinja2 import Template

def render(template):
    \(aq\(aq\(aq
    Render the data passing the functions and grains into the rendering system
    \(aq\(aq\(aq
    if not os.path.isfile(template):
        return {}
    passthrough = {}
    passthrough.update(__salt__)
    passthrough.update(__grains__)
    template = Template(open(template, \(aqr\(aq).read())
    yaml_data = template.render(**passthrough)
    return yaml.load(yaml_data)
.ft P
.fi
.SH FULL LIST OF BUILTIN RENDERERS
.TS
center;
|l|l|.
_
T{
\fBjson_jinja\fP
T}	T{
Process json with the jinja2 templating engine
T}
_
T{
\fBjson_mako\fP
T}	T{
T}
_
T{
\fByaml_jinja\fP
T}	T{
The default rendering engine, process yaml with the jinja2 templating engine
T}
_
T{
\fByaml_mako\fP
T}	T{
T}
_
T{
\fBpy\fP
T}	T{
Pure python state renderer
T}
_
.TE
.SS salt.renderers.json_jinja
.sp
Process json with the jinja2 templating engine
.sp
This renderer will take a json file with the jinja template and render it to a
high data format for salt states.
.INDENT 0.0
.TP
.B salt.renderers.json_jinja.render(template_file, env=\(aq\(aq, sls=\(aq\(aq)
Render the data passing the functions and grains into the rendering system
.UNINDENT
.SS salt.renderers.yaml_jinja
.sp
The default rendering engine, process yaml with the jinja2 templating engine
.sp
This renderer will take a yaml file with the jinja2 template and render it to a
high data format for salt states.
.INDENT 0.0
.TP
.B salt.renderers.yaml_jinja.render(template_file, env=\(aq\(aq, sls=\(aq\(aq)
Render the data passing the functions and grains into the rendering system
.UNINDENT
.SS salt.renderers.py
.sp
Pure python state renderer
.sp
The sls file should contain a function called \fBsls\fP which returns high state
data
.INDENT 0.0
.TP
.B salt.renderers.py.render(template, env=\(aq\(aq, sls=\(aq\(aq)
Render the python module\(aqs components
.UNINDENT
.SH SALT RUNNERS
.sp
Salt runners are convenience applications executed with the salt\-run command.
.sp
A Salt runner can be a simple client call, or a complex application.
.sp
The use for a salt running is to build a frontend hook for running sets of
commands via salt or creating special formatted output.
.SS Writing Salt Runners
.sp
Salt runners can be easily written, the work in a similar way to Salt modules
except they run on the server side.
.sp
A runner is a python module that contains functions, each public function is
a runner that can be executed via the salt\-run command.
.sp
If a python module named test.py is created in the runners directory and
contains a function called \fBfoo\fP then the function could be called with:
.sp
.nf
.ft C
# salt \(aq*\(aq test.foo
.ft P
.fi
.SS Examples
.sp
The best examples of runners can be found in the Salt source:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/runners\fP
.sp
A simple runner that returns a well formated list of the minons that are
responding to salt calls would look like this:
.sp
.nf
.ft C
# Import salt modules
import salt.client

def up():
    \(aq\(aq\(aq
    Print a list of all of the minions that are up
    \(aq\(aq\(aq
    client = salt.client.LocalClient(__opts__[\(aqconfig\(aq])
    minions = client.cmd(\(aq*\(aq, \(aqtest.ping\(aq, timeout=1)
    for minion in sorted(minions):
        print minion
.ft P
.fi
.SH PEER COMMUNICATION
.sp
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.
.sp
The peer interface allows a minion to call out publications on the salt master
and receive the return data.
.sp
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.
.SS Configuration
.sp
The configuration is done under the peer setting in the salt master
configuration file, here are a number of configuration possibilities.
.sp
The simplest approach is to enable all communication for all minions, this is
only recommended for very secure environments.
.sp
.nf
.ft C
peer:
  .*:
    \- .*
.ft P
.fi
.sp
This configuration will allow minions with ids ending in example.com access
to the test, ps, and pkg module functions.
.sp
.nf
.ft C
peer:
  .*example.com:
    \- test.*
    \- ps.*
    \- pkg.*
.ft P
.fi
.sp
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.
.sp
.nf
.ft C
peer:
  .*example.com:
    \- test.*
    \- ps.*
    \- pkg.*
  .*foo.org:
    \- test.*
    \- ps.*
    \- pkg.*
.ft P
.fi
.SH SALT SYNDIC
.sp
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 attatched to
the master running the syndic.
.sp
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.
.SS Configuring the Syndic
.sp
Since the Syndic only needs to be attatched 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.
.sp
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\(aqs
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.
.SS Running the Syndic
.sp
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.
.sp
.nf
.ft C
# salt\-syndic
.ft P
.fi
.SH PYTHON CLIENT API
.sp
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.
.SS Using the LocalClient API
.sp
Sending information through the client is simple:
.sp
.nf
.ft C
# 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(\(aq*\(aq, \(aqcmd.run\(aq, [\(aqls \-l\(aq])
.ft P
.fi
.sp
The cmd call is the only one needed for the local client, the arguments are as
follows:
.INDENT 0.0
.TP
.B LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form=\(aqglob\(aq)
.UNINDENT
.sp
The LocalClient object only works running as root on the salt\-master, it is the
same interface used by the salt command line tool. The arguments are as
follows.
.INDENT 0.0
.TP
.B 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.
.UNINDENT
.INDENT 0.0
.TP
.B 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 \(aq*\(aq sys.doc
.UNINDENT
.INDENT 0.0
.TP
.B arg
The optional arg parameter is used to pass a list of options on to the
remote function
.UNINDENT
.INDENT 0.0
.TP
.B timeout
The number of seconds to wait after the last minion returns but before all
minions return.
.UNINDENT
.INDENT 0.0
.TP
.B expr_form
The type of tgt that is passed in, the allowed values are:
.INDENT 7.0
.IP \(bu 2
\(aqglob\(aq \- Bash glob completion \- Default
.IP \(bu 2
\(aqpcre\(aq \- Perl style regular expression
.IP \(bu 2
\(aqlist\(aq \- Python list of hosts
.UNINDENT
.UNINDENT
.SS Compound Command Execution With the Salt API
.sp
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 send in a single publish
containing a series of commands. This can dramatically lower overhead and
speed up the application communicating with Salt.
.sp
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.
.sp
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.
.sp
.nf
.ft C
# 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(\(aq*\(aq, [\(aqcmd.run\(aq, \(aqtest.ping\(aq, \(aqtest.echo\(aq], [[\(aqls \-l\(aq], [], [\(aqfoo\(aq]])
.ft P
.fi
.sp
This will execute \fBcmd.run ls \-l\fP then \fBtest.ping\fP and finally
\fBtest.echo foo\fP.
The return data from the minion will look like this:
.sp
.nf
.ft C
{\(aqcmd.run\(aq: \(aq<output from ls \-l>\(aq,
 \(aqtest.ping\(aq: True,
 \(aqtest.echo\(aq: \(aqfoo\(aq}
.ft P
.fi
.SH SALT FILE SERVER
.sp
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.
.sp
The main intent of the Salt File server is the 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.
.SS The cp Module
.sp
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.
.SS Environments
.sp
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.
.SS get_file
.sp
The cp.get_file function can be used on the minion to download a file from
the master, the syntax looks like this:
.sp
.nf
.ft C
# salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc
.ft P
.fi
.sp
This will instruct all salt minions to download the vimrc file and copy it
to /etc/vimrc
.SS File Server Client API
.sp
A client API is available which allows for modules and applications to be
written which make use of the Salt file server.
.sp
The file server uses the same authentication and encryption used by the rest
of the Salt system for network communication.
.SS FileClient Class
.sp
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 \fB__opts__\fP data can be passed:
.sp
.nf
.ft C
import salt.minion

def get_file(path, dest, env=\(aqbase\(aq):
    \(aq\(aq\(aq
    Used to get a single file from the salt master

    CLI Example:
    salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc
    \(aq\(aq\(aq
    # Create the FileClient object
    client = salt.minion.FileClient(__opts__)
    # Call get_file
    return client.get_file(path, dest, False, env)
.ft P
.fi
.sp
Using the FileClient class outside of a minion module where the \fB__opts__\fP
data is not available, it needs to be generated:
.sp
.nf
.ft C
import salt.minion
import salt.config

def get_file(path, dest, env=\(aqbase\(aq):
    \(aq\(aq\(aq
    Used to get a single file from the salt master
    \(aq\(aq\(aq
    # Get the configuration data
    opts = salt.config.minion_config(\(aq/etc/salt/minion\(aq)
    # Create the FileClient object
    client = salt.minion.FileClient(opts)
    # Call get_file
    return client.get_file(path, dest, False, env)
.ft P
.fi
.SH CONFIGURATION FILE EXAMPLES
.INDENT 0.0
.IP \(bu 2
\fI\%Example master configuration file\fP
.IP \(bu 2
\fI\%Example minion configuration file\fP
.UNINDENT
.SS Example master configuration file
.sp
.nf
.ft C
##### Primary configuration settings #####
##########################################
# The address of the interface to bind to
#interface: 0.0.0.0

# The port used by the publisher
#publish_port: 4505

# 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
#ret_port: 4506

# The root directory prepended to these options: pki_dir, cachedir,
# sock_dir, log_file.
#root_dir: /

# Directory used to store public key data
#pki_dir: /etc/salt/pki

# Directory to store job and cache data
#cachedir: /var/cache/salt

# Set the number of hours to keep old job information
#keep_jobs: 24

# Set the directory used to hold unix sockets
#sock_dir: /tmp/salt\-unix

# Set the acceptance level for serialization of messages. This should only be
# set if the master is newer that 0.9.5 and the minion are older, this option
# allows a 0.9.5 and newer master to communicate with minions 0.9.4 and
# earlier. It is not recommended to keep this setting on if the minions are
# all 0.9.5 or higher, as leaving pickle as the serialization medium is slow
# and opens up security risks
#
#serial: msgpack

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

#####      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
#state_top: top.sls
#
# 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

#####      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
# 
# Default:
#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

#####          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\(aq syndic interfaces
#order_masters: False
#
# If this master will be running a salt syndic daemon, then the syndic needs
# to know where the master it is recieving commands from is, set it with the
# syndic_master value
#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 recomanded, since it would allow anyone who gets root on any
# single minion to instantly have root on all of the minions!
#

#####         Cluster settings       #####
##########################################
# Salt supports automatic clustering, salt creates a single ip address which
# is shared among the individual salt components using ucarp. The private key
# and all of the minion keys are maintained across the defined cluster masters
# The failover service is automatically managed via these settings

# List the identifiers for the other cluster masters in this manner:
# [saltmaster\-01.foo.com,saltmaster\-02.foo.com,saltmaster\-03.foo.com]
# The members of this master array must be running as salt minions to
# facilitate the distribution of cluster information
#cluster_masters: []

# The cluster modes are "paranoid" and "full"
# paranoid will only distribute the accepted minion public keys.
# full will also distribute the master private key.
#cluster_mode: paranoid


#####         Logging settings       #####
##########################################
# The location of the master log file
#log_file: /var/log/salt/master
# The level of messages to send to the log file.
# One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq.
# Default: \(aqwarning\(aq
#log_level: warning
#
# Logger levels can be used to tweak specific loggers logging levels.
# Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you
# still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level:
#   log_granular_levels:
#     \(aqsalt\(aq: \(aqwarning\(aq,
#     \(aqsalt.modules\(aq: \(aqdebug\(aq
#
#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: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq,
#   group2: \(aqG@os:Debian and foo.domain.com\(aq,


.ft P
.fi
.SS Example minion configuration file
.sp
.nf
.ft C
##### Primary configuration settings #####
##########################################
# 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 post used by the master reply and authentication server
#master_port: 4506

# The root directory prepended to these options: pki_dir, cachedir, log_file.
#root_dir: /

# The directory to store the pki information in
#pki_dir: /etc/salt/pki

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

# The minion connection to the master may be inturupted, the minion will
# verify the connection every so many seconds, to disable connection
# verification set this value to 0
#sub_timeout: 60

# Where cache data goes
#cachedir: /var/cache/salt

# When waiting for a master to accept the minion\(aqs public key, salt will
# contiuously attempt to reconnect until successful. This is the time, in
# seconds, between those reconnection attempts.
# acceptance_wait_time = 10



#####   Minion module management     #####
##########################################
# Disable specific modules, this will allow the admin to limit the level os
# 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: []
# 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
# json_jinja
# json_mako
#
#renderer: yaml_jinja
#
# state_verbose allows for the data returned from the minion to be more
# verbose. Normaly 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: 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

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


######         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
#log_file: /var/log/salt/minion
# The level of messages to send to the log file.
# One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq.
# Default: \(aqwarning\(aq
#log_level: warning
#
# Logger levels can be used to tweak specific loggers logging levels.
# Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you
# still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level:
#   log_granular_levels: {
#     \(aqsalt\(aq: \(aqwarning\(aq,
#     \(aqsalt.modules\(aq: \(aqdebug\(aq
#   }
#
#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 allied via the yaml dict construct, some examples:
#
# 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}

.ft P
.fi
.SH CONFIGURING THE SALT MASTER
.sp
The Salt system is amazingly simple and easy to configure, the two components
of the Salt system each have a respective configuration file. The
\fBsalt\-master\fP is configured via the master configuration file, and the
\fBsalt\-minion\fP is configured via the minion configuration file.
.IP "See also"
.sp
\fIexample master configuration file\fP
.RE
.sp
The configuration file for the salt\-master is located at
\fB/etc/salt/master\fP. The available options are as follows:
.SS Primary Master Configuration
.SS \fBinterface\fP
.sp
Default: \fB0.0.0.0\fP (all interfaces)
.sp
The local interface to bind to.
.sp
.nf
.ft C
interface: 192.168.0.1
.ft P
.fi
.SS \fBpublish_port\fP
.sp
Default: \fB4505\fP
.sp
The network port to set up the publication interface
.sp
.nf
.ft C
publish_port: 4505
.ft P
.fi
.SS \fBworker_threads\fP
.sp
Default: \fB5\fP
.sp
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.
.sp
.nf
.ft C
worker_threads: 5
.ft P
.fi
.SS \fBret_port\fP
.sp
Default: \fB4506\fP
.sp
The port used by the return server, this is the server used by Salt to receive
execution returns and command executions.
.sp
.nf
.ft C
ret_port: 4506
.ft P
.fi
.SS \fBroot_dir\fP
.sp
Default: \fB/\fP
.sp
The system root direcotry to oporate from, change this to make Salt run from
an alternative root
.SS \fBpki_dir\fP
.sp
Default: \fB/etc/salt/pki\fP
.sp
The directory to store the pki authentication keys.
.sp
.nf
.ft C
pki_dir: /etc/salt/pki
.ft P
.fi
.SS \fBcachedir\fP
.sp
Default: \fB/var/cache/salt\fP
.sp
The location used to store cache information, particularly the job information
for executed salt commands.
.sp
.nf
.ft C
cachedir: /var/cache/salt
.ft P
.fi
.SS \fBkeep_jobs\fP
.sp
Default: \fB24\fP
.sp
Set the number of hours to keep old job information
.SS \fBsock_dir\fP
.sp
Default:: \fB/tmp/salt\-unix\fP
.sp
Set the location to use for creating Unix sockets for master process
communication
.SS Master Security Settings
.SS \fBopen_mode\fP
.sp
Default: \fBFalse\fP
.sp
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 the value passed must be \fBTrue\fP.
.sp
.nf
.ft C
open_mode: False
.ft P
.fi
.SS \fBauto_accept\fP
.sp
Default: \fBFalse\fP
.sp
Enable auto_accept, this setting will automatically accept all incoming
public keys from the minions
.sp
.nf
.ft C
auto_accept: False
.ft P
.fi
.SS Master State System Settings
.SS \fBstate_top\fP
.sp
Default: \fBtop.sls\fP
.sp
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
.sp
.nf
.ft C
state_top: top.sls
.ft P
.fi
.SS \fBrenderer\fP
.sp
Default: \fByaml_jinja\fP
.sp
The renderer to use on the minions to render the state data
.sp
.nf
.ft C
renderer: yaml_jinja
.ft P
.fi
.sp
Default:: \fBFalse\fP
.sp
Set the global failhard flag, this informs all states to stop running states
at the moment a single state fails
.sp
.nf
.ft C
failhard: False
.ft P
.fi
.SS Master File Server Settings
.SS \fBfile_roots\fP
.sp
Default: \fBbase: [/srv/salt]\fP
.sp
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:
.sp
.nf
.ft C
file_roots:
  base:
    \- /srv/salt/
  dev:
    \- /srv/salt/dev/services
    \- /srv/salt/dev/states
  prod:
    \- /srv/salt/prod/services
    \- /srv/salt/prod/states
.ft P
.fi
.sp
.nf
.ft C
base:
  \- /srv/salt
.ft P
.fi
.SS \fBhash_type\fP
.sp
Default: \fBmd5\fP
.sp
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.
.sp
.nf
.ft C
hash_type: md5
.ft P
.fi
.SS \fBfile_buffer_size\fP
.sp
Default: \fB1048576\fP
.sp
The buffer size in the file server in bytes
.sp
.nf
.ft C
file_buffer_size: 1048576
.ft P
.fi
.SS Syndic Server Settings
.sp
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
.SS \fBorder_masters\fP
.sp
Default: \fBFalse\fP
.sp
Extra data needs to be sind with publications if the master os controlling a
lower level master via a syndic minion. If this is the case the order_masters
value must be set to True
.sp
.nf
.ft C
order_masters: False
.ft P
.fi
.SS \fBsyndic_master\fP
.sp
Default: \fBNone\fP
.sp
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
.sp
.nf
.ft C
syndic_master: masterofmasters
.ft P
.fi
.SS Peer Publish Settings
.sp
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.
.SS \fBpeer\fP
.sp
Default: \fB{}\fP
.sp
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
.sp
.nf
.ft C
peer:
  foo.example.com:
      \- test.*
      \- pkg.*
.ft P
.fi
.sp
This will allow all minions to execute all commands:
.sp
.nf
.ft C
peer:
  .*:
      \- .*
.ft P
.fi
.sp
This is not recomanded, since it would allow anyone who gets root on any
single minion to instantly have root on all of the minions!
.SS Node Groups
.sp
Default: \fB{}\fP
.sp
Node groups allow for logical groupings of minion nodes.
A group consists of a group name and a compound target.
.sp
.nf
.ft C
nodegroups:
  group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq
  group2: \(aqG@os:Debian and foo.domain.com\(aq
.ft P
.fi
.SS Master Logging Settings
.SS \fBlog_file\fP
.sp
Default: \fB/var/log/salt/master\fP
.sp
The location of the master log file
.sp
.nf
.ft C
log_file: /var/log/salt/master
.ft P
.fi
.SS \fBlog_level\fP
.sp
Default: \fBwarning\fP
.sp
The level of messages to send to the log file.
One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq.
.sp
.nf
.ft C
log_level: warning
.ft P
.fi
.SS \fBlog_granular_levels\fP
.sp
Default: \fB{}\fP
.sp
Logger levels can be used to tweak specific loggers logging levels.
Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you
still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level:
.sp
.nf
.ft C
log_granular_levels:
  \(aqsalt\(aq: \(aqwarning\(aq,
  \(aqsalt.modules\(aq: \(aqdebug\(aq
.ft P
.fi
.SH CONFIGURING THE SALT MINION
.sp
The Salt system is amazingly simple and easy to configure, the two components
of the Salt system each have a respective configuration file. The
\fBsalt\-master\fP is configured via the master configuration file, and the
\fBsalt\-minion\fP is configured via the minion configuration file.
.IP "See also"
.sp
\fIexample minion configuration file\fP
.RE
.sp
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.
.SS Minion Primary Configuration
.SS \fBmaster\fP
.sp
Default: \fBsalt\fP
.sp
The hostname or ipv4 of the master.
.sp
.nf
.ft C
master: salt
.ft P
.fi
.SS \fBmaster_port\fP
.sp
Default: \fB4506\fP
.sp
The port of the master ret server, this needs to coincide with the ret_port
option on the salt master.
.sp
.nf
.ft C
master_port: 4506
.ft P
.fi
.SS \fBpki_dir\fP
.sp
Default: \fB/etc/salt/pki\fP
.sp
The directory used to store the minion\(aqs public and private keys.
.sp
.nf
.ft C
pki_dir: /etc/salt/pki
.ft P
.fi
.SS \fBid\fP
.sp
Default: hostname (as returned by the Python call: \fBsocket.getfqdn()\fP)
.sp
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.
.sp
.nf
.ft C
id: foo.bar.com
.ft P
.fi
.SS \fBsub_timeout\fP
.sp
The minion connection to the master may be inturupted, the minion will
verify the connection every so many seconds, to disable connection
verification set this value to 0
.sp
.nf
.ft C
sub_timeout: 60
.ft P
.fi
.SS \fBcachedir\fP
.sp
Default: \fB/var/cache/salt\fP
.sp
The location for minion cache data.
.sp
.nf
.ft C
cachedir: /var/cache/salt
.ft P
.fi
.sp
Default: \fB10\fP
.sp
The number of seconds to wait until attempting to re\-authenticate with the
master.
.sp
.nf
.ft C
acceptance_wait_time: 10
.ft P
.fi
.SS Minion Module Management
.SS \fBdisable_modules\fP
.sp
Default: \fB[]\fP (all modules are enabled by default)
.sp
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.
.sp
This setting can also tune the minion, as all modules are loaded into ram
disabling modules will lover the minion\(aqs ram footprint.
.sp
.nf
.ft C
disable_modules:
  \- test
  \- solr
.ft P
.fi
.SS \fBdisable_returners\fP
.sp
Default: \fB[]\fP (all returners are enabled by default)
.sp
If certian returners should be disabled, this is the place
.sp
.nf
.ft C
disable_returners:
  \- mongo_return
.ft P
.fi
.SS \fBmodule_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for salt modules
.sp
.nf
.ft C
module_dirs:
  \- /var/lib/salt/modules
.ft P
.fi
.SS \fBreturner_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for salt returners
.sp
.nf
.ft C
returners_dirs:
  \- /var/lib/salt/returners
.ft P
.fi
.SS \fBstates_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for salt states
.sp
.nf
.ft C
states_dirs:
  \- /var/lib/salt/states
.ft P
.fi
.SS \fBrender_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for salt renderers
.sp
.nf
.ft C
render_dirs:
  \- /var/lib/salt/renderers
.ft P
.fi
.SS \fBcython_enable\fP
.sp
Default: \fBFalse\fP
.sp
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
.sp
.nf
.ft C
cython_enable: False
.ft P
.fi
.SS State Management Settings
.SS \fBrenderer\fP
.sp
Default: \fByaml_jinja\fP
.sp
The default renderer used for local state executions
.sp
.nf
.ft C
renderer: yaml_jinja
.ft P
.fi
.SS \fBstate_verbose\fP
.sp
Default: \fBFalse\fP
.sp
state_verbose allows for the data returned from the minion to be more
verbose. Normaly only states that fail or states that have changes are
returned, but setting state_verbose to True will return all states that
were checked
.sp
.nf
.ft C
state_verbose: True
.ft P
.fi
.SS \fBautoload_dynamic_modules\fP
.sp
Default: \fBTrue\fP
.sp
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
.sp
.nf
.ft C
autoload_dynamic_modules: True
.ft P
.fi
.sp
Default: \fBTrue\fP
.sp
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
.sp
.nf
.ft C
clean_dynamic_modules: True
.ft P
.fi
.SS Security Settings
.SS \fBopen_mode\fP
.sp
Default: \fBFalse\fP
.sp
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.
.sp
.nf
.ft C
open_mode: False
.ft P
.fi
.SS Thread Settings
.sp
Default: \fBTrue\fP
.sp
Disable multiprocessing support, by default when a minion receives a
publication a new process is spawned and the command is executed therein.
.sp
.nf
.ft C
multiprocessing: True
.ft P
.fi
.SS Minion Logging Settings
.SS \fBlog_file\fP
.sp
Default: \fB/var/log/salt/minion\fP
.sp
The location of the minion log file
.sp
.nf
.ft C
log_file: /var/log/salt/minion
.ft P
.fi
.SS \fBlog_level\fP
.sp
Default: \fBwarning\fP
.sp
The level of messages to send to the log file.
One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq.
.sp
.nf
.ft C
log_level: warning
.ft P
.fi
.SS \fBlog_granular_levels\fP
.sp
Default: \fB{}\fP
.sp
Logger levels can be used to tweak specific loggers logging levels.
Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you
still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level:
.sp
.nf
.ft C
log_granular_levels:
  \(aqsalt\(aq: \(aqwarning\(aq,
  \(aqsalt.modules\(aq: \(aqdebug\(aq
.ft P
.fi
.SH COMMAND LINE REFERENCE
.sp
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.
.sp
Using the Salt client commands can be easily sent to the minions.
.sp
Each of these commands accepts an explicit \fI\-\-config\fP 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 \fBSALT_MASTER_CONFIG\fP and \fBSALT_MINION_CONFIG\fP.
.IP "See also"
.sp
\fB/topics/configuration\fP
.RE
.SS Using the Salt Command
.sp
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.
.SS Defining the Target Minions
.sp
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:
.sp
.nf
.ft C
salt \e*foo.com sys.doc
.ft P
.fi
.sp
Salt can also define the target minions with regular expressions:
.sp
.nf
.ft C
salt \-E \(aq.*\(aq cmd.run \(aqls \-l | grep foo\(aq
.ft P
.fi
.sp
Or to explicitly list hosts, salt can take a list:
.sp
.nf
.ft C
salt \-L foo.bar.baz,quo.qux cmd.run \(aqps aux | grep foo\(aq
.ft P
.fi
.SS More Powerful Targets
.sp
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.
.SS Targeting with Grains
.sp
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.
.sp
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.
.sp
.nf
.ft C
salt \-G \(aqos:Fedora\(aq test.ping
.ft P
.fi
.sp
Will return True from all of the minions running Fedora.
.sp
To discover what grains are available and what the values are, execute the
grains.item salt function:
.sp
.nf
.ft C
salt \(aq*\(aq grains.items
.ft P
.fi
.SS Targeting with Executions
.sp
As of 0.8.8 targeting with executions is still under heavy development and this
documentation is written to refernce the behavior of execution matching in the
future.
.sp
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.
.sp
Execution matching allows for matching minions based on any arbitrairy running
data on tne minions.
.SS Compound Targeting
.sp
New in version 0.9.5.
.sp
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:
.sp
.nf
.ft C
salt \-C \(aqG@os:Debian and webser* or E@db.*\(aq test.ping
.ft P
.fi
.sp
in this example any minion who\(aqs id starts with webser and is running Debian,
or any minion who\(aqs id starts with db will be matched.
.sp
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.
.SS Node Group Targeting
.sp
New in version 0.9.5.
.sp
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:
.sp
.nf
.ft C
nodegroups:
 \ group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq
 \ group2: \(aqG@os:Debian and foo.domain.com\(aq
.ft P
.fi
.SS Calling the Function
.sp
The function to call on the specified target is placed after the target
specification.
.SS Finding available minion functions
.sp
The Salt functions are self documenting, all of the function documentation can
be retried from the minions via the \fBsys.doc()\fP function:
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
.ft P
.fi
.SS Compound Command Execution
.sp
If a series of commands need to be sent to a single target specification then
the multiple commands can be send in a single publish. This can make gathering
groups of information faster, and lowers the stress on the network for repeated
commands.
.sp
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.
.sp
Executing compound commands if done by passing a comma delimited list of
functions, followed by a comma delimited list of arguments:
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqcat /proc/cpuinfo\(aq,,foo
.ft P
.fi
.sp
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.
\fBtest.ping\fP takes no arguments, so we need to add another comma, otherwise
Salt would attempt to pass "foo" to \fBtest.ping\fP.
.SH SALT
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq [ options ] sys.doc
.sp
salt \-E \(aq.*\(aq [ options ] sys.doc cmd
.sp
salt \-G \(aqos:Arch.*\(aq [ options ] test.ping
.sp
salt \-C \fI\%'G@os\fP:Arch.* and webserv* or \fI\%G@kernel\fP:FreeBSD\(aq [ options ] test.ping
.sp
salt \-Q test.ping
.UNINDENT
.UNINDENT
.SS Description
.sp
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.
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options
.UNINDENT
.INDENT 0.0
.TP
.B \-t TIMEOUT, \-\-timeout=TIMEOUT
The timeout in seconds to wait for replies from the salt minions.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Print the version of salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-E, \-\-pcre
The target expression will be interpreted as a pcre regular expression
rather than a shell glob.
.UNINDENT
.INDENT 0.0
.TP
.B \-L, \-\-list
The target expression will be interpreted as a comma delimited list,
example: server1.foo.bar,server2.foo.bar,example7.quo.qux
.UNINDENT
.INDENT 0.0
.TP
.B \-G, \-\-grain
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of \(aq<grain value>:<pcre
regular expression>\(aq; example: \(aqos:Arch.*\(aq
.UNINDENT
.INDENT 0.0
.TP
.B \-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: \(aqwebserv* and \fI\%G@os\fP:Debian or \fI\%E@db.*\fP\(aq
make sure that the compound target is encapsulated in quotes.
.UNINDENT
.INDENT 0.0
.TP
.B \-X, \-\-exsel
Instead of using shell globs use the return code of a function.
.UNINDENT
.INDENT 0.0
.TP
.B \-N, \-\-nodegroup
Use a predefined compound target defined in the salt master configuration
file
.UNINDENT
.INDENT 0.0
.TP
.B \-\-return
Chose an alternative returner to call on the minion, if an alternative
returner is used then the return will not come back tot he command line
but will be sent to the specified return system.
.UNINDENT
.INDENT 0.0
.TP
.B \-Q, \-\-query
Execute a salt command query, this can be used to find the results of a
previous function call: \-Q test.echo\(aq)
.UNINDENT
.INDENT 0.0
.TP
.B \-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
.UNINDENT
.INDENT 0.0
.TP
.B \-\-raw\-out
Print the output from the salt command in raw python
form, this is suitable for re\-reading the output into
an executing python script with eval.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-text\-out
Print the output from the salt command in the same
form the shell would.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-yaml\-out
Print the output from the salt command in yaml.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-json\-out
Print the output from the salt command in json.
.UNINDENT
.SS See also
.sp
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SH SALT-MASTER
.sp
The salt master daemon, used to control the salt minions
.SS Synopsis
.sp
salt\-master [ options ]
.SS Description
.sp
The master daemon controls the salt minions
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run the salt master as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG, \-\-config=CONFIG
The master configuration file to use, the default is /etc/salt/master
.UNINDENT
.SH SALT-MINION
.sp
The salt minion daemon, receives commands from a remote salt master.
.SS Synopsis
.sp
salt\-minion [ options ]
.SS Description
.sp
The salt minion receives commands from the central salt master and replies with
the results of said commands.
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run the salt minion as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG, \-\-config=CONFIG
The minion configuration file to use, the default is /etc/salt/minion
.UNINDENT
.SH SALT-KEY
.SS Synopsis
.sp
salt\-key [ options ]
.SS Description
.sp
Salt\-key executes simple management of salt server public keys used for
authentication.
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-list
List the unaccepted minion public keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-L, \-\-list\-all
List all public keys on this salt master, both accepted and pending
acceptance.
.UNINDENT
.INDENT 0.0
.TP
.B \-a ACCEPT, \-\-accept=ACCEPT
Accept the named minion public key for command execution.
.UNINDENT
.INDENT 0.0
.TP
.B \-A, \-\-accept\-all
Accepts all pending public keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG, \-\-config=CONFIG
The master configuration file needs to be read to determine where the salt
keys are stored via the pki_dir configuration value;
default=/etc/salt/master
.UNINDENT
.SH SALT-CP
.sp
Copy a file to a set of systems
.SS Synopsis
.sp
.nf
.ft C
salt\-cp \(aq*\(aq [ options ] SOURCE DEST

salt\-cp \-E \(aq.*\(aq [ options ] SOURCE DEST

salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE DEST
.ft P
.fi
.SS Description
.sp
Salt copy copies a local file out to all of the salt minions matched by the
given target.
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options
.UNINDENT
.INDENT 0.0
.TP
.B \-t TIMEOUT, \-\-timeout=TIMEOUT
The timeout in seconds to wait for replies from the salt minions.
.UNINDENT
.INDENT 0.0
.TP
.B \-E, \-\-pcre
The target expression will be interpereted as a pcre regular expression
rather than a shell glob.
.UNINDENT
.INDENT 0.0
.TP
.B \-L, \-\-list
The target expression will be interpereted as a comma delimited list,
example: server1.foo.bar,server2.foo.bar,example7.quo.qux
.UNINDENT
.INDENT 0.0
.TP
.B \-G, \-\-grain
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of \(aq<grain value>:<pcre
regular expression>\(aq; example: \(aqos:Arch.*\(aq
.UNINDENT
.INDENT 0.0
.TP
.B \-Q, \-\-query
Execute a salt command query, this can be used to find the results of a
previous function call: \-Q test.echo\(aq)
.UNINDENT
.INDENT 0.0
.TP
.B \-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
.UNINDENT
.SH SALT-CALL
.SS Synopsis
.sp
.nf
.ft C
salt\-call [options]
.ft P
.fi
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options
.UNINDENT
.INDENT 0.0
.TP
.B \-g, \-\-grains
Return the information generated by the salt grains
.UNINDENT
.INDENT 0.0
.TP
.B \-m MODULE_DIRS, \-\-module\-dirs=MODULE_DIRS
Specify an additional directories to pull modules from, multiple
directories can be delimited by commas
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-doc
Return the documentation for the specified module of for all modules if
none are specified
.UNINDENT
.SH SALT-RUN
.sp
Execute a Salt runner
.SS Synopsis
.sp
.nf
.ft C
salt\-run RUNNER
.ft P
.fi
.SS Description
.sp
Salt run is the frontend command for executing \fBSalt Runners\fP.
Salt runners are simple modules used to execute convenience functions on the
master
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options
.UNINDENT
.INDENT 0.0
.TP
.B \-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
.UNINDENT
.SH SALT-SYNDIC
.sp
The salt syndic daemon, a special minion that passes through commands from a
higher master
.SS Synopsis
.sp
salt\-syndic [ options ]
.SS Description
.sp
The salt syndic daemon, a special minion that passes through commands from a
higher master.
.SS Options
.INDENT 0.0
.TP
.B \-h, \-\-help
Print a usage message briefly summarizing these command\-line options.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run the salt syndic as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-\-master\-config=MASTER_CONFIG
The master configuration file to use, the default is /etc/salt/master
.UNINDENT
.INDENT 0.0
.TP
.B \-\-minion\-config=MINION_CONFIG
The minion configuration file to use, the default is /etc/salt/minion
.UNINDENT
.SH SALT STACK ROADMAP
.sp
Salt is the core of a more complete goal, the Salt Stack. The Salt Stack is a
complete infrastructure management system which is comprised of many
components all functioning on top of Salt.
.sp
The majority of the functionality of the Salt Stack happens directly inside
Salt, but the information derived from Salt needs to be used to create a
transparent view of the infrastructure as a whole.
.sp
The information used in Salt States will be matched via a higher interface
and the low salt data will be visualized. This will allow the state data to
appear in the web interface.
.sp
The features listed here are only listed based on major version releases, the
plan is to have a clear long term goal but not to overly dictate the flow
of development. The project needs to be flexible enough to be able to receive
now features at a moment\(aqs notice. This model should spur ideas and make
allowing new community developers to join without issue. So just because
something is slated for a later reason does not mean that a developer is
going to have their code rejected or stalled.
.SS 1.0.0
.sp
1.0.0 requires that remote execution is stable and that states are ready to
complete. We mostly just need to clean things up for 1.0.0.
.SS Clean up code base
.sp
Go through the code, clean up PEP 8 violations and make sure we have
Python 3 compatible code.
.SS Module Cross Calls
.sp
Many instances of using functions when we should be using module cross calls
exist in the code. Mostly from modules which were written before cross calls
were around. The big thing to look for are subprocess calls, since they should
all be running with the cms module.
.SS State Return Data Cleanup
.sp
The return structures in the state modules need to be uniform in how they are
declared, before we get too much of a following we should have as consistent
modules as possible. We want to hit the gate with very clean code!
.SS States and Modules
.sp
More states need to be available.
.SS User State
.sp
The user state needs to be expanded to support password setting and managing
the finger component
.SS Clean up Bugs
.sp
We are finding a number of bugs in the new state system as we get more testers
there are a few bugs that been attention:
.sp
#66
.sp
We need to keep pushing through testing states on live systems and find as
many bugs as possible before 1.0, we have found too many 0 day bugs.
.SS Documentation
.sp
The documentation has gotten a LOT better, but we still need more work in a
few places
.SS Clean up formatting
.sp
The 1.0 PDF needs to be a document that we can publish to the world with pride
.SS Expand the State Tutorial
.sp
We are learning a lot about how to teach states, we need to take this knowledge
and improve the states tutorial. We want people to be able to get going with
states in no time at all
.SS Module Built in Docs
.sp
Double check all of the module built in docs for consistency. Make sure things
are clear and accurate.
.SS Proposal System
.sp
I would like to have a proposal system in place for Salt, so that
community members can submit proposals for feature development for
review. Using Github\(aqs new issue system with support for tags
(blocker, feature...) seems like a good choice.
.SS Workflow
.sp
Gitflow not only makes for a good branching model everybody can
understand and work with but also scales well and just works (tm).
Let\(aqs start using it!
.SS 2.0.0
.sp
2.0.0 will require a number of serious additions and overhauls. We wand to make
the transport layer much cleaner and clean up the crypto dependencies.
Figure out how to get more speed out of Salt and make it more memory
efficient. The security system needs some additions to make it more
secure.
.sp
There are also a number of features that should be pulled out of their classes
and made to stand alone. Also we want to MASSIVELY improve platform support and
module/state penetration.
.sp
This is only a subset of what we can expect 2.0.0 to be!
.sp
With 1.0.0 salt is a great option, with 2.0.0, using anything else is just plain
dumb!
.SS Python 3 Support
.sp
The goal so far has been to write Salt with 3.0 in mind, but with 2.0
we want it to be a reality. This will mostly require that the
requirements are met.
.SS Refine Security
.SS Only One Crypt Backend
.sp
Right now we have pycrypto and m2crypto, we need to pick just one. So far
the plan is to dump m2crypto and use just pycrypto.
.SS Make the iv explicit
.sp
Right now the iv is implied by the length of the AES key, we want the iv to be
randomly applied and sent with the AES key.
.SS Master Signatures
.sp
There is a theoretical vulnerability in the validation of transit messages, they
need to have a master private key signature somewhere.
.SS Change Network Serialization
.sp
Right now it is pickle, this needs to be changed to something more
standard like JSON or maybe even something simpler/faster such as
tnetstrings as used by Mongrel2. We also need to change how messages
are formatted to speed up the serialization and lower network usage
more. A new model will be proposed.
.SS State Generator
.sp
Since the state system is based on data structures we can generate them from
a uniform API, this needs to be available in renderer modules.
.SS Separate out the File Server
.sp
Te built in file server should be less built in. We will make a standalone file
server from the existing built in one that is more powerful and can be used
with and without encryption and authentication. The updated file server should
also be faster, so that large files can be downloaded more quickly.
.sp
The salt\-cp command needs to be moved to use the file server as well, so that
it can be used to copy large files as well.
.SS Support for more Platforms
.sp
Platform support means a few things, primarily that we have support for the major
modules pertinent to the platforms and that Salt will run on these platforms at
least as a minion.
.sp
Solaris
Gentoo
Suse
Slackware
OpenBSD
NetBSD
AIX
HPUX
Windows
.SS Language Library Modules and States
.sp
Modules and States that support installing programming language packages.
Here is the list to start with:
.sp
pypi
rubygem
cpan
lua
haskell?
.SS Firewall Support
.sp
This is going to be rather serious, this is a collection of modules for
iptables, pf, and the subsequent subsystems for other platforms. But in the
end, we want seamless firewall support for at least opening up ports for
services.
.SS Advanced Grains
.sp
The grains system still needs an overhaul, the problem is that grains should
have access to each other, but they should still only be run once. Some plans
are in place to pull this off, but they need to be implemented.
.SS More Renderers!
.sp
The renderer system needs to support more templating engines and language
bindings. Adding support for XML, Cheetah, Tenjin etc. will be simple. But
the main goal here is to allow sls files to be written in Ruby, Lua, Perl or
basically anything.
.SS Unit Tests
.sp
Need unit tests in place for everything, we are planning on using
Unittest2 and pytest.
.SH RELEASE NOTES AND UPGRADE INSTRUCTIONS
.SS Salt 0.6.0 release notes
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
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\(aq 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.
.sp
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.
.sp
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.
.sp
Salt 0.6.0 Source: \fI\%https://github.com/downloads/saltstack/salt/salt-0.6.0.tar.gz\fP
.sp
Github page: \fI\%https://github.com/saltstack/salt\fP
.sp
Wiki: \fI\%https://github.com/saltstack/salt/wiki\fP
.sp
Arch Linux Package: \fI\%https://aur.archlinux.org/packages.php?ID=47512\fP
.sp
I am very open to contributions, for instance I need packages for more Linux
distributions as well as BSD packages and testers.
.sp
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!
.SS Salt 0.7.0 release notes
.sp
I am pleased to announce the release of Salt 0.7.0!
.sp
This release marks what is the first stable release of salt, 0.7.0 should be
suitable for general use.
.sp
0.7.0 Brings the following new features to Salt:
.INDENT 0.0
.IP \(bu 2
Integration with facter data from puppet labs
.IP \(bu 2
Allow for matching minions from the salt client via facter information
.IP \(bu 2
Minion job threading, many jobs can be executed from the master at once
.IP \(bu 2
Preview of master clustering support \- Still experimental
.IP \(bu 2
Introduce new minion modules for stats, virtualization, service management and more
.IP \(bu 2
Add extensive logging to the master and minion daemons
.IP \(bu 2
Add sys.reload_functions for dynamic function reloading
.IP \(bu 2
Greatly improve authentication
.IP \(bu 2
Introduce the saltkey command for managing public keys
.IP \(bu 2
Begin backend development preparatory to introducing butter
.IP \(bu 2
Addition of man pages for the core commands
.IP \(bu 2
Extended and cleaned configuration
.UNINDENT
.sp
0.7.0 Fixes the following major bugs:
.INDENT 0.0
.IP \(bu 2
Fix crash in minions when matching failed
.IP \(bu 2
Fix configuration file lookups for the local client
.IP \(bu 2
Repair communication bugs in encryption
.IP \(bu 2
Numerous fixes in the minion modules
.UNINDENT
.sp
The next release of Salt should see the following features:
.INDENT 0.0
.IP \(bu 2
Stabilize the cluster support
.IP \(bu 2
Introduce a remote client for salt command tiers
.IP \(bu 2
salt\-ftp system for distributed file copies
.IP \(bu 2
Initial support for "butter"
.UNINDENT
.sp
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.
.sp
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.
.sp
Special thanks to Joseph Hall for the status and network modules, and thanks
to Matthias Teege for tracking down some configuration bugs!
.sp
Salt can be downloaded from the following locations;
.sp
Source Tarball:
.sp
\fI\%https://github.com/downloads/saltstack/salt/salt-0.7.0.tar.gz\fP
.sp
Arch Linux Package:
.sp
\fI\%https://aur.archlinux.org/packages.php?ID=47512\fP
.sp
Please enjoy the latest Salt release!
.SS Salt 0.8.0 release notes
.sp
Salt 0.8.0 is ready for general consumption!
The source tarball is available on github for download:
.sp
\fI\%https://github.com/downloads/saltstack/salt/salt-0.8.0.tar.gz\fP
.sp
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!
.sp
The main new features of salt 0.8.0 are:
.sp
Salt\-cp
.sp
Cython minion modules
.sp
Dynamic returners
.sp
Faster return handling
.sp
Lowered required python version to 2.6
.sp
Advanced minion threading
.sp
Configurable minion modules
.SS Salt\-cp \-
.sp
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:
.sp
# salt\-cp ‘*’ /etc/hosts /etc/hosts
.sp
Will copy the local /etc/hosts file to all of the minions.
.sp
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.
.SS Cython minion modules \-
.sp
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.
.sp
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:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/modules/cytest.pyx\fP
.SS Dynamic Returners \-
.sp
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.
.sp
This means that a custom data returner can be added to communicate the return
data so anything from MySQL, redis, mongodb and more!
.sp
There are 2 simple stock returners in the returners directory:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/returners\fP
.sp
The documentation on writing returners will be added to the wiki shortly, and
returners can be written in pure python, or in cython.
.SS Configurable Minion Modules \-
.sp
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.
.sp
Information on how to use this simple addition has been added to the wiki:
\fI\%https://github.com/thatch45/salt/wiki/Writing-Salt-Modules\fP
.sp
The test module has an example of using the __opts__ dict, and how to set
default options:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/modules/test.py\fP
.SS Advanced Minion Threading:
.sp
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:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/conf/minion\fP
.sp
Lowered Supported Python to 2.6 \-
.sp
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.
.sp
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!
.sp
I hope you enjoy salt, while it is not yet 1.0 salt is completely viable and
usable!
.sp
\-Thomas S. Hatch
.SS Salt 0.8.7 release notes
.sp
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.
.sp
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.
.sp
I also recently gave a presentation to the Utah Python users group in Salt Lake
City, the slides from this presentation are available here:
\fI\%https://github.com/downloads/saltstack/salt/Salt.pdf\fP
.sp
The video from this presentation will be available shortly.
.sp
The major new features and changes in Salt 0.8.7 are:
.INDENT 0.0
.IP \(bu 2
Revamp ZeroMQ topology on the master for better scalability
.IP \(bu 2
State enforcement
.IP \(bu 2
Dynamic state enforcement managers
.IP \(bu 2
Extract the module loader into salt.loader
.IP \(bu 2
Make Job ids more granular
.IP \(bu 2
Replace facter functionality with the new salt grains interface
.IP \(bu 2
Support for “virtual” salt modules
.IP \(bu 2
Introduce the salt\-call command
.IP \(bu 2
Better debugging for minion modules
.UNINDENT
.sp
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.
.sp
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.
.sp
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 –
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/loader.py\fP
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
Salt is nearing the goal of 1.0, where the core feature set and capability is
complete!
.sp
Salt 0.8.7 can be downloaded from github here:
\fI\%https://github.com/downloads/saltstack/salt/salt-0.8.7.tar.gz\fP
.sp
\-Thomas S Hatch
.SS Salt 0.8.8 release notes
.sp
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:
\fI\%https://github.com/downloads/saltstack/salt/salt-0.8.8.tar.gz\fP
.sp
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:
\fI\%http://thatch45.github.com/salt-www/\fP
We still have a lot to add, and when the domain is set up I will post another
announcement.
.sp
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.
.sp
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.
.sp
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.
.sp
The salt state system can enforce the following states with many more to come:
Packages
Files
Services
Executing commands
Hosts
.sp
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.
.sp
The salt state system also supports isolated environments, as well as matching
code from several environments to a single salt minion.
.sp
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.
.sp
If you would like a more complete overview of Salt please watch the Salt
presentation:
Flash Video:
\fI\%http://blip.tv/thomas-s-hatch/salt-0-8-7-presentation-5180182\fP
OGV Video Download:
\fI\%http://blip.tv/file/get/Thatch45-Salt087Presentation416.ogv\fP
Slides:
\fI\%https://github.com/downloads/saltstack/salt/Salt.pdf\fP
.sp
\-Thomas S Hatch
.SS Salt 0.8.9 Release Notes
.sp
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!
.sp
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.
.sp
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.
.SS Download!
.sp
The Salt source can be downloaded from the salt github site:
.sp
\fI\%https://github.com/downloads/saltstack/salt/salt-0.8.9.tar.gz\fP
.sp
Or from PiPy:
.sp
\fI\%http://pypi.python.org/packages/source/s/salt/salt-0.8.9.tar.gz\fP
.sp
Here s the md5sum:
.sp
7d5aca4633bc22f59045f59e82f43b56
.sp
For instructions on how to set up Salt please see the \fBinstallation
instructions\fP.
.SS New Features
.SS Salt Run
.sp
A big feature is the addition of Salt run, the \fBsalt\-run\fP command allows for
master side execution modules to be made that gather specific information or
execute custom routines from the master.
.sp
Documentation for salt\-run can be found here:
.sp
\fI\%http://saltstack.org/ref/runners.html\fP
.SS Refined Outputters
.sp
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 \fBoutputter\fP for
functions in minion modules.
.SS Cross Calling Salt Modules
.sp
Salt modules can now call each other, the \fB__salt__\fP dict has been added to
the predefined references in minion modules. This new feature is documented in
the modules documentation:
.sp
\fI\%http://saltstack.org/ref/modules/index.html\fP
.SS Watch Option Added to Salt State System
.sp
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.
.SS Root Dir Option
.sp
Travis Cline has added the ability to define the option \fBroot_dir\fP which
allows the salt minion to operate in a subdir. This is a strong move in
supporting the minion running as an unprivileged user
.SS Config Files Defined in Variables
.sp
Thanks again to Travis Cline, the master and minion configuration file locations
can be defined in environment variables now.
.SS New Modules
.sp
Quite a few new modules, states, returners and runners have been made.
.SS New Minion Modules
.SS apt
.sp
Support for apt\-get has been added, this adds greatly improved Debian and
Ubuntu support to Salt!
.SS useradd and groupadd
.sp
Support for manipulating users and groups on Unix\-like systems.
.SS moosefs
.sp
Initial support for reporting on aspects of the distributed file system,
MooseFS. For more information on MooseFS please see: \fI\%http://moosefs.org\fP
.sp
Thanks to Joseph Hall for his work on MooseFS support.
.SS mount
.sp
Manage mounts and the fstab.
.SS puppet
.sp
Execute puppet on remote systems.
.SS shadow
.sp
Manipulate and manage the user password file.
.SS ssh
.sp
Interact with ssh keys.
.SS New States
.SS user and group
.sp
Support for managing users and groups in Salt States.
.SS mount
.sp
Enforce mounts and the fstab.
.SS New Returners
.SS mongo_return
.sp
Send the return information to a mongodb server.
.SS New Runners
.SS manage
.sp
Display minions that are up or down.
.SS Salt 0.9.0 Release Notes
.sp
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.
.sp
0.9.0 also introduces many more modules, improvements to the api and
improvements to the ZeroMQ systems.
.SS Download!
.sp
The Salt source can be downloaded from the salt github site:
.sp
\fI\%https://github.com/downloads/saltstack/salt/salt-0.9.0.tar.gz\fP
.sp
Or from PiPy:
.sp
\fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.0.tar.gz\fP
.sp
Here is the md5sum:
.sp
9a925da04981e65a0f237f2e77ddab37
.sp
For instructions on how to set up Salt please see the \fBinstallation
instructions\fP.
.SS New Features
.SS Salt Syndic
.sp
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.
.sp
\fI\%http://saltstack.org/ref/syndic.html\fP
.SS Peer Communication
.sp
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.
.sp
Peer communication is turned off by default but can be enabled via the \fBpeer\fP
option in the master configuration file. Documentation on the new peer
interface can be found here:
.sp
\fI\%http://saltstack.org/ref/peer.html\fP
.SS Easily Extensible API
.sp
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 \fBmaster.py\fP salt module:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/master.py\fP
.sp
The \fBMaster\fP class extends the \fBSMaster\fP class and set up the main master
server.
.sp
The minion functions can now also be easily added to another application via
the \fBSMinion\fP class, this class can be found in the \fBminion.py\fP module:
.sp
\fI\%https://github.com/saltstack/salt/blob/v0.9.5/salt/minion.py\fP
.SS Cleaner Key Management
.sp
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.
.sp
The \-d option has also been added to the salt\-key command allowing for easy
removal of accepted public keys.
.sp
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.
.SS Improved 0MQ Master Workers
.sp
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.
.SS New Modules
.sp
Quite a few new modules have been made.
.SS New Minion Modules
.SS apache
.sp
Work directly with apache servers, great for managing balanced web servers
.SS cron
.sp
Read out the contents of a systems crontabs
.SS mdadm
.sp
Module to manage raid devices in Linux, appears as the \fBraid\fP module
.SS mysql
.sp
Gather simple data from MySQL databases
.SS ps
.sp
Extensive utilities for managing processes
.SS publish
.sp
Used by the peer interface to allow minions to make publications
.SS Salt 0.9.2 Release Notes
.sp
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.
.sp
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!
.sp
0.9.2 also fixes a number of bugs found on python 2.6.
.SS Download!
.sp
The Salt source can be downloaded from the salt github site:
.sp
\fI\%https://github.com/downloads/saltstack/salt/salt-0.9.2.tar.gz\fP
.sp
Or from PiPy:
.sp
\fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.2.tar.gz\fP
.sp
For instructions on how to set up Salt please see the \fBinstallation
instructions\fP.
.SS New Features
.SS Salt\-Call Additions
.sp
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.
.sp
The end result is that the salt\-call command can execute the state system and
return clean output:
.sp
.nf
.ft C
# salt\-call state.highstate
.ft P
.fi
.SS State System Fixes
.sp
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:
.sp
\fI\%https://github.com/thatch45/salt-states\fP
.sp
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!
.SS Notable Bug Fixes
.SS Python 2.6 String Formatting
.sp
Python 2.6 does not support format strings without an index identifier, all of
them have been repaired.
.SS Cython Loading Disabled by Default
.sp
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.
.SS Salt 0.9.3 Release Notes
.sp
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.
.sp
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.
.SS Download!
.sp
The Salt source can be downloaded from the salt github site:
.sp
\fI\%https://github.com/downloads/saltstack/salt/salt-0.9.3.tar.gz\fP
.sp
Or from PiPy:
.sp
\fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.3.tar.gz\fP
.sp
For instructions on how to set up Salt please see the \fBinstallation
instructions\fP.
.SS New Features
.SS WAN Support
.sp
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.
.SS State System Fixes
.sp
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.
.sp
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.
.sp
Error reporting has also been introduced, issues found in sls files will now
be clearly reported when executing Salt States.
.SS Extend Declaration
.sp
The Salt States have also gained the \fBextend\fP 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:
.sp
.nf
.ft C
include:
  \- apache

extend:
  apache:
    service:
      \- require:
        \- pkg: mod_python

mod_python:
  pkg:
    \- installed
.ft P
.fi
.sp
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.
.SS Highstate Structure Specification
.sp
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.
.sp
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.
.SS SheBang Renderer Switch
.sp
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.
.sp
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.
.SS Python State Renderer
.sp
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:
.sp
.nf
.ft C
#!py

def run():
    \(aq\(aq\(aq
    Install the python\-mako package
    \(aq\(aq\(aq
    return {\(aqinclude\(aq: [\(aqpython\(aq],
            \(aqpython\-mako\(aq: {\(aqpkg\(aq: [\(aqinstalled\(aq]}}
.ft P
.fi
.sp
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.
.sp
This example of a pure python sls module is the same as this example in yaml:
.sp
.nf
.ft C
include:
  \- python

python\-mako:
  pkg:
    \- installed
.ft P
.fi
.SS FreeBSD Support
.sp
Additional support has been added for FreeBSD, this is Salt\(aqs first branch out
of the Linux world and proves the viability of Salt on non\-Linux platforms.
.sp
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.
.sp
The new freebsdpkg module provides package management support for FreeBSD
and the new pw_user and pw_group provide user and group management.
.SS Module and State Additions
.SS Cron Support
.sp
Support for managing the system crontab has been added, declaring a cron state
can be done easily:
.sp
.nf
.ft C
date > /tmp/datestamp:
  cron:
    \- present
    \- user: fred
    \- minute: 5
    \- hour: 3
.ft P
.fi
.SS File State Additions
.sp
The file state has been given a number of new features, primarily the
directory, recurse, symlink and absent functions.
.INDENT 0.0
.TP
.B file.directory
Make sure that a directory exists and has the right permissions.
.sp
.nf
.ft C
/srv/foo:
  file:
    \- directory
    \- user: root
    \- group: root
    \- mode: 1755
.ft P
.fi
.TP
.B file.symlink
Make a symlink.
.sp
.nf
.ft C
/var/lib/www:
  file:
    \- symlink
    \- target: /srv/www
    \- force: True
.ft P
.fi
.TP
.B 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 recuse function is very
powerful and has been tested by pushing out the full Linux kernel source.
.sp
.nf
.ft C
/opt/code:
  file:
    \- recurse
    \- source: salt://linux
.ft P
.fi
.TP
.B file.absent
Make sure that the file is not on the system, recursively delets
directories, files and symlinks.
.sp
.nf
.ft C
/etc/httpd/conf.d/somebogusfile.conf:
  file:
    \- absent
.ft P
.fi
.UNINDENT
.SS Sysctl Module and State
.sp
The sysctl module and state allows for sysctl components in the kernel to be
managed easily. the sysctl module contains the following functions:
.INDENT 0.0
.TP
.B sysctl.show
Return a list of sysctl parameters for this minion
.TP
.B sysctl.get
Return a single sysctl parameter for this minion
.TP
.B sysctl.assign
Assign a single sysctl parameter for this minion
.TP
.B sysctl.persist
Assign and persist a simple sysctl parameter for this minion
.UNINDENT
.sp
The sysctl state allows for sysctl parameters to be assigned:
.sp
.nf
.ft C
vm.swappiness:
  sysctl:
    \- present
    \- value: 20
.ft P
.fi
.SS Kernel Module Management
.sp
A module for managing Linux kernel modules has been added. The new functions
are as follows:
.INDENT 0.0
.TP
.B kmod.available
Return a list of all available kernel modules
.TP
.B kmod.check_available
Check to see if the specified kernel module is available
.TP
.B kmod.lsmod
Return a dict containing information about currently loaded modules
.TP
.B kmod.load
Load the specified kernel module
.TP
.B kmod.remove
Unload the specified kernel module
.UNINDENT
.sp
The kmod state can enforce modules be either present or absent:
.sp
.nf
.ft C
kvm_intel:
  kmod:
    \- present
.ft P
.fi
.SS Ssh Authorized Keys
.sp
The ssh_auth state can distribute ssh authorized keys out to minions. Ssh
authorized keys can be present or absent.
.sp
.nf
.ft C
AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyYvlRBsJdDOo49CNfhlWHWXQRqul6rwL4KIuPrhY7hBw0tV7UNC7J9IZRNO4iGod9C+OYutuWGJ2x5YNf7P4uGhH9AhBQGQ4LKOLxhDyT1OrDKXVFw3wgY3rHiJYAbd1PXNuclJHOKL27QZCRFjWSEaSrUOoczvAAAAFQD9d4jp2dCJSIseSkk4Lez3LqFcqQAAAIAmovHIVSrbLbXAXQE8eyPoL9x5C+x2GRpEcA7AeMH6bGx/xw6NtnQZVMcmZIre5Elrw3OKgxcDNomjYFNHuOYaQLBBMosyO++tJe1KTAr3A2zGj2xbWO9JhEzu8xvSdF8jRu0N5SRXPpzSyU4o1WGIPLVZSeSq1VFTHRT4lXB7PQAAAIBXUz6ZO0bregF5xtJRuxUN583HlfQkXvxLqHAGY8WSEVlTnuG/x75wolBDbVzeTlxWxgxhafj7P6Ncdv25Wz9wvc6ko/puww0b3rcLNqK+XCNJlsM/7lB8Q26iK5mRZzNsGeGwGTyzNIMBekGYQ5MRdIcPv5dBIP/1M6fQDEsAXQ==:
  ssh_auth:
    \- present
    \- user: frank
    \- enc: dsa
    \- comment: \(aqFrank\(aqs key\(aq
.ft P
.fi
.SS Salt 0.9.4 Release Notes
.sp
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 \fBorder\fP option.
.sp
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.
.SS Download!
.sp
The Salt source can be downloaded from the salt github site:
.sp
\fI\%https://github.com/downloads/saltstack/salt/salt-0.9.4.tar.gz\fP
.sp
Or from PiPy:
.sp
\fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.4.tar.gz\fP
.sp
For instructions on how to set up Salt please see the \fBinstallation
instructions\fP.
.SS New Features
.SS Failhard State Option
.sp
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.
.sp
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
\fBfailing hard\fP.
.SS State Level Failhard
.sp
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:
.sp
.nf
.ft C
/etc/yum.repos.d/company.repo:
  file:
    \- managed
    \- source: salt://company/yumrepo.conf
    \- user: root
    \- group: root
    \- mode: 644
    \- order: 1
    \- failhard: True
.ft P
.fi
.sp
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.
.SS Global Failhard
.sp
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.
.sp
This is NOT the default behavior, normally Salt will only fail states that
require a failed state.
.sp
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.
.sp
To use the global failhard set failhard: True in the master configuration
.SS Finite Ordering of State Execution
.sp
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.
.sp
A few tools exist in Salt to set up the correct state ordering, these tools
consist of requisite declarations and order options.
.SS The Order Option
.sp
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.
.sp
The order option is used by adding an order number to a state declaration
with the option \fIorder\fP:
.sp
.nf
.ft C
vim:
  pkg:
    \- installed
    \- order: 1
.ft P
.fi
.sp
By adding the order option to \fI1\fP this ensures that the vim package will be
installed in tandem with any other state declaration set to the order \fI1\fP.
.sp
Any state declared without an order option will be executed after all states
with order options are executed.
.sp
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:
.sp
.nf
.ft C
vim:
  pkg:
    \- installed
    \- order: last
.ft P
.fi
.sp
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.
.sp
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.
.sp
Error reporting has also been introduced, issues found in sls files will now
be clearly reported when executing Salt States.
.SS Gentoo Support
.sp
Additional experimental support has been added for Gentoo. This is found in
the contribution from Doug Renn, aka nestegg.
.SS Salt 0.9.5 Release Notes
.sp
Salt 0.9.5 is one of the largest steps forward in the development of Salt.
.sp
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.
.SS Community
.sp
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.
.sp
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:
.sp
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
.sp
This makes 21 new developers since 0.9.4 was released!
.sp
To keep up with the growing community follow Salt on Ohloh
(\fI\%http://www.ohloh.net/p/salt\fP), to join the Salt development community, fork
Salt on Github, and get coding (\fI\%https://github.com/saltstack/salt\fP)!
.SS Major Features
.SS SPEED! Pickle to msgpack
.sp
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 (\fI\%http://msgpack.org/\fP) 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.
.sp
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.
.sp
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.
.sp
Therefore the suggested methods for upgrading are either to just upgrade
everything at once, or to upgrade the master to 0.9.5, set "serial: pickle" in
the master config, upgrade the minions, and then remove the serial option from
the 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.
.SS C Bindings for YAML
.sp
All of the YAML rendering is now done with the YAML C bindings. This speeds up
all of the sls files when running states.
.SS Experimental Windows Support
.sp
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.
.sp
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!
.SS Dynamic Module Distribution
.sp
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:
.SS Modules via States
.sp
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
.INDENT 0.0
.INDENT 3.5
modules can be deployed and used in the same state run.
.UNINDENT
.UNINDENT
.SS Modules via Module Environment Directories
.sp
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 "saltutil.sync_all".
.sp
The directories are named:
_modules
_states
_grains
_renderers
_returners
.sp
The modules are pushed to their respective scopes on the minions.
.SS Module Reloading
.sp
Modules can now be reloaded without restarting the minion, this is done by
calling the sys.reload_modules function.
.sp
But wait, there\(aqs 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.
.sp
Finally, all modules are reloaded when modules are dynamically distributed
from the salt master.
.SS Enable / Disable Added to Service
.sp
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.
.sp
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.
.SS Compound Target
.sp
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.
.sp
These targets can also be separated by and/or operators, so certain properties
can be used to omit a node:
.sp
salt \-C \(aqwebserv* and \fI\%G@os\fP:Debian or \fI\%E@db.*\fP\(aq test.ping
.sp
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.
.SS Node Groups
.sp
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:
.INDENT 0.0
.TP
.B nodegroups:
group1: \fI\%'L@foo.domain.com\fP,bar.domain.com,baz.domain.com and bl*.domain.com\(aq
group2: \fI\%'G@os\fP:Debian and foo.domain.com\(aq
.UNINDENT
.sp
And then used via the \-N option:
.sp
salt \-N group1 test.ping
.SS Minion Side Data Store
.sp
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.
.sp
The Minion datastore is young, and will eventually provide an interface similar
to a more mature key/value pair server.
.SS Major Grains Improvement
.sp
The Salt grains have been overhauled to include a massive amount of extra data.
this includes hardware data, os data and salt specific data.
.SS Salt \-Q is Useful Now
.sp
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.
.sp
0.9.5 has added the outputter system to the \-Q option, thus enabling the salt
query system to return readable output.
.SS Packaging Updates
.sp
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.
.SS FreeBSD
.sp
Salt on FreeBSD? There a port for that:
.sp
\fI\%http://www.freebsd.org/cgi/cvsweb.cgi/ports/sysutils/salt/pkg-descr\fP
.sp
This port was developed and added by Christer Edwards. This also marks the
first time Salt has been included in an upstream packaging system!
.SS Fedora and Red Hat Enterprise
.sp
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).
.SS Debian/Ubuntu
.sp
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.
.sp
These packages have been prepared with the help of:
Corey
Aaron Toponce
and\(ga
.SS More to Come
.sp
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.
.SS Refinement
.sp
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.
.SS More Testing, More BugFixes
.sp
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.
.SS Custom Exceptions
.sp
A custom exception module has been added to throw salt specific exceptions.
This allows Salt to give much more granular error information.
.SS New Modules
.SS data
.sp
The new data module manages a persistent datastore on the minion.
Big thanks to bastichelaar for his help refining this module
.SS freebsdkmod
.sp
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
.SS gentoo_service
.sp
Support has been added for managing services in Gentoo. Now Gentoo services
can be started, stopped, restarted, enabled, disabled and viewed.
.SS pip
.sp
The pip module introduces management for pip installed applications.
Thanks goes to whitinge for the addition of the pip module
.SS rh_service
.sp
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
.SS saltutil
.sp
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.
.SS systemd
.sp
Systemd support has been added to Salt, now systems using this next generation
init system are supported on systems running systemd.
.SS virtualenv
.sp
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
.SS win_disk
.sp
Support for gathering disk information on Microsoft Windows minions
The windows modules come courtesy of Utah_Dave
.SS win_service
.sp
The win_service module adds service support to Salt for Microsoft Windows
services
.SS win_useradd
.sp
Salt can now manage local users on Microsoft Windows Systems
.SS yumpkg5
.sp
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.
.sp
The yumpkg5 module bypasses this issue by shelling out to yum on systems where
the yum api is not available.
.SS New States
.SS mysql_database
.sp
The new mysql_database state adds the ability to systems running a mysql
server to manage the existence of mysql databases.
.sp
The mysql states are thanks to syphernl
.SS mysql_user
.sp
The mysql_user state enables mysql user management.
.SS virtualenv
.sp
The virtualenv state can manage the state of python virtual environments.
Thanks to Whitinge for the virtualenv state
.SS New Returners
.SS cassandra_returner
.sp
A returnerer allowing Salt to send data to a cassandra server.
Thanks to Byron Clark for contributing this returner
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.