valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-08 17:33:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
4d0ea7a863
salt/doc/man/salt.7

148467 lines
3.2 MiB
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

.\" Man page generated from reStructuredText.
.
.TH "SALT" "7" "March 10, 2015" "2014.7.2-280-g6ac6a53" "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
..
.SH INTRODUCTION TO SALT
We’re not just talking about NaCl..SS The 30 second summary
.sp
Salt is:
.INDENT 0.0
.IP \(bu 2
a configuration management system, capable of maintaining remote nodes
in defined states (for example, ensuring that specific packages are installed and
specific services are running)
.IP \(bu 2
a distributed remote execution system used to execute commands and
query data on remote nodes, either individually or by arbitrary
selection criteria
.UNINDENT
.sp
It was developed in order to bring the best solutions found in the
world of remote execution together and make them better, faster, and more
malleable. Salt accomplishes this through its ability to handle large loads of
information, and not just dozens but hundreds and even thousands of individual
servers quickly through a simple and manageable interface.
.SS Simplicity
.sp
Providing versatility between massive scale deployments and smaller systems may seem
daunting, but Salt is very simple to set up and maintain, regardless of the
size of the project. The architecture of Salt is designed to work with any
number of servers, from a handful of local network systems to international
deployments across different data centers. The topology is a simple
server/client model with the needed functionality built into a single set of
daemons. While the default configuration will work with little to no
modification, Salt can be fine tuned to meet specific needs.
.SS Parallel execution
.sp
The core functions of Salt:
.INDENT 0.0
.IP \(bu 2
enable commands to remote systems to be called in parallel rather than serially
.IP \(bu 2
use a secure and encrypted protocol
.IP \(bu 2
use the smallest and fastest network payloads possible
.IP \(bu 2
provide a simple programming interface
.UNINDENT
.sp
Salt also introduces more granular controls to the realm of remote
execution, allowing systems to be targeted not just by hostname, but
also by system properties.
.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 the Salt daemon includes a viable and transparent AMQ
broker. Salt uses public keys for authentication with the master
daemon, then uses faster \fI\%AES\fP encryption for payload communication;
authentication and encryption are integral to Salt. Salt takes
advantage of communication via \fI\%msgpack\fP, 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. 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 at high speed on
target server groups ranging from one to very many servers. Salt is
very fast, easy to set up, amazingly malleable and provides a single
remote execution architecture that can manage the diverse
requirements of any number of servers. The Salt infrastructure
brings together the best of the remote execution world, amplifies its
capabilities and expands its range, resulting in a system that is as
versatile as it is practical, suitable for any network.
.SS Open
.sp
Salt is developed under the \fI\%Apache 2.0 license\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.
Please feel free to sprinkle Salt around your systems and let the
deliciousness come forth.
.SS Salt 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\%https://groups.google.com/forum/#!forum/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.
.sp
\fI\%Logs of the IRC channel activity\fP are being collected courtesy of Moritz Lenz.
.sp
If you wish to discuss the development of Salt itself join us in
\fB#salt\-devel\fP\&.
.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 Blogs
.sp
SaltStack Inc. keeps a \fI\%blog\fP with recent news and advancements:
.sp
\fI\%http://www.saltstack.com/blog/\fP
.sp
Thomas Hatch also shares news and thoughts on Salt and related projects in his personal blog \fI\%The Red45\fP:
.sp
\fI\%http://red45.wordpress.com/\fP
.SS Example Salt States
.sp
The official \fBsalt\-states\fP repository is:
\fI\%https://github.com/saltstack/salt\-states\fP
.sp
A few examples of salt states from the community:
.INDENT 0.0
.IP \(bu 2
\fI\%https://github.com/blast\-hardcheese/blast\-salt\-states\fP
.IP \(bu 2
\fI\%https://github.com/kevingranade/kevingranade\-salt\-state\fP
.IP \(bu 2
\fI\%https://github.com/uggedal/states\fP
.IP \(bu 2
\fI\%https://github.com/mattmcclean/salt\-openstack/tree/master/salt\fP
.IP \(bu 2
\fI\%https://github.com/rentalita/ubuntu\-setup/\fP
.IP \(bu 2
\fI\%https://github.com/brutasse/states\fP
.IP \(bu 2
\fI\%https://github.com/bclermont/states\fP
.IP \(bu 2
\fI\%https://github.com/pcrews/salt\-data\fP
.UNINDENT
.SS Follow on ohloh
.sp
\fI\%https://www.ohloh.net/p/salt\fP
.SS Other community links
.INDENT 0.0
.IP \(bu 2
\fI\%Salt Stack Inc.\fP
.IP \(bu 2
\fI\%Subreddit\fP
.IP \(bu 2
\fI\%Google+\fP
.IP \(bu 2
\fI\%YouTube\fP
.IP \(bu 2
\fI\%Facebook\fP
.IP \(bu 2
\fI\%Twitter\fP
.IP \(bu 2
\fI\%Wikipedia page\fP
.UNINDENT
.SS Hack the Source
.sp
If you want to get involved with the development of source code or the
documentation efforts, please review the \fBhacking section\fP!
.SH INSTALLATION
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBInstalling Salt for development\fP and
contributing to the project.
.UNINDENT
.UNINDENT
.SS Quick Install
.sp
On most distributions, you can set up a \fBSalt Minion\fP with the
\fI\%Salt Bootstrap\fP\&.
.SS Platform\-specific Installation Instructions
.sp
These guides go into detail how to install Salt on a given platform.
.SS Arch Linux
.SS Installation
.sp
Salt (stable) is currently available via the Arch Linux Official repositories.
There are currently \-git packages available in the Arch User repositories (AUR)
as well.
.SS Stable Release
.sp
Install Salt stable releases from the Arch Linux Official repositories as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pacman \-S salt\-zmq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To install Salt stable releases using the \fBRAET protocol\fP,
use the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pacman \-S salt\-raet
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Tracking develop
.sp
To install the bleeding edge version of Salt (\fBmay include bugs!\fP),
use the \-git package. Installing the \-git package as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget https://aur.archlinux.org/packages/sa/salt\-git/salt\-git.tar.gz
tar xf salt\-git.tar.gz
cd salt\-git/
makepkg \-is
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
yaourt
.sp
If a tool such as \fI\%Yaourt\fP is used, the dependencies will be
gathered and built automatically.
.sp
The command to install salt using the yaourt tool is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yaourt salt\-git
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Post\-installation tasks
.sp
\fBsystemd\fP
.sp
Activate the Salt Master and/or Minion via \fBsystemctl\fP as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl enable salt\-master.service
systemctl enable salt\-minion.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBStart the Master\fP
.sp
Once you\(aqve completed all of these steps you\(aqre ready to start your Salt
Master. You should be able to start your Salt Master now using the command
seen here:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl start salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS Debian Installation
.sp
Currently the latest packages for Debian Old Stable, Stable and
Unstable (Squeeze, Wheezy and Sid) are published in our
(saltstack.com) Debian repository.
.SS Configure Apt
.SS Squeeze (Old Stable)
.sp
For squeeze, you will need to enable the Debian backports repository
as well as the debian.saltstack.com repository. To do so, add the
following to \fB/etc/apt/sources.list\fP or a file in
\fB/etc/apt/sources.list.d\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
deb http://debian.saltstack.com/debian squeeze\-saltstack main
deb http://backports.debian.org/debian\-backports squeeze\-backports main contrib non\-free
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Wheezy (Stable)
.sp
For wheezy, the following line is needed in either
\fB/etc/apt/sources.list\fP or a file in \fB/etc/apt/sources.list.d\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
deb http://debian.saltstack.com/debian wheezy\-saltstack main
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Jessie (Testing)
.sp
For jessie, the following line is needed in either
\fB/etc/apt/sources.list\fP or a file in \fB/etc/apt/sources.list.d\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
deb http://debian.saltstack.com/debian jessie\-saltstack main
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Sid (Unstable)
.sp
For sid, the following line is needed in either
\fB/etc/apt/sources.list\fP or a file in \fB/etc/apt/sources.list.d\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
deb http://debian.saltstack.com/debian unstable main
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Import the repository key.
.sp
You will need to import the key used for signing.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-q \-O\- "http://debian.saltstack.com/debian\-salt\-team\-joehealy.gpg.key" | apt\-key add \-
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
You can optionally verify the key integrity with \fBsha512sum\fP using the
public key signature shown here. E.g:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo "b702969447140d5553e31e9701be13ca11cc0a7ed5fe2b30acb8491567560ee62f834772b5095d735dfcecb2384a5c1a20045f52861c417f50b68dd5ff4660e6 debian\-salt\-team\-joehealy.gpg.key" | sha512sum \-c
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Update the package database
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apt\-get update
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Install packages
.sp
Install the Salt master, minion, or syndic from the repository with the apt\-get
command. These examples each install one daemon, but more than one package name
may be given at a time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apt\-get install salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apt\-get install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apt\-get install salt\-syndic
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Post\-installation tasks
.sp
Now, go to the \fBConfiguring Salt\fP page.
.SS Notes
.sp
1. These packages will be backported from the packages intended to be
uploaded into Debian unstable. This means that the packages will be
built for unstable first and then backported over the next day or so.
.sp
2. These packages will be tracking the released versions of salt
rather than maintaining a stable fixed feature set. If a fixed version
is what you desire, then either pinning or manual installation may be
more appropriate for you.
.sp
3. The version numbering and backporting process should provide clean
upgrade paths between Debian versions.
.sp
If you have any questions regarding these, please email the mailing
list or look for joehh on IRC.
.SS Fedora
.sp
Beginning with version 0.9.4, Salt has been available in the primary Fedora
repositories and \fI\%EPEL\fP\&. It is installable using yum. Fedora will have more
up to date versions of Salt than other members of the Red Hat family, which
makes it a great place to help improve Salt!
.sp
\fBWARNING\fP: Fedora 19 comes with systemd 204. Systemd has known bugs fixed in
later revisions that prevent the salt\-master from starting reliably or opening
the network connections that it needs to. It\(aqs not likely that a salt\-master
will start or run reliably on any distribution that uses systemd version 204 or
earlier. Running salt\-minions should be OK.
.SS Installation
.sp
Salt can be installed using \fByum\fP and is available in the standard Fedora
repositories.
.SS Stable Release
.sp
Salt is packaged separately for the minion and the master. It is necessary only to
install the appropriate package for the role the machine will play. Typically, there
will be one master and multiple minions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yum install salt\-master
yum install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Installing from \fBupdates\-testing\fP
.sp
When a new Salt release is packaged, it is first admitted into the
\fBupdates\-testing\fP repository, before being moved to the stable repo.
.sp
To install from \fBupdates\-testing\fP, use the \fBenablerepo\fP argument for yum:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yum \-\-enablerepo=updates\-testing install salt\-master
yum \-\-enablerepo=updates\-testing install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Post\-installation tasks
.sp
\fBMaster\fP
.sp
To have the Master start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl enable salt\-master.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl start salt\-master.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBMinion\fP
.sp
To have the Minion start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl enable salt\-minion.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl start salt\-minion.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS FreeBSD
.sp
Salt was added to the FreeBSD ports tree Dec 26th, 2011 by Christer Edwards
<\fI\%christer.edwards@gmail.com\fP>. It has been tested on FreeBSD 7.4, 8.2, 9.0 and 9.1
releases.
.sp
Salt is dependent on the following additional ports. These will be installed as
dependencies of the \fBsysutils/py\-salt\fP port:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/devel/py\-yaml
/devel/py\-pyzmq
/devel/py\-Jinja2
/devel/py\-msgpack
/security/py\-pycrypto
/security/py\-m2crypto
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Installation
.sp
On FreeBSD 10 and later, to install Salt from the FreeBSD pkgng repo, use the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pkg install py27\-salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On older versions of FreeBSD, to install Salt from the FreeBSD ports tree, use the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make \-C /usr/ports/sysutils/py\-salt install clean
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Post\-installation tasks
.sp
\fBMaster\fP
.sp
Copy the sample configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cp /usr/local/etc/salt/master.sample /usr/local/etc/salt/master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBrc.conf\fP
.sp
Activate the Salt Master in \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+ salt_master_enable="YES"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBStart the Master\fP
.sp
Start the Salt Master as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
service salt_master start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBMinion\fP
.sp
Copy the sample configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cp /usr/local/etc/salt/minion.sample /usr/local/etc/salt/minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBrc.conf\fP
.sp
Activate the Salt Minion in \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+ salt_minion_enable="YES"
+ salt_minion_paths="/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBStart the Minion\fP
.sp
Start the Salt Minion as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
service salt_minion start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS Gentoo
.sp
Salt can be easily installed on Gentoo via Portage:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
emerge app\-admin/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Post\-installation tasks
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS OS X
.SS Dependency Installation
.sp
When installing via Homebrew, dependency resolution is handled for you.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
brew install saltstack
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When using macports, zmq, swig, and pip may need to be installed this way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo port install py\-zmq
sudo port install py27\-m2crypto
sudo port install py27\-crypto
sudo port install py27\-msgpack
sudo port install swig\-python
sudo port install py\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For installs using the OS X system python, pip install needs to use \(aqsudo\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo pip install salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Salt\-Master Customizations
.sp
To run salt\-master on OS X, the root user maxfiles limit must be increased:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo launchctl limit maxfiles 4096 8192
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And sudo add this configuration option to the /etc/salt/master file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
max_open_files: 8192
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the salt\-master should run without errors:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo /usr/local/share/python/salt\-master \-\-log\-level=all
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Post\-installation tasks
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux
.SS Installation Using pip
.sp
Since Salt is on \fI\%PyPI\fP, it can be installed using pip, though most users
prefer to install using RPMs (which can be installed from \fI\%EPEL\fP).
Installation from pip is easy:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
If installing from pip (or from source using \fBsetup.py install\fP), be
advised that the \fByum\-utils\fP package is needed for Salt to manage
packages. Also, if the Python dependencies are not already installed, then
you will need additional libraries/tools installed to build some of them.
More information on this can be found \fIhere\fP\&.
.UNINDENT
.UNINDENT
.SS Installation from Repository
.SS RHEL/CentOS 5
.sp
Due to the removal of some of Salt\(aqs dependencies from EPEL5, we have created a
repository on \fI\%Fedora COPR\fP\&. Moving forward, this will be the official means
of installing Salt on RHEL5\-based systems. Information on how to enable this
repository can be found \fI\%here\fP\&.
.SS RHEL/CentOS 6 and 7, Scientific Linux, etc.
.sp
Beginning with version 0.9.4, Salt has been available in \fI\%EPEL\fP\&. It is
installable using yum. Salt should work properly with all mainstream
derivatives of RHEL, including CentOS, Scientific Linux, Oracle Linux and
Amazon Linux. Report any bugs or issues on the \fI\%issue tracker\fP\&.
.sp
On RHEL6, the proper Jinja package \(aqpython\-jinja2\(aq was moved from EPEL to the
"RHEL Server Optional Channel". Verify this repository is enabled before
installing salt on RHEL6.
.SS Enabling EPEL
.sp
If the EPEL repository is not installed on your system, you can download the
RPM from \fI\%here\fP for RHEL/CentOS 6 (or \fI\%here\fP for RHEL/CentOS 7) and install it
using the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rpm \-Uvh epel\-release\-X\-Y.rpm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Replace \fBepel\-release\-X\-Y.rpm\fP with the appropriate filename.
.SS Installing Stable Release
.sp
Salt is packaged separately for the minion and the master. It is necessary only
to install the appropriate package for the role the machine will play.
Typically, there will be one master and multiple minions.
.sp
On the salt\-master, run this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yum install salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On each salt\-minion, run this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yum install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Installing from \fBepel\-testing\fP
.sp
When a new Salt release is packaged, it is first admitted into the
\fBepel\-testing\fP repository, before being moved to the stable repo.
.sp
To install from \fBepel\-testing\fP, use the \fBenablerepo\fP argument for yum:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yum \-\-enablerepo=epel\-testing install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS ZeroMQ 4
.sp
We recommend using ZeroMQ 4 where available. SaltStack provides ZeroMQ 4.0.4
and pyzmq 14.3.1 in a \fI\%COPR\fP repository. Instructions for adding this repository
(as well as for upgrading ZeroMQ and pyzmq on existing minions) can be found
\fI\%here\fP\&.
.sp
If this repo is added \fIbefore\fP Salt is installed, then installing either
\fBsalt\-master\fP or \fBsalt\-minion\fP will automatically pull in ZeroMQ 4.0.4, and
additional states to upgrade ZeroMQ and pyzmq are unnecessary.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For RHEL/CentOS 5 installations, if using the new repository to install
Salt (as detailed \fI\%above\fP), then it is not
necessary to enable the zeromq4 COPR, as the new EL5 repository includes
ZeroMQ 4.
.UNINDENT
.UNINDENT
.SS Package Management
.sp
Salt\(aqs interface to \fByum\fP makes heavy use of the
\fBrepoquery\fP utility, from the \fI\%yum\-utils\fP package. This package will be
installed as a dependency if salt is installed via EPEL. However, if salt has
been installed using pip, or a host is being managed using salt\-ssh, then as of
version 2014.7.0 \fI\%yum\-utils\fP will be installed automatically to satisfy this
dependency.
.SS Post\-installation tasks
.sp
\fBMaster\fP
.sp
To have the Master start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chkconfig salt\-master on
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
service salt\-master start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBMinion\fP
.sp
To have the Minion start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chkconfig salt\-minion on
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
service salt\-minion start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS Solaris
.sp
Salt was added to the OpenCSW package repository in September of 2012 by Romeo
Theriault <\fI\%romeot@hawaii.edu\fP> at version 0.10.2 of Salt. It has mainly been
tested on Solaris 10 (sparc), though it is built for and has been tested
minimally on Solaris 10 (x86), Solaris 9 (sparc/x86) and 11 (sparc/x86).
(Please let me know if you\(aqre using it on these platforms!) Most of the testing
has also just focused on the minion, though it has verified that the master
starts up successfully on Solaris 10.
.sp
Comments and patches for better support on these platforms is very welcome.
.sp
As of version 0.10.4, Solaris is well supported under salt, with all of the
following working well:
.INDENT 0.0
.IP 1. 3
remote execution
.IP 2. 3
grain detection
.IP 3. 3
service control with SMF
.IP 4. 3
\(aqpkg\(aq states with \(aqpkgadd\(aq and \(aqpkgutil\(aq modules
.IP 5. 3
cron modules/states
.IP 6. 3
user and group modules/states
.IP 7. 3
shadow password management modules/states
.UNINDENT
.sp
Salt is dependent on the following additional packages. These will
automatically be installed as dependencies of the \fBpy_salt\fP package:
.INDENT 0.0
.IP \(bu 2
py_yaml
.IP \(bu 2
py_pyzmq
.IP \(bu 2
py_jinja2
.IP \(bu 2
py_msgpack_python
.IP \(bu 2
py_m2crypto
.IP \(bu 2
py_crypto
.IP \(bu 2
python
.UNINDENT
.SS Installation
.sp
To install Salt from the OpenCSW package repository you first need to install
\fI\%pkgutil\fP assuming you don\(aqt already have it installed:
.sp
On Solaris 10:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pkgadd \-d http://get.opencsw.org/now
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Solaris 9:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget http://mirror.opencsw.org/opencsw/pkgutil.pkg
pkgadd \-d pkgutil.pkg all
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once pkgutil is installed you\(aqll need to edit it\(aqs config file
\fB/etc/opt/csw/pkgutil.conf\fP to point it at the unstable catalog:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- #mirror=http://mirror.opencsw.org/opencsw/testing
+ mirror=http://mirror.opencsw.org/opencsw/unstable
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
OK, time to install salt.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Update the catalog
root> /opt/csw/bin/pkgutil \-U
# Install salt
root> /opt/csw/bin/pkgutil \-i \-y py_salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Minion Configuration
.sp
Now that salt is installed you can find it\(aqs configuration files in
\fB/etc/opt/csw/salt/\fP\&.
.sp
You\(aqll want to edit the minion config file to set the name of your salt master
server:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- #master: salt
+ master: your\-salt\-server
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you would like to use \fI\%pkgutil\fP as the default package provider for your
Solaris minions, you can do so using the \fBproviders\fP option in the
minion config file.
.sp
You can now start the salt minion like so:
.sp
On Solaris 10:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svcadm enable salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Solaris 9:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/init.d/salt\-minion start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You should now be able to log onto the salt master and check to see if the
salt\-minion key is awaiting acceptance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-key \-l un
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Accept the key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-key \-a <your\-salt\-minion>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Run a simple test against the minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq<your\-salt\-minion>\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Troubleshooting
.sp
Logs are in \fB/var/log/salt\fP
.SS Ubuntu Installation
.SS Add repository
.sp
The latest packages for Ubuntu are published in the saltstack PPA. If you have
the \fBadd\-apt\-repository\fP utility, you can add the repository and import the
key in one step:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo add\-apt\-repository ppa:saltstack/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "add\-apt\-repository: command not found?"
.sp
The \fBadd\-apt\-repository\fP command is not always present on Ubuntu systems.
This can be fixed by installing \fIpython\-software\-properties\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get install python\-software\-properties
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that since Ubuntu 12.10 (Raring Ringtail), \fBadd\-apt\-repository\fP is
found in the \fIsoftware\-properties\-common\fP package, and is part of the base
install. Thus, \fBadd\-apt\-repository\fP should be able to be used
out\-of\-the\-box to add the PPA.
.UNINDENT
.UNINDENT
.sp
Alternately, manually add the repository and import the PPA key with these
commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo deb http://ppa.launchpad.net/saltstack/salt/ubuntu \(galsb_release \-sc\(ga main | sudo tee /etc/apt/sources.list.d/saltstack.list
wget \-q \-O\- "http://keyserver.ubuntu.com:11371/pks/lookup?op=get&search=0x4759FA960E27C0A6" | sudo apt\-key add \-
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After adding the repository, update the package management database:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get update
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Install packages
.sp
Install the Salt master, minion, or syndic from the repository with the apt\-get
command. These examples each install one daemon, but more than one package name
may be given at a time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get install salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get install salt\-syndic
.ft P
.fi
.UNINDENT
.UNINDENT
.SS ZeroMQ 4
.sp
We recommend using ZeroMQ 4 where available. ZeroMQ 4 is already available for
Ubuntu 14.04 and Ubuntu 14.10 and nothing additional needs to be done. However,
the \fBchris\-lea/zeromq\fP PPA can be used to provide ZeroMQ 4 on Ubuntu 12.04 LTS.
Adding this PPA can be done with a \fBpkgrepo.managed\fP
state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zeromq\-ppa:
pkgrepo.managed:
\- ppa: chris\-lea/zeromq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following states can be used to upgrade ZeroMQ and pyzmq, and then restart
the minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
update_zmq:
pkg.latest:
\- pkgs:
\- zeromq
\- python\-zmq
\- order: last
cmd.wait:
\- name: |
echo service salt\-minion restart | at now + 1 minute
\- watch:
\- pkg: update_zmq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This example assumes that atd is installed and running, see \fI\%here\fP for a more
detailed explanation.
.UNINDENT
.UNINDENT
.sp
If this repo is added \fIbefore\fP Salt is installed, then installing either
\fBsalt\-master\fP or \fBsalt\-minion\fP will automatically pull in ZeroMQ 4.0.4, and
additional states to upgrade ZeroMQ and pyzmq are unnecessary.
.SS Post\-installation tasks
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS Windows
.sp
Salt has full support for running the Salt Minion on Windows.
.sp
There are no plans for the foreseeable future to develop a Salt Master on
Windows. For now you must run your Salt Master on a supported operating system
to control your Salt Minions on Windows.
.sp
Many of the standard Salt modules have been ported to work on Windows and many
of the Salt States currently work on Windows, as well.
.SS Windows Installer
.sp
Salt Minion Windows installers can be found here. The output of \fImd5sum <salt
minion exe>\fP should match the contents of the corresponding md5 file.
.INDENT 0.0
.INDENT 3.5
.IP "Download here"
.INDENT 0.0
.IP \(bu 2
2014.7.2
.IP \(bu 2
\fI\%Salt\-Minion\-2014.7.2\-x86\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.7.2\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.7.1
.IP \(bu 2
\fI\%Salt\-Minion\-2014.7.1\-x86\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.7.1\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.7.0
.IP \(bu 2
Salt\-Minion\-2014.7.0\-1\-win32\-Setup.exe | md5
.IP \(bu 2
Salt\-Minion\-2014.7.0\-AMD64\-Setup.exe | md5
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The 2014.7.0 installers have been removed because of a regression. Please use the 2014.7.1 release instead.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
2014.1.13
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.13\-x86\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.13\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.11
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.11\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.11\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.10
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.10\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.10\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.7
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.7\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.7\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.5
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.5\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.5\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.4
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.4\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.4\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.3\-1 (packaging bugfix)
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.3\-1\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.3\-1\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.3
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.3\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.3\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.1
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.1\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.1\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
2014.1.0
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.0\-win32\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
\fI\%Salt\-Minion\-2014.1.0\-AMD64\-Setup.exe\fP | \fI\%md5\fP
.IP \(bu 2
0.17.5\-2 (bugfix release)
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-2\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-2\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.17.5
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.5\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.17.4
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.4\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.4\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.17.2
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.2\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.2\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.17.1.1 \- Windows Installer bugfix release
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1.1\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1.1\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.17.1
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.17.0
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.0\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.17.0\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.16.3
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.3\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.3\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.16.2
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.2\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.2\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.16.0
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.0\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.16.0\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.15.3
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.15.3\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.15.3\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.14.1
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.1\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.1\-AMD64\-Setup.exe\fP
.IP \(bu 2
0.14.0
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.0\-win32\-Setup.exe\fP
.IP \(bu 2
\fI\%https://docs.saltstack.com/downloads/Salt\-Minion\-0.14.0\-AMD64\-Setup.exe\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The executables above will install dependencies that the Salt minion
requires.
.UNINDENT
.UNINDENT
.sp
The 64bit installer has been tested on Windows 7 64bit and Windows Server
2008R2 64bit. The 32bit installer has been tested on Windows 2003 Server 32bit.
Please file a bug report on our GitHub repo if issues for other platforms are
found.
.sp
The installer asks for 2 bits of information; the master hostname and the
minion name. The installer will update the minion config with these options and
then start the minion.
.sp
The \fIsalt\-minion\fP service will appear in the Windows Service Manager and can be
started and stopped there or with the command line program \fIsc\fP like any other
Windows service.
.sp
If the minion won\(aqt start, try installing the Microsoft Visual C++ 2008 x64 SP1
redistributable. Allow all Windows updates to run salt\-minion smoothly.
.SS Silent Installer option
.sp
The installer can be run silently by providing the \fI/S\fP option at the command
line. The options \fI/master\fP and \fI/minion\-name\fP allow for configuring the master
hostname and minion name, respectively. Here\(aqs an example of using the silent
installer:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Salt\-Minion\-0.17.0\-Setup\-amd64.exe /S /master=yoursaltmaster /minion\-name=yourminionname
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting up a Windows build environment
.INDENT 0.0
.IP 1. 4
Install the Microsoft Visual C++ 2008 SP1 Redistributable, \fI\%vcredist_x86\fP
or \fI\%vcredist_x64\fP\&.
.IP 2. 4
Install \fI\%msysgit\fP
.IP 3. 4
Clone the Salt git repository from GitHub
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
git clone git://github.com/saltstack/salt.git
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 4
Install the latest point release of \fI\%Python 2.7\fP for the architecture you
wish to target
.IP 5. 4
Add C:\ePython27 and C:\ePython27\eScripts to your system path
.IP 6. 4
Download and run the Setuptools bootstrap \- \fI\%ez_setup.py\fP
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
python ez_setup.py
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 7. 4
Install Pip
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
easy_install pip
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 8. 4
Install the latest point release of \fI\%OpenSSL for Windows\fP
.INDENT 4.0
.IP 1. 3
During setup, choose first option to install in Windows system
directory
.UNINDENT
.IP 9. 4
Install the latest point release of \fI\%M2Crypto\fP
.INDENT 4.0
.IP 1. 3
In general, be sure to download installers targeted at py2.7 for your
chosen architecture
.UNINDENT
.IP 10. 4
Install the latest point release of \fI\%pycrypto\fP
.IP 11. 4
Install the latest point release of \fI\%pywin32\fP
.IP 12. 4
Install the latest point release of \fI\%Cython\fP
.IP 13. 4
Install the latest point release of \fI\%jinja2\fP
.IP 14. 4
Install the latest point release of \fI\%msgpack\fP
.IP 15. 4
Install psutil
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
easy_install psutil
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 16. 4
Install pyzmq
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
easy_install pyzmq
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 17. 4
Install PyYAML
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
easy_install pyyaml
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 18. 4
Install bbfreeze
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
easy_install bbfreeze
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 19. 4
Install wmi
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
pip install wmi
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 20. 4
Install esky
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
pip install esky
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 21. 4
Install Salt
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
cd salt
python setup.py install
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 22. 4
Build a frozen binary distribution of Salt
.INDENT 4.0
.INDENT 3.5
.sp
.nf
.ft C
python setup.py bdist_esky
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
A zip file has been created in the \fBdist/\fP folder, containing a frozen copy
of Python and the dependency libraries, along with Windows executables for each
of the Salt scripts.
.SS Building the installer
.sp
The Salt Windows installer is built with the open\-source NSIS compiler. The
source for the installer is found in the pkg directory of the Salt repo here:
\fI\%https://github.com/saltstack/salt/blob/develop/pkg/windows/installer/Salt\-Minion\-Setup.nsi\fP\&. To create the installer,
extract the frozen archive from \fBdist/\fP into \fBpkg/windows/buildenv/\fP and
run NSIS.
.sp
The NSIS installer can be found here: \fI\%http://nsis.sourceforge.net/Main_Page\fP
.SS Testing the Salt minion
.INDENT 0.0
.IP 1. 3
Create the directory C:\esalt (if it doesn\(aqt exist already)
.IP 2. 3
Copy the example \fBconf\fP and \fBvar\fP directories from
\fBpkg/windows/buildenv/\fP into C:\esalt
.IP 3. 3
Edit C:\esalt\econf\eminion
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
master: ipaddress or hostname of your salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
Start the salt\-minion
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
cd C:\ePython27\eScripts
python salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 5. 3
On the salt\-master accept the new minion\(aqs key
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
sudo salt\-key \-A
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This accepts all unaccepted keys. If you\(aqre concerned about security just
accept the key for this specific minion.
.IP 6. 3
Test that your minion is responding
.sp
On the salt\-master run:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
sudo salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
You should get the following response: \fB{\(aqyour minion hostname\(aq: True}\fP
.SS Single command bootstrap script
.sp
On a 64 bit Windows host the following script makes an unattended install of
salt, including all dependencies:
.INDENT 0.0
.INDENT 3.5
.IP "Not up to date."
.sp
This script is not up to date. Please use the installer found above
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# (All in one line.)
"PowerShell (New\-Object System.Net.WebClient).DownloadFile(\(aqhttp://csa\-net.dk/salt/bootstrap64.bat\(aq,\(aqC:\ebootstrap.bat\(aq);(New\-Object \-com Shell.Application).ShellExecute(\(aqC:\ebootstrap.bat\(aq);"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can execute the above command remotely from a Linux host using winexe:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
winexe \-U "administrator" //fqdn "PowerShell (New\-Object ......);"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For more info check \fI\%http://csa\-net.dk/salt\fP
.SS Packages management under Windows 2003
.sp
On windows Server 2003, you need to install optional component "wmi windows
installer provider" to have full list of installed packages. If you don\(aqt have
this, salt\-minion can\(aqt report some installed softwares.
.SS SUSE Installation
.sp
With openSUSE 13.1, Salt 0.16.4 has been available in the primary repositories.
The devel:language:python repo will have more up to date versions of salt,
all package development will be done there.
.SS Installation
.sp
Salt can be installed using \fBzypper\fP and is available in the standard openSUSE 13.1
repositories.
.SS Stable Release
.sp
Salt is packaged separately for the minion and the master. It is necessary only to
install the appropriate package for the role the machine will play. Typically, there
will be one master and multiple minions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper install salt\-master
zypper install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Post\-installation tasks openSUSE
.sp
\fBMaster\fP
.sp
To have the Master start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl enable salt\-master.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl start salt\-master.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBMinion\fP
.sp
To have the Minion start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl enable salt\-minion.service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl start salt\-minion.service
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Post\-installation tasks SLES
.sp
\fBMaster\fP
.sp
To have the Master start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chkconfig salt\-master on
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rcsalt\-master start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBMinion\fP
.sp
To have the Minion start automatically at boot time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chkconfig salt\-minion on
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To start the Minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rcsalt\-minion start
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Unstable Release
.SS openSUSE
.sp
For openSUSE Factory run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_Factory/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For openSUSE 13.1 run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_13.1/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For openSUSE 12.3 run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_12.3/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For openSUSE 12.2 run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_12.2/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For openSUSE 12.1 run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_12.1/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For bleeding edge python Factory run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/bleeding_edge_python_Factory/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Suse Linux Enterprise
.sp
For SLE 11 SP3 run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/SLE_11_SP3/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For SLE 11 SP2 run the following as root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/SLE_11_SP2/devel:languages:python.repo
zypper refresh
zypper install salt salt\-minion salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now go to the \fBConfiguring Salt\fP page.
.SS 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 >= 2.6 <3.0
.IP \(bu 2
\fI\%msgpack\-python\fP \- High\-performance message interchange format
.IP \(bu 2
\fI\%YAML\fP \- Python YAML bindings
.IP \(bu 2
\fI\%Jinja2\fP \- parsing Salt States (configurable in the master settings)
.IP \(bu 2
\fI\%MarkupSafe\fP \- Implements a XML/HTML/XHTML Markup safe string for Python
.IP \(bu 2
\fI\%apache\-libcloud\fP \- Python lib for interacting with many of the popular
cloud service providers using a unified API
.IP \(bu 2
\fI\%Requests\fP \- HTTP library
.UNINDENT
.sp
Depending on the chosen Salt transport, \fI\%ZeroMQ\fP or \fI\%RAET\fP, dependencies
vary:
.INDENT 0.0
.IP \(bu 2
ZeroMQ:
.INDENT 2.0
.IP \(bu 2
\fI\%ZeroMQ\fP >= 3.2.0
.IP \(bu 2
\fI\%pyzmq\fP >= 2.2.0 \- ZeroMQ Python bindings
.IP \(bu 2
\fI\%PyCrypto\fP \- The Python cryptography toolkit
.IP \(bu 2
\fI\%M2Crypto\fP \- "Me Too Crypto" \- Python OpenSSL wrapper
.UNINDENT
.IP \(bu 2
RAET:
.INDENT 2.0
.IP \(bu 2
\fI\%libnacl\fP \- Python bindings to \fI\%libsodium\fP
.IP \(bu 2
\fI\%ioflo\fP \- The flo programming interface raet and salt\-raet is built on
.IP \(bu 2
\fI\%RAET\fP \- The worlds most awesome UDP protocol
.UNINDENT
.UNINDENT
.sp
Salt defaults to the \fI\%ZeroMQ\fP transport, and the choice can be made at install
time, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python setup.py install \-\-salt\-transport=raet
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This way, only the required dependencies are pulled by the setup script if need
be.
.sp
If installing using pip, the \fB\-\-salt\-transport\fP install option can be
provided like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install \-\-install\-option="\-\-salt\-transport=raet" salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Optional Dependencies
.INDENT 0.0
.IP \(bu 2
\fI\%mako\fP \- an optional parser for Salt States (configurable in the master
settings)
.IP \(bu 2
gcc \- dynamic \fI\%Cython\fP module compiling
.UNINDENT
.SS Upgrading Salt
.sp
When upgrading Salt, the master(s) should always be upgraded first. Backward
compatibility for minions running newer versions of salt than their masters is
not guaranteed.
.sp
Whenever possible, backward compatibility between new masters and old minions
will be preserved. Generally, the only exception to this policy is in case of
a security vulnerability.
.SH TUTORIALS
.SS Introduction
.SS Salt Masterless Quickstart
.sp
Running a masterless salt\-minion lets you use Salt\(aqs configuration management
for a single machine without calling out to a Salt master on another machine.
.sp
Since the Salt minion contains such extensive functionality it can be useful
to run it standalone. A standalone minion can be used to do a number of
things:
.INDENT 0.0
.IP \(bu 2
Stand up a master server via States (Salting a Salt Master)
.IP \(bu 2
Use salt\-call commands on a system without connectivity to a master
.IP \(bu 2
Masterless States, run states entirely from files local to the minion
.UNINDENT
.sp
It is also useful for testing out state trees before deploying to a production setup.
.SS Bootstrap Salt Minion
.sp
The \fI\%salt\-bootstrap\fP script makes bootstrapping a server with Salt simple
for any OS with a Bourne shell:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O \- https://bootstrap.saltstack.com | sudo sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See the \fI\%salt\-bootstrap\fP documentation for other one liners. When using \fI\%Vagrant\fP
to test out salt, the \fI\%salty\-vagrant\fP tool will provision the VM for you.
.SS Telling Salt to Run Masterless
.sp
To instruct the minion to not look for a master when running
the \fBfile_client\fP configuration option needs to be set.
By default the \fBfile_client\fP is set to \fBremote\fP so that the
minion knows that file server and pillar data are to be gathered from the
master. When setting the \fBfile_client\fP option to \fBlocal\fP the
minion is configured to not gather this data from the master.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_client: local
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the salt minion will not look for a master and will assume that the local
system has all of the file and pillar resources.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When running Salt in masterless mode, do not run the salt\-minion daemon.
Otherwise, it will attempt to connect to a master and fail. The salt\-call
command stands on its own and does not need the salt\-minion daemon.
.UNINDENT
.UNINDENT
.SS Create State Tree
.sp
Following the successful installation of a salt\-minion, the next step is to create
a state tree, which is where the SLS files that comprise the possible states of the
minion are stored.
.sp
The following example walks through the steps necessary to create a state tree that
ensures that the server has the Apache webserver installed.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For a complete explanation on Salt States, see the \fI\%tutorial\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 1. 3
Create the \fBtop.sls\fP file:
.UNINDENT
.sp
\fB/srv/salt/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 2. 3
Create the webserver state tree:
.UNINDENT
.sp
\fB/srv/salt/webserver.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache: # ID declaration
pkg: # state declaration
\- installed # function declaration
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The only thing left is to provision our minion using salt\-call and the
highstate command.
.SS Salt\-call
.sp
The salt\-call command is used to run module functions locally on a minion
instead of executing them from the master. Normally the salt\-call command
checks into the master to retrieve file server and pillar data, but when
running standalone salt\-call needs to be instructed to not check the master for
this data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call \-\-local state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB\-\-local\fP flag tells the salt\-minion to look for the state tree in the
local file system and not to contact a Salt Master for instructions.
.sp
To provide verbose output, use \fB\-l debug\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call \-\-local state.highstate \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The minion first examines the \fBtop.sls\fP file and determines that it is a part
of the group matched by \fB*\fP glob and that the \fBwebserver\fP SLS should be applied.
.sp
It then examines the \fBwebserver.sls\fP file and finds the \fBapache\fP state, which
installs the Apache package.
.sp
The minion should now have Apache installed, and the next step is to begin
learning how to write
\fBmore complex states\fP\&.
.SS Basics
.SS Salt Bootstrap
.sp
The Salt Bootstrap script allows for a user to install the Salt Minion or
Master on a variety of system distributions and versions. This shell script
known as \fBbootstrap\-salt.sh\fP runs through a series of checks to determine
the operating system type and version. It then installs the Salt binaries
using the appropriate methods. The Salt Bootstrap script installs the
minimum number of packages required to run Salt. This means that in the event
you run the bootstrap to install via package, Git will not be installed.
Installing the minimum number of packages helps ensure the script stays as
lightweight as possible, assuming the user will install any other required
packages after the Salt binaries are present on the system. The script source
is available on GitHub: \fI\%https://github.com/saltstack/salt\-bootstrap\fP
.SS Supported Operating Systems
.INDENT 0.0
.IP \(bu 2
Amazon Linux 2012.09
.IP \(bu 2
Arch
.IP \(bu 2
CentOS 5/6
.IP \(bu 2
Debian 6.x/7.x/8(git installations only)
.IP \(bu 2
Fedora 17/18
.IP \(bu 2
FreeBSD 9.1/9.2/10
.IP \(bu 2
Gentoo
.IP \(bu 2
Linaro
.IP \(bu 2
Linux Mint 13/14
.IP \(bu 2
OpenSUSE 12.x
.IP \(bu 2
Oracle Linux 5/5
.IP \(bu 2
Red Hat 5/6
.IP \(bu 2
Red Hat Enterprise 5/6
.IP \(bu 2
Scientific Linux 5/6
.IP \(bu 2
SmartOS
.IP \(bu 2
SuSE 11 SP1/11 SP2
.IP \(bu 2
Ubuntu 10.x/11.x/12.x/13.04/13.10
.IP \(bu 2
Elementary OS 0.2
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In the event you do not see your distribution or version available please
review the develop branch on Github as it main contain updates that are
not present in the stable release:
\fI\%https://github.com/saltstack/salt\-bootstrap/tree/develop\fP
.UNINDENT
.UNINDENT
.SS Example Usage
.sp
If you\(aqre looking for the \fIone\-liner\fP to install salt, please scroll to the
bottom and use the instructions for \fI\%Installing via an Insecure One\-Liner\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In every two\-step example, you would be well\-served to examine the downloaded file and examine
it to ensure that it does what you expect.
.UNINDENT
.UNINDENT
.sp
Using \fBcurl\fP to install latest git:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com \-o install_salt.sh
sudo sh install_salt.sh git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using \fBwget\fP to install your distribution\(aqs stable packages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install a specific version from git using \fBwget\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh \-P git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you already have python installed, \fBpython 2.6\fP, then it\(aqs as easy as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-m urllib "https://bootstrap.saltstack.com" > install_salt.sh
sudo sh install_salt.sh git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All python versions should support the following one liner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-c \(aqimport urllib; print urllib.urlopen("https://bootstrap.saltstack.com").read()\(aq > install_salt.sh
sudo sh install_salt.sh git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On a FreeBSD base system you usually don\(aqt have either of the above binaries available. You \fBdo\fP
have \fBfetch\fP available though:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fetch \-o install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If all you want is to install a \fBsalt\-master\fP using latest git:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-o install_salt.sh.sh \-L https://bootstrap.saltstack.com
sudo sh install_salt.sh.sh \-M \-N git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you want to install a specific release version (based on the git tags):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-o install_salt.sh.sh \-L https://bootstrap.saltstack.com
sudo sh install_salt.sh.sh git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To install a specific branch from a git fork:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-o install_salt.sh.sh \-L https://bootstrap.saltstack.com
sudo sh install_salt.sh.sh \-g https://github.com/myuser/salt.git git mybranch
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Installing via an Insecure One\-Liner
.sp
The following examples illustrate how to install Salt via a one\-liner.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Warning! These methods do not involve a verification step and assume that
the delivered file is trustworthy.
.UNINDENT
.UNINDENT
.SS Examples
.sp
Installing the latest develop branch of Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Any of the example above which use two\-lines can be made to run in a single\-line
configuration with minor modifications.
.SS Example Usage
.sp
The Salt Bootstrap script has a wide variety of options that can be passed as
well as several ways of obtaining the bootstrap script itself.
.sp
For example, using \fBcurl\fP to install your distribution\(aqs stable packages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using \fBwget\fP to install your distribution\(aqs stable packages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O \- https://bootstrap.saltstack.com | sudo sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Installing the latest version available from git with \fBcurl\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install a specific version from git using \fBwget\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O \- https://bootstrap.saltstack.com | sh \-s \-\- \-P git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you already have python installed, \fBpython 2.6\fP, then it\(aqs as easy as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-m urllib "https://bootstrap.saltstack.com" | sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All python versions should support the following one liner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-c \(aqimport urllib; print urllib.urlopen("https://bootstrap.saltstack.com").read()\(aq | \e
sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On a FreeBSD base system you usually don\(aqt have either of the above binaries
available. You \fBdo\fP have \fBfetch\fP available though:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fetch \-o \- https://bootstrap.saltstack.com | sudo sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If all you want is to install a \fBsalt\-master\fP using latest git:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- \-M \-N git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you want to install a specific release version (based on the git tags):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Downloading the develop branch (from here standard command line options may be
passed):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget https://bootstrap.saltstack.com/develop
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Command Line Options
.sp
Here\(aqs a summary of the command line options:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sh bootstrap\-salt.sh \-h
Usage : bootstrap\-salt.sh [options] <install\-type> <install\-type\-args>
Installation types:
\- stable (default)
\- daily (ubuntu specific)
\- git
Examples:
$ bootstrap\-salt.sh
$ bootstrap\-salt.sh stable
$ bootstrap\-salt.sh daily
$ bootstrap\-salt.sh git
$ bootstrap\-salt.sh git develop
$ bootstrap\-salt.sh git v0.17.0
$ bootstrap\-salt.sh git 8c3fadf15ec183e5ce8c63739850d543617e4357
Options:
\-h Display this message
\-v Display script version
\-n No colours.
\-D Show debug output.
\-c Temporary configuration directory
\-g Salt repository URL. (default: git://github.com/saltstack/salt.git)
\-k Temporary directory holding the minion keys which will pre\-seed
the master.
\-M Also install salt\-master
\-S Also install salt\-syndic
\-N Do not install salt\-minion
\-X Do not start daemons after installation
\-C Only run the configuration function. This option automatically
bypasses any installation.
\-P Allow pip based installations. On some distributions the required salt
packages or its dependencies are not available as a package for that
distribution. Using this flag allows the script to use pip as a last
resort method. NOTE: This only works for functions which actually
implement pip based installations.
\-F Allow copied files to overwrite existing(config, init.d, etc)
\-U If set, fully upgrade the system prior to bootstrapping salt
\-K If set, keep the temporary files in the temporary directories specified
with \-c and \-k.
\-I If set, allow insecure connections while downloading any files. For
example, pass \(aq\-\-no\-check\-certificate\(aq to \(aqwget\(aq or \(aq\-\-insecure\(aq to \(aqcurl\(aq
\-A Pass the salt\-master DNS name or IP. This will be stored under
${BS_SALT_ETC_DIR}/minion.d/99\-master\-address.conf
\-i Pass the salt\-minion id. This will be stored under
${BS_SALT_ETC_DIR}/minion_id
\-L Install the Apache Libcloud package if possible(required for salt\-cloud)
\-p Extra\-package to install while installing salt dependencies. One package
per \-p flag. You\(aqre responsible for providing the proper package name.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Standalone Minion
.sp
Since the Salt minion contains such extensive functionality it can be useful
to run it standalone. A standalone minion can be used to do a number of
things:
.INDENT 0.0
.IP \(bu 2
Use salt\-call commands on a system without connectivity to a master
.IP \(bu 2
Masterless States, run states entirely from files local to the minion
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When running Salt in masterless mode, do not run the salt\-minion daemon.
Otherwise, it will attempt to connect to a master and fail. The salt\-call
command stands on its own and does not need the salt\-minion daemon.
.UNINDENT
.UNINDENT
.SS Telling Salt Call to Run Masterless
.sp
The salt\-call command is used to run module functions locally on a minion
instead of executing them from the master. Normally the salt\-call command
checks into the master to retrieve file server and pillar data, but when
running standalone salt\-call needs to be instructed to not check the master for
this data. To instruct the minion to not look for a master when running
salt\-call the \fBfile_client\fP configuration option needs to be set.
By default the \fBfile_client\fP is set to \fBremote\fP so that the
minion knows that file server and pillar data are to be gathered from the
master. When setting the \fBfile_client\fP option to \fBlocal\fP the
minion is configured to not gather this data from the master.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_client: local
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the salt\-call command will not look for a master and will assume that the
local system has all of the file and pillar resources.
.SS Running States Masterless
.sp
The state system can be easily run without a Salt master, with all needed files
local to the minion. To do this the minion configuration file needs to be set
up to know how to return file_roots information like the master. The file_roots
setting defaults to /srv/salt for the base environment just like on the master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now set up the Salt State Tree, top file, and SLS modules in the same way that
they would be set up on a master. Now, with the \fBfile_client\fP
option set to \fBlocal\fP and an available state tree then calls to functions in
the state module will use the information in the file_roots on the minion
instead of checking in with the master.
.sp
Remember that when creating a state tree on a minion there are no syntax or
path changes needed, SLS modules written to be used from a master do not need
to be modified in any way to work with a minion.
.sp
This makes it easy to "script" deployments with Salt states without having to
set up a master, and allows for these SLS modules to be easily moved into a
Salt master as the deployment grows.
.sp
The declared state can now be executed with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or the salt\-call command can be executed with the \fB\-\-local\fP flag, this makes
it unnecessary to change the configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call state.highstate \-\-local
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Opening the Firewall up for Salt
.sp
The Salt master communicates with the minions using an AES\-encrypted ZeroMQ
connection. These communications are done over TCP ports 4505 and 4506, which need
to be accessible on the master only. This document outlines suggested firewall
rules for allowing these incoming connections to the master.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
No firewall configuration needs to be done on Salt minions. These changes
refer to the master only.
.UNINDENT
.UNINDENT
.SS RHEL 6 / CentOS 6
.sp
The \fBlokkit\fP command packaged with some Linux distributions makes opening
iptables firewall ports very simple via the command line. Just be careful
to not lock out access to the server by neglecting to open the ssh
port.
.sp
\fBlokkit example\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
lokkit \-p 22:tcp \-p 4505:tcp \-p 4506:tcp
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBsystem\-config\-firewall\-tui\fP command provides a text\-based interface to modifying
the firewall.
.sp
\fBsystem\-config\-firewall\-tui\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
system\-config\-firewall\-tui
.ft P
.fi
.UNINDENT
.UNINDENT
.SS openSUSE
.sp
Salt installs firewall rules in \fI\%/etc/sysconfig/SuSEfirewall2.d/services/salt\fP\&.
Enable with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
SuSEfirewall2 open
SuSEfirewall2 start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have an older package of Salt where the above configuration file is not included, the \fBSuSEfirewall2\fP command makes opening iptables firewall ports
very simple via the command line.
.sp
\fBSuSEfirewall example\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
SuSEfirewall2 open EXT TCP 4505
SuSEfirewall2 open EXT TCP 4506
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The firewall module in YaST2 provides a text\-based interface to modifying the firewall.
.sp
\fBYaST2\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yast2 firewall
.ft P
.fi
.UNINDENT
.UNINDENT
.SS iptables
.sp
Different Linux distributions store their \fIiptables\fP (also known as
\fI\%netfilter\fP) rules in different places, which makes it difficult to
standardize firewall documentation. Included are some of the more
common locations, but your mileage may vary.
.sp
\fBFedora / RHEL / CentOS\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/sysconfig/iptables
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBArch Linux\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/iptables/iptables.rules
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBDebian\fP
.sp
Follow these instructions: \fI\%https://wiki.debian.org/iptables\fP
.sp
Once you\(aqve found your firewall rules, you\(aqll need to add the two lines below
to allow traffic on \fBtcp/4505\fP and \fBtcp/4506\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4505 \-j ACCEPT
\-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4506 \-j ACCEPT
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBUbuntu\fP
.sp
Salt installs firewall rules in \fI\%/etc/ufw/applications.d/salt.ufw\fP\&. Enable with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ufw allow salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS pf.conf
.sp
The BSD\-family of operating systems uses \fI\%packet filter (pf)\fP\&. The following
example describes the additions to \fBpf.conf\fP needed to access the Salt
master.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pass in on $int_if proto tcp from any to $int_if port 4505
pass in on $int_if proto tcp from any to $int_if port 4506
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once these additions have been made to the \fBpf.conf\fP the rules will need to
be reloaded. This can be done using the \fBpfctl\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pfctl \-vf /etc/pf.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Whitelist communication to Master
.sp
There are situations where you want to selectively allow Minion traffic
from specific hosts or networks into your Salt Master. The first
scenario which comes to mind is to prevent unwanted traffic to your
Master out of security concerns, but another scenario is to handle
Minion upgrades when there are backwards incompatible changes between
the installed Salt versions in your environment.
.sp
Here is an example \fI\%Linux iptables\fP ruleset to
be set on the Master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Allow Minions from these networks
\-I INPUT \-s 10.1.2.0/24 \-p tcp \-m multiport \-\-dports 4505,4506 \-j ACCEPT
\-I INPUT \-s 10.1.3.0/24 \-p tcp \-m multiport \-\-dports 4505,4506 \-j ACCEPT
# Allow Salt to communicate with Master on the loopback interface
\-A INPUT \-i lo \-p tcp \-m multiport \-\-dports 4505,4506 \-j ACCEPT
# Reject everything else
\-A INPUT \-p tcp \-m multiport \-\-dports 4505,4506 \-j REJECT
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The important thing to note here is that the \fBsalt\fP command
needs to communicate with the listening network socket of
\fBsalt\-master\fP on the \fIloopback\fP interface. Without this you will
see no outgoing Salt traffic from the master, even for a simple
\fBsalt \(aq*\(aq test.ping\fP, because the \fBsalt\fP client never reached
the \fBsalt\-master\fP to tell it to carry out the execution.
.UNINDENT
.UNINDENT
.SS Using cron with Salt
.sp
The Salt Minion can initiate its own highstate using the \fBsalt\-call\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-call state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will cause the minion to check in with the master and ensure it is in the
correct \(aqstate\(aq.
.SS Use cron to initiate a highstate
.sp
If you would like the Salt Minion to regularly check in with the master you can
use the venerable cron to run the \fBsalt\-call\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# PATH=/bin:/sbin:/usr/bin:/usr/sbin
00 00 * * * salt\-call state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above cron entry will run a highstate every day at midnight.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Be aware that you may need to ensure the PATH for cron includes any
scripts or commands that need to be executed.
.UNINDENT
.UNINDENT
.SS 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.
.INDENT 0.0
.INDENT 3.5
.IP "Stuck?"
.sp
There are many ways to \fIget help from the Salt community\fP including our
\fI\%mailing list\fP
and our \fI\%IRC channel\fP #salt.
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq<target>\(aq <function> [arguments]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBsalt manpage\fP
.UNINDENT
.UNINDENT
.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. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
salt \(aq*.example.org\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Targets can be based on minion system information using the Grains system:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos:Ubuntu\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBGrains system\fP
.UNINDENT
.UNINDENT
.sp
Targets can be filtered by regular expression:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-E \(aqvirtmach[0\-9]\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Targets can be explicitly specified in a list:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-L \(aqfoo,bar,baz,quo\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or Multiple target types can be combined in one command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-C \(aqG@os:Ubuntu and webser* or E@database.*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here are some examples:
.sp
Show all currently available minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Run an arbitrary shell command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run \(aquname \-a\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBthe full list of modules\fP
.UNINDENT
.UNINDENT
.SS arguments
.sp
Space\-delimited arguments to the function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Optional, keyword arguments are also supported:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.install salt timeout=5 upgrade=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
They are always in the form of \fBkwarg=argument\fP\&.
.SS Pillar Walkthrough
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This walkthrough assumes that the reader has already completed the initial
Salt \fBwalkthrough\fP\&.
.UNINDENT
.UNINDENT
.sp
Pillars are tree\-like structures of data defined on the Salt Master and passed
through to minions. They allow confidential, targeted data to be securely sent
only to the relevant minion.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Grains and Pillar are sometimes confused, just remember that Grains
are data about a minion which is stored or generated from the minion.
This is why information like the OS and CPU type are found in Grains.
Pillar is information about a minion or many minions stored or generated
on the Salt Master.
.UNINDENT
.UNINDENT
.sp
Pillar data is useful for:
.INDENT 0.0
.TP
.B Highly Sensitive Data:
Information transferred via pillar is guaranteed to only be presented to
the minions that are targeted, making Pillar suitable
for managing security information, such as cryptographic keys and
passwords.
.TP
.B Minion Configuration:
Minion modules such as the execution modules, states, and returners can
often be configured via data stored in pillar.
.TP
.B Variables:
Variables which need to be assigned to specific minions or groups of
minions can be defined in pillar and then accessed inside sls formulas
and template files.
.TP
.B Arbitrary Data:
Pillar can contain any basic data structure, so a list of values, or a
key/value store can be defined making it easy to iterate over a group
of values in sls formulas
.UNINDENT
.sp
Pillar is therefore one of the most important systems when using Salt. This
walkthrough is designed to get a simple Pillar up and running in a few minutes
and then to dive into the capabilities of Pillar and where the data is
available.
.SS Setting Up Pillar
.sp
The pillar is already running in Salt by default. To see the minion\(aqs
pillar data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.items
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Prior to version 0.16.2, this function is named \fBpillar.data\fP\&. This
function name is still supported for backwards compatibility.
.UNINDENT
.UNINDENT
.sp
By default the contents of the master configuration file are loaded into
pillar for all minions. This enables the master configuration file to
be used for global configuration of minions.
.sp
Similar to the state tree, the pillar is comprised of sls files and has a top file.
The default location for the pillar is in /srv/pillar.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The pillar location can be configured via the \fIpillar_roots\fP option inside
the master configuration file. It must not be in a subdirectory of the state
tree.
.UNINDENT
.UNINDENT
.sp
To start setting up the pillar, the /srv/pillar directory needs to be present:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mkdir /srv/pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now create a simple top file, following the same format as the top file used for
states:
.sp
\fB/srv/pillar/top.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- data
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This top file associates the data.sls file to all minions. Now the
\fB/srv/pillar/data.sls\fP file needs to be populated:
.sp
\fB/srv/pillar/data.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
info: some data
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To ensure that the minions have the new pillar data, issue a command
to them asking that they fetch their pillars from the master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.pillar_refresh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now that the minions have the new pillar, it can be retreived:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.items
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The key \fBinfo\fP should now appear in the returned pillar data.
.SS More Complex Data
.sp
Unlike states, pillar files do not need to define \fBformulas\fP\&.
This example sets up user data with a UID:
.sp
\fB/srv/pillar/users/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
users:
thatch: 1000
shouse: 1001
utahdave: 1002
redbeard: 1003
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The same directory lookups that exist in states exist in pillar, so the
file \fBusers/init.sls\fP can be referenced with \fBusers\fP in the \fItop
file\fP\&.
.UNINDENT
.UNINDENT
.sp
The top file will need to be updated to include this sls file:
.sp
\fB/srv/pillar/top.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- data
\- users
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the data will be available to the minions. To use the pillar data in a
state, you can use Jinja:
.sp
\fB/srv/salt/users/init.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% for user, uid in pillar.get(\(aqusers\(aq, {}).items() %}
{{user}}:
user.present:
\- uid: {{uid}}
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This approach allows for users to be safely defined in a pillar and then the
user data is applied in an sls file.
.SS Parameterizing States With Pillar
.sp
Pillar data can be accessed in state files to customise behavior for each
minion. All pillar (and grain) data applicable to each minion is substituted
into the state files through templating before being run. Typical uses
include setting directories appropriate for the minion and skipping states
that don\(aqt apply.
.sp
A simple example is to set up a mapping of package names in pillar for
separate Linux distributions:
.sp
\fB/srv/pillar/pkg/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pkgs:
{% if grains[\(aqos_family\(aq] == \(aqRedHat\(aq %}
apache: httpd
vim: vim\-enhanced
{% elif grains[\(aqos_family\(aq] == \(aqDebian\(aq %}
apache: apache2
vim: vim
{% elif grains[\(aqos\(aq] == \(aqArch\(aq %}
apache: apache
vim: vim
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The new \fBpkg\fP sls needs to be added to the top file:
.sp
\fB/srv/pillar/top.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- data
\- users
\- pkg
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the minions will auto map values based on respective operating systems
inside of the pillar, so sls files can be safely parameterized:
.sp
\fB/srv/salt/apache/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
\- name: {{ pillar[\(aqpkgs\(aq][\(aqapache\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or, if no pillar is available a default can be set as well:
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The function \fBpillar.get\fP used in this example was added to Salt in
version 0.14.0
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/apache/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
\- name: {{ salt[\(aqpillar.get\(aq](\(aqpkgs:apache\(aq, \(aqhttpd\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the above example, if the pillar value \fBpillar[\(aqpkgs\(aq][\(aqapache\(aq]\fP is not
set in the minion\(aqs pillar, then the default of \fBhttpd\fP will be used.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Under the hood, pillar is just a Python dict, so Python dict methods such
as \fIget\fP and \fIitems\fP can be used.
.UNINDENT
.UNINDENT
.SS Pillar Makes Simple States Grow Easily
.sp
One of the design goals of pillar is to make simple sls formulas easily grow
into more flexible formulas without refactoring or complicating the states.
.sp
A simple formula:
.sp
\fB/srv/salt/edit/vim.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed: []
/etc/vimrc:
file.managed:
\- source: salt://edit/vimrc
\- mode: 644
\- user: root
\- group: root
\- require:
\- pkg: vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Can be easily transformed into a powerful, parameterized formula:
.sp
\fB/srv/salt/edit/vim.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed:
\- name: {{ pillar[\(aqpkgs\(aq][\(aqvim\(aq] }}
/etc/vimrc:
file.managed:
\- source: {{ pillar[\(aqvimrc\(aq] }}
\- mode: 644
\- user: root
\- group: root
\- require:
\- pkg: vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where the vimrc source location can now be changed via pillar:
.sp
\fB/srv/pillar/edit/vim.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if grains[\(aqid\(aq].startswith(\(aqdev\(aq) %}
vimrc: salt://edit/dev_vimrc
{% elif grains[\(aqid\(aq].startswith(\(aqqa\(aq) %}
vimrc: salt://edit/qa_vimrc
{% else %}
vimrc: salt://edit/vimrc
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Ensuring that the right vimrc is sent out to the correct minions.
.SS Setting Pillar Data on the Command Line
.sp
Pillar data can be set on the command line like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate pillar=\(aq{"foo": "bar"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBstate.sls\fP command can also be used to set pillar values via the command
line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.sls my_sls_file pillar=\(aq{"hello": "world"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lists can be passed in pillar as well:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate pillar=\(aq["foo", "bar", "baz"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If a key is passed on the command line that already exists on the minion,
the key that is passed in will overwrite the entire value of that key,
rather than merging only the specified value set via the command line.
.UNINDENT
.UNINDENT
.SS More On Pillar
.sp
Pillar data is generated on the Salt master and securely distributed to
minions. Salt is not restricted to the pillar sls files when defining the
pillar but can retrieve data from external sources. This can be useful when
information about an infrastructure is stored in a separate location.
.sp
Reference information on pillar and the external pillar interface can be found
in the Salt documentation:
.sp
\fBPillar\fP
.SS States
.SS How Do I Use Salt States?
.sp
Simplicity, Simplicity, Simplicity
.sp
Many of the most powerful and useful engineering solutions are founded on
simple principles. Salt States strive to do just that: K.I.S.S. (Keep It
Stupidly Simple)
.sp
The core of the Salt State system is the SLS, or \fBS\fPa\fBL\fPt
\fBS\fPtate file. The SLS is a representation of the state in which
a system should be in, and is set up to contain this data in a simple format.
This is often called configuration management.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This is just the beginning of using states, make sure to read up on pillar
\fBPillar\fP next.
.UNINDENT
.UNINDENT
.SS It is All Just Data
.sp
Before delving into the particulars, it will help to understand that the SLS
file is just a data structure under the hood. While understanding that the SLS
is just a data structure isn\(aqt critical for understanding and making use of
Salt States, it should help bolster knowledge of where the real power is.
.sp
SLS files are therefore, in reality, just \fI\%dictionaries\fP, \fI\%lists\fP, \fI\%strings\fP, and \fI\%numbers\fP\&.
By using this approach Salt can be much more flexible. As one writes more state
files, it becomes clearer exactly what is being written. The result is a system
that is easy to understand, yet grows with the needs of the admin or developer.
.SS The Top File
.sp
The example SLS files in the below sections can be assigned to hosts using a
file called \fBtop.sls\fP\&. This file is described in\-depth \fBhere\fP\&.
.SS Default Data \- YAML
.sp
By default Salt represents the SLS data in what is one of the simplest
serialization formats available \- \fI\%YAML\fP\&.
.sp
A typical SLS file will often look like this in YAML:
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
These demos use some generic service and package names, different
distributions often use different names for packages and services. For
instance \fIapache\fP should be replaced with \fIhttpd\fP on a Red Hat system.
Salt uses the name of the init script, systemd name, upstart name etc.
based on what the underlying service management for the platform. To
get a list of the available service names on a platform execute the
service.get_all salt function.
.sp
Information on how to make states work with multiple distributions
is later in the tutorial.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed: []
service.running:
\- require:
\- pkg: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This SLS data will ensure that the package named apache is installed, and
that the apache service is running. The components can be explained in a
simple way.
.sp
The first line is the ID for a set of data, and it is called the ID
Declaration. This ID sets the name of the thing that needs to be manipulated.
.sp
The second and third lines contain the state module function to be run, in the
format \fB<state_module>.<function>\fP\&. The \fBpkg.installed\fP state module
function ensures that a software package is installed via the system\(aqs native
package manager. The \fBservice.running\fP state module function ensures that a
given system daemon is running.
.sp
Finally, on line five, is the word \fBrequire\fP\&. This is called a Requisite
Statement, and it makes sure that the Apache service is only started after
a successful installation of the apache package.
.SS Adding Configs and Users
.sp
When setting up a service like an Apache web server, many more components may
need to be added. The Apache configuration file will most likely be managed,
and a user and group may need to be set up.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed: []
service.running:
\- watch:
\- pkg: apache
\- file: /etc/httpd/conf/httpd.conf
\- user: apache
user.present:
\- uid: 87
\- gid: 87
\- home: /var/www/html
\- shell: /bin/nologin
\- require:
\- group: apache
group.present:
\- gid: 87
\- require:
\- pkg: apache
/etc/httpd/conf/httpd.conf:
file.managed:
\- source: salt://apache/httpd.conf
\- user: root
\- group: root
\- mode: 644
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This SLS data greatly extends the first example, and includes a config file,
a user, a group and new requisite statement: \fBwatch\fP\&.
.sp
Adding more states is easy, since the new user and group states are under
the Apache ID, the user and group will be the Apache user and group. The
\fBrequire\fP statements will make sure that the user will only be made after
the group, and that the group will be made only after the Apache package is
installed.
.sp
Next, the \fBrequire\fP statement under service was changed to watch, and is
now watching 3 states instead of just one. The watch statement does the same
thing as require, making sure that the other states run before running the
state with a watch, but it adds an extra component. The \fBwatch\fP statement
will run the state\(aqs watcher function for any changes to the watched states.
So if the package was updated, the config file changed, or the user
uid modified, then the service state\(aqs watcher will be run. The service
state\(aqs watcher just restarts the service, so in this case, a change in the
config file will also trigger a restart of the respective service.
.SS Moving Beyond a Single SLS
.sp
When setting up Salt States in a scalable manner, more than one SLS will need
to be used. The above examples were in a single SLS file, but two or more
SLS files can be combined to build out a State Tree. The above example also
references a file with a strange source \- \fBsalt://apache/httpd.conf\fP\&. That
file will need to be available as well.
.sp
The SLS files are laid out in a directory structure on the Salt master; an
SLS is just a file and files to download are just files.
.sp
The Apache example would be laid out in the root of the Salt file server like
this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache/init.sls
apache/httpd.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
So the httpd.conf is just a file in the apache directory, and is referenced
directly.
.sp
But when using more than one single SLS file, more components can be added to
the toolkit. Consider this SSH example:
.sp
\fBssh/init.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openssh\-client:
pkg.installed
/etc/ssh/ssh_config:
file.managed:
\- user: root
\- group: root
\- mode: 644
\- source: salt://ssh/ssh_config
\- require:
\- pkg: openssh\-client
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBssh/server.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- ssh
openssh\-server:
pkg.installed
sshd:
service.running:
\- require:
\- pkg: openssh\-client
\- pkg: openssh\-server
\- file: /etc/ssh/banner
\- file: /etc/ssh/sshd_config
/etc/ssh/sshd_config:
file.managed:
\- user: root
\- group: root
\- mode: 644
\- source: salt://ssh/sshd_config
\- require:
\- pkg: openssh\-server
/etc/ssh/banner:
file:
\- managed
\- user: root
\- group: root
\- mode: 644
\- source: salt://ssh/banner
\- require:
\- pkg: openssh\-server
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Notice that we use two similar ways of denoting that a file
is managed by Salt. In the \fI/etc/ssh/sshd_config\fP state section above,
we use the \fIfile.managed\fP state declaration whereas with the
\fI/etc/ssh/banner\fP state section, we use the \fIfile\fP state declaration
and add a \fImanaged\fP attribute to that state declaration. Both ways
produce an identical result; the first way \-\- using \fIfile.managed\fP \-\-
is merely a shortcut.
.UNINDENT
.UNINDENT
.sp
Now our State Tree looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache/init.sls
apache/httpd.conf
ssh/init.sls
ssh/server.sls
ssh/banner
ssh/ssh_config
ssh/sshd_config
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example now introduces the \fBinclude\fP statement. The include statement
includes another SLS file so that components found in it can be required,
watched or as will soon be demonstrated \- extended.
.sp
The include statement allows for states to be cross linked. When an SLS
has an include statement it is literally extended to include the contents of
the included SLS files.
.sp
Note that some of the SLS files are called init.sls, while others are not. More
info on what this means can be found in the \fIStates Tutorial\fP\&.
.SS Extending Included SLS Data
.sp
Sometimes SLS data needs to be extended. Perhaps the apache service needs to
watch additional resources, or under certain circumstances a different file
needs to be placed.
.sp
In these examples, the first will add a custom banner to ssh and the second will
add more watchers to apache to include mod_python.
.sp
\fBssh/custom\-server.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- ssh.server
extend:
/etc/ssh/banner:
file:
\- source: salt://ssh/custom\-banner
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBpython/mod_python.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- apache
extend:
apache:
service:
\- watch:
\- pkg: mod_python
mod_python:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBcustom\-server.sls\fP file uses the extend statement to overwrite where the
banner is being downloaded from, and therefore changing what file is being used
to configure the banner.
.sp
In the new mod_python SLS the mod_python package is added, but more importantly
the apache service was extended to also watch the mod_python package.
.INDENT 0.0
.INDENT 3.5
.IP "Using extend with require or watch"
.sp
The \fBextend\fP statement works differently for \fBrequire\fP or \fBwatch\fP\&.
It appends to, rather than replacing the requisite component.
.UNINDENT
.UNINDENT
.SS Understanding the Render System
.sp
Since SLS data is simply that (data), it does not need to be represented
with YAML. Salt defaults to YAML because it is very straightforward and easy
to learn and use. But the SLS files can be rendered from almost any imaginable
medium, so long as a renderer module is provided.
.sp
The default rendering system is the \fByaml_jinja\fP renderer. The
\fByaml_jinja\fP renderer will first pass the template through the \fI\%Jinja2\fP
templating system, and then through the YAML parser. The benefit here is that
full programming constructs are available when creating SLS files.
.sp
Other renderers available are \fByaml_mako\fP and \fByaml_wempy\fP which each use
the \fI\%Mako\fP or \fI\%Wempy\fP templating system respectively rather than the jinja
templating system, and more notably, the pure Python or \fBpy\fP, \fBpydsl\fP &
\fBpyobjects\fP renderers.
The \fBpy\fP renderer allows for SLS files to be written in pure Python,
allowing for the utmost level of flexibility and power when preparing SLS
data; while the \fBpydsl\fP renderer
provides a flexible, domain\-specific language for authoring SLS data in Python;
and the \fBpyobjects\fP renderer
gives you a \fI\%"Pythonic"\fP interface to building state data.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The templating engines described above aren\(aqt just available in SLS files.
They can also be used in \fBfile.managed\fP
states, making file management much more dynamic and flexible. Some
examples for using templates in managed files can be found in the
documentation for the \fBfile states\fP, as well as the \fI\%MooseFS
example\fP below.
.UNINDENT
.UNINDENT
.SS Getting to Know the Default \- yaml_jinja
.sp
The default renderer \- \fByaml_jinja\fP, allows for use of the jinja
templating system. A guide to the Jinja templating system can be found here:
\fI\%http://jinja.pocoo.org/docs\fP
.sp
When working with renderers a few very useful bits of data are passed in. In
the case of templating engine based renderers, three critical components are
available, \fBsalt\fP, \fBgrains\fP, and \fBpillar\fP\&. The \fBsalt\fP object allows for
any Salt function to be called from within the template, and \fBgrains\fP allows
for the Grains to be accessed from within the template. A few examples:
.sp
\fBapache/init.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
{% if grains[\(aqos\(aq] == \(aqRedHat\(aq%}
\- name: httpd
{% endif %}
service.running:
{% if grains[\(aqos\(aq] == \(aqRedHat\(aq%}
\- name: httpd
{% endif %}
\- watch:
\- pkg: apache
\- file: /etc/httpd/conf/httpd.conf
\- user: apache
user.present:
\- uid: 87
\- gid: 87
\- home: /var/www/html
\- shell: /bin/nologin
\- require:
\- group: apache
group.present:
\- gid: 87
\- require:
\- pkg: apache
/etc/httpd/conf/httpd.conf:
file.managed:
\- source: salt://apache/httpd.conf
\- user: root
\- group: root
\- mode: 644
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example is simple. If the \fBos\fP grain states that the operating system is
Red Hat, then the name of the Apache package and service needs to be httpd.
.sp
A more aggressive way to use Jinja can be found here, in a module to set up
a MooseFS distributed filesystem chunkserver:
.sp
\fBmoosefs/chunk.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- moosefs
{% for mnt in salt[\(aqcmd.run\(aq](\(aqls /dev/data/moose*\(aq).split() %}
/mnt/moose{{ mnt[\-1] }}:
mount.mounted:
\- device: {{ mnt }}
\- fstype: xfs
\- mkmnt: True
file.directory:
\- user: mfs
\- group: mfs
\- require:
\- user: mfs
\- group: mfs
{% endfor %}
/etc/mfshdd.cfg:
file.managed:
\- source: salt://moosefs/mfshdd.cfg
\- user: root
\- group: root
\- mode: 644
\- template: jinja
\- require:
\- pkg: mfs\-chunkserver
/etc/mfschunkserver.cfg:
file.managed:
\- source: salt://moosefs/mfschunkserver.cfg
\- user: root
\- group: root
\- mode: 644
\- template: jinja
\- require:
\- pkg: mfs\-chunkserver
mfs\-chunkserver:
pkg.installed: []
mfschunkserver:
service.running:
\- require:
{% for mnt in salt[\(aqcmd.run\(aq](\(aqls /dev/data/moose*\(aq) %}
\- mount: /mnt/moose{{ mnt[\-1] }}
\- file: /mnt/moose{{ mnt[\-1] }}
{% endfor %}
\- file: /etc/mfschunkserver.cfg
\- file: /etc/mfshdd.cfg
\- file: /var/lib/mfs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example shows much more of the available power of Jinja.
Multiple for loops are used to dynamically detect available hard drives
and set them up to be mounted, and the \fBsalt\fP object is used multiple
times to call shell commands to gather data.
.SS Introducing the Python, PyDSL and the Pyobjects Renderers
.sp
Sometimes the chosen default renderer might not have enough logical power to
accomplish the needed task. When this happens, the Python renderer can be
used. Normally a YAML renderer should be used for the majority of SLS files,
but an SLS file set to use another renderer can be easily added to the tree.
.sp
This example shows a very basic Python SLS file:
.sp
\fBpython/django.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!py
def run():
\(aq\(aq\(aq
Install the django package
\(aq\(aq\(aq
return {\(aqinclude\(aq: [\(aqpython\(aq],
\(aqdjango\(aq: {\(aqpkg\(aq: [\(aqinstalled\(aq]}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is a very simple example; the first line has an SLS shebang that
tells Salt to not use the default renderer, but to use the \fBpy\fP renderer.
Then the run function is defined, the return value from the run function
must be a Salt friendly data structure, or better known as a Salt
\fBHighState data structure\fP\&.
.sp
Alternatively, using the \fBpydsl\fP
renderer, the above example can be written more succinctly as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pydsl
include(\(aqpython\(aq, delayed=True)
state(\(aqdjango\(aq).pkg.installed()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBpyobjects\fP renderer
provides an \fI\%"Pythonic"\fP object based approach for building the state data.
The above example could be written as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
include(\(aqpython\(aq)
Pkg.installed("django")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This Python examples would look like this if they were written in YAML:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- python
django:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example clearly illustrates that; one, using the YAML renderer by default
is a wise decision and two, unbridled power can be obtained where needed by
using a pure Python SLS.
.SS Running and debugging salt states.
.sp
Once the rules in an SLS are ready, they should be tested to ensure they
work properly. To invoke these rules, simply execute
\fBsalt \(aq*\(aq state.highstate\fP on the command line. If you get back only
hostnames with a \fB:\fP after, but no return, chances are there is a problem with
one or more of the sls files. On the minion, use the \fBsalt\-call\fP command:
\fBsalt\-call state.highstate \-l debug\fP to examine the output for errors.
This should help troubleshoot the issue. The minions can also be started in
the foreground in debug mode: \fBsalt\-minion \-l debug\fP\&.
.SS Next Reading
.sp
With an understanding of states, the next recommendation is to become familiar
with Salt\(aqs pillar interface:
.INDENT 0.0
.INDENT 3.5
\fBPillar Walkthrough\fP
.UNINDENT
.UNINDENT
.SS States tutorial, part 1 \- Basic Usage
.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.
.INDENT 0.0
.INDENT 3.5
.IP "Stuck?"
.sp
There are many ways to \fIget help from the Salt community\fP including our
\fI\%mailing list\fP
and our \fI\%IRC channel\fP #salt.
.UNINDENT
.UNINDENT
.SS Setting up the Salt State Tree
.sp
States are stored in text files on the master and transferred to the minions on
demand via the master\(aqs File Server. The collection of state files make up the
\fBState Tree\fP\&.
.sp
To start using a central state system in Salt, the Salt File Server must first
be set up. Edit the master config file (\fBfile_roots\fP) and
uncomment the following lines:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you are deploying on FreeBSD via ports, the \fBfile_roots\fP path defaults
to \fB/usr/local/etc/salt/states\fP\&.
.UNINDENT
.UNINDENT
.sp
Restart the Salt master in order to pick up this change:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pkill salt\-master
salt\-master \-d
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Preparing the Top File
.sp
On the master, in the directory uncommented in the previous step,
(\fB/srv/salt\fP by default), create a new file called
\fBtop.sls\fP and add the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.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).
.INDENT 0.0
.INDENT 3.5
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqos:Fedora\(aq:
\- match: grain
\- webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Create an \fBsls\fP file
.sp
In the same directory as the \fItop file\fP, create a file
named \fBwebserver.sls\fP, containing the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache: # ID declaration
pkg: # state declaration
\- installed # function declaration
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The package name for the Apache httpd web server may differ depending on
OS or distro — for example, on Fedora it is \fBhttpd\fP but on
Debian/Ubuntu it is \fBapache2\fP\&.
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.IP "Renderers"
.sp
States \fBsls\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. The default can be changed by editing
\fBrenderer\fP in the master configuration file.
.UNINDENT
.UNINDENT
.SS Install the package
.sp
Next, let\(aqs run the state we created. Open a terminal on the master and run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
% salt \(aq*\(aq state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
If you have created \fIcustom grain modules\fP, they will
not be available in the top file until after the first \fI\%highstate\fP\&. To make custom grains available on a minion\(aqs first
highstate, it is recommended to use \fIthis example\fP to ensure that the custom grains are synced when
the minion starts.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "SLS File Namespace"
.sp
Note that in the \fI\%example\fP above, the SLS file
\fBwebserver.sls\fP was referred to simply as \fBwebserver\fP\&. The namespace
for SLS files follows a few simple rules:
.INDENT 0.0
.IP 1. 3
The \fB\&.sls\fP is discarded (i.e. \fBwebserver.sls\fP becomes
\fBwebserver\fP).
.IP 2. 3
.INDENT 3.0
.TP
.B Subdirectories can be used for better organization.
.INDENT 7.0
.IP a. 3
Each subdirectory is represented by a dot.
.IP b. 3
\fBwebserver/dev.sls\fP is referred to as \fBwebserver.dev\fP\&.
.UNINDENT
.UNINDENT
.IP 3. 3
A file called \fBinit.sls\fP in a subdirectory is referred to by the path
of the directory. So, \fBwebserver/init.sls\fP is referred to as
\fBwebserver\fP\&.
.IP 4. 3
If both \fBwebserver.sls\fP and \fBwebserver/init.sls\fP happen to exist,
\fBwebserver/init.sls\fP will be ignored and \fBwebserver.sls\fP will be the
file referred to as \fBwebserver\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "Troubleshooting Salt"
.sp
If the expected output isn\(aqt seen, the following tips can help to
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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B Run the minion in the foreground
By not starting the minion in daemon mode (\fB\-d\fP) one can view any output from the minion as it works:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion &
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Increase the default timeout value when running \fBsalt\fP\&. For
example, to change the default timeout to 60 seconds:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-t 60
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For best results, combine all three:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion \-l debug & # On the minion
salt \(aq*\(aq state.highstate \-t 60 # On the master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.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
\fBsls\fP syntax and will explore more of the states that ship with Salt.
.SS States tutorial, part 2 \- More Complex States, Requisites
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This tutorial builds on topics covered in \fBpart 1\fP\&. It is
recommended that you begin there.
.UNINDENT
.UNINDENT
.sp
In the \fBlast part\fP of the Salt States tutorial we covered the
basics of installing a package. We will now modify our \fBwebserver.sls\fP file
to have requirements, and use even more Salt States.
.SS Call multiple States
.sp
You can specify multiple \fIstate\-declaration\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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed: []
service.running:
\- require:
\- pkg: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Try stopping Apache before running \fBstate.highstate\fP once again and observe
the output.
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed: []
service.running:
\- require:
\- pkg: apache
/var/www/index.html: # ID declaration
file: # state declaration
\- managed # function
\- source: salt://webserver/index.html # function arg
\- require: # requisite declaration
\- pkg: apache # requisite reference
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBline 9\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 10\fP the \fIstate\-declaration\fP\&. This example uses the Salt \fBfile
state\fP\&.
.sp
\fBLine 11\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 12\fP is a \fIfunction\-arg\-declaration\fP which, in this example, passes
the \fBsource\fP argument to the \fBmanaged function\fP\&.
.sp
\fBLine 13\fP is a \fIrequisite\-declaration\fP\&.
.sp
\fBLine 14\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:
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Verify that Apache is now serving your custom HTML.
.INDENT 0.0
.INDENT 3.5
.IP "\fBrequire\fP vs. \fBwatch\fP"
.sp
There are two \fIrequisite\-declaration\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:
.INDENT 0.0
.INDENT 3.5
.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
\- require:
\- pkg: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.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\&.
.UNINDENT
.UNINDENT
.SS Next steps
.sp
In \fBpart 3\fP we will discuss how to use includes, extends and
templating to make a more complete State Tree configuration.
.SS States tutorial, part 3 \- Templating, Includes, Extends
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This tutorial builds on topics covered in \fBpart 1\fP and
\fBpart 2\fP\&. It is recommended that you begin there.
.UNINDENT
.UNINDENT
.sp
This part of the 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 execution. 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.
To make use of the templating system, simply add some templating markup.
An example of an sls module with templating markup may look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% for usr in [\(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq] %}
{{ usr }}:
user.present
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This templated sls file once generated will look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
moe:
user.present
larry:
user.present
curly:
user.present
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here\(aqs a more complex example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %}
{{ usr }}:
group:
\- present
user:
\- present
\- gid_from_name: True
\- require:
\- group: {{ usr }}
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Using Grains in SLS modules
.sp
Often times a state will need to behave differently on different systems.
\fBSalt grains\fP objects are made available
in the template context. The \fIgrains\fP can be used from within sls modules:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
{% if grains[\(aqos\(aq] == \(aqRedHat\(aq %}
\- name: httpd
{% elif grains[\(aqos\(aq] == \(aqUbuntu\(aq %}
\- name: apache2
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Calling Salt modules from templates
.sp
All of the Salt modules loaded by the minion are available within the
templating system. This allows data to be gathered in real time on the target
system. It also allows for shell commands to be run easily from within the sls
modules.
.sp
The Salt module functions are also made available in the template context as
\fBsalt:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
moe:
user.present:
\- gid: {{ salt[\(aqfile.group_to_gid\(aq](\(aqsome_group_that_exists\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that for the above example to work, \fBsome_group_that_exists\fP must exist
before the state file is processed by the templating engine.
.sp
Below is an example that uses the \fBnetwork.hw_addr\fP function to retrieve the
MAC address for eth0:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt[\(aqnetwork.hw_addr\(aq](\(aqeth0\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Advanced SLS module syntax
.sp
Lastly, we will cover some incredibly useful techniques for more complex State
trees.
.SS Include declaration
.sp
A previous example showed how to spread a Salt tree across several files.
Similarly, \fBrequisites\fP span multiple files by
using an \fIinclude\-declaration\fP\&. For example:
.sp
\fBpython/python\-libs.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python\-dateutil:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBpython/django.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- python.python\-libs
django:
pkg.installed:
\- require:
\- pkg: python\-dateutil
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Extend declaration
.sp
You can modify previous declarations by using an \fIextend\-declaration\fP\&. For
example the following modifies the Apache tree to also restart Apache when the
vhosts file is changed:
.sp
\fBapache/apache.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBapache/mywebsite.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- apache.apache
extend:
apache:
service:
\- running
\- watch:
\- file: /etc/httpd/extra/httpd\-vhosts.conf
/etc/httpd/extra/httpd\-vhosts.conf:
file.managed:
\- source: salt://apache/httpd\-vhosts.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "Using extend with require or watch"
.sp
The \fBextend\fP statement works differently for \fBrequire\fP or \fBwatch\fP\&.
It appends to, rather than replacing the requisite component.
.UNINDENT
.UNINDENT
.SS Name declaration
.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
follows:
.sp
\fBapache/mywebsite.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- apache.apache
extend:
apache:
service:
\- running
\- watch:
\- file: mywebsite
mywebsite:
file.managed:
\- name: /etc/httpd/extra/httpd\-vhosts.conf
\- source: salt://apache/httpd\-vhosts.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Names declaration
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stooges:
user.present:
\- names:
\- moe
\- larry
\- curly
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Next steps
.sp
In \fBpart 4\fP we will discuss how to use salt\(aqs
\fBfile_roots\fP to set up a workflow in which states can be
"promoted" from dev, to QA, to production.
.SS States tutorial, part 4
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This tutorial builds on topics covered in \fBpart 1\fP,
\fBpart 2\fP and \fBpart 3\fP\&. It is recommended
that you begin there.
.UNINDENT
.UNINDENT
.sp
This part of the tutorial will show how to use salt\(aqs \fBfile_roots\fP
to set up a workflow in which states can be "promoted" from dev, to QA, to
production.
.SS Salt fileserver path inheritance
.sp
Salt\(aqs fileserver allows for more than one root directory per environment, like
in the below example, which uses both a local directory and a secondary
location shared to the salt master via NFS:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# In the master config file (/etc/salt/master)
file_roots:
base:
\- /srv/salt
\- /mnt/salt\-nfs/base
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt\(aqs fileserver collapses the list of root directories into a single virtual
environment containing all files from each root. If the same file exists at the
same relative path in more than one root, then the top\-most match "wins". For
example, if \fB/srv/salt/foo.txt\fP and \fB/mnt/salt\-nfs/base/foo.txt\fP both
exist, then \fBsalt://foo.txt\fP will point to \fB/srv/salt/foo.txt\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When using multiple fileserver backends, the order in which they are listed
in the \fBfileserver_backend\fP parameter also matters. If both
\fBroots\fP and \fBgit\fP backends contain a file with the same relative path,
and \fBroots\fP appears before \fBgit\fP in the
\fBfileserver_backend\fP list, then the file in \fBroots\fP will
"win", and the file in gitfs will be ignored.
.sp
A more thorough explanation of how Salt\(aqs modular fileserver works can be
found \fIhere\fP\&. We recommend reading this.
.UNINDENT
.UNINDENT
.SS Environment configuration
.sp
Configure a multiple\-environment setup like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt/prod
qa:
\- /srv/salt/qa
\- /srv/salt/prod
dev:
\- /srv/salt/dev
\- /srv/salt/qa
\- /srv/salt/prod
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Given the path inheritance described above, files within \fB/srv/salt/prod\fP
would be available in all environments. Files within \fB/srv/salt/qa\fP would be
available in both \fBqa\fP, and \fBdev\fP\&. Finally, the files within
\fB/srv/salt/dev\fP would only be available within the \fBdev\fP environment.
.sp
Based on the order in which the roots are defined, new files/states can be
placed within \fB/srv/salt/dev\fP, and pushed out to the dev hosts for testing.
.sp
Those files/states can then be moved to the same relative path within
\fB/srv/salt/qa\fP, and they are now available only in the \fBdev\fP and \fBqa\fP
environments, allowing them to be pushed to QA hosts and tested.
.sp
Finally, if moved to the same relative path within \fB/srv/salt/prod\fP, the
files are now available in all three environments.
.SS Practical Example
.sp
As an example, consider a simple website, installed to \fB/var/www/foobarcom\fP\&.
Below is a top.sls that can be used to deploy the website:
.sp
\fB/srv/salt/prod/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqweb*prod*\(aq:
\- webserver.foobarcom
qa:
\(aqweb*qa*\(aq:
\- webserver.foobarcom
dev:
\(aqweb*dev*\(aq:
\- webserver.foobarcom
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using pillar, roles can be assigned to the hosts:
.sp
\fB/srv/pillar/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqweb*prod*\(aq:
\- webserver.prod
\(aqweb*qa*\(aq:
\- webserver.qa
\(aqweb*dev*\(aq:
\- webserver.dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/webserver/prod.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
webserver_role: prod
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/webserver/qa.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
webserver_role: qa
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/webserver/dev.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
webserver_role: dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And finally, the SLS to deploy the website:
.sp
\fB/srv/salt/prod/webserver/foobarcom.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if pillar.get(\(aqwebserver_role\(aq, \(aq\(aq) %}
/var/www/foobarcom:
file.recurse:
\- source: salt://webserver/src/foobarcom
\- env: {{ pillar[\(aqwebserver_role\(aq] }}
\- user: www
\- group: www
\- dir_mode: 755
\- file_mode: 644
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Given the above SLS, the source for the website should initially be placed in
\fB/srv/salt/dev/webserver/src/foobarcom\fP\&.
.sp
First, let\(aqs deploy to dev. Given the configuration in the top file, this can
be done using \fBstate.highstate\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-\-pillar \(aqwebserver_role:dev\(aq state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, in the event that it is not desirable to apply all states configured
in the top file (which could be likely in more complex setups), it is possible
to apply just the states for the \fBfoobarcom\fP website, using \fBstate.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-\-pillar \(aqwebserver_role:dev\(aq state.sls webserver.foobarcom
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once the site has been tested in dev, then the files can be moved from
\fB/srv/salt/dev/webserver/src/foobarcom\fP to
\fB/srv/salt/qa/webserver/src/foobarcom\fP, and deployed using the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-\-pillar \(aqwebserver_role:qa\(aq state.sls webserver.foobarcom
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, once the site has been tested in qa, then the files can be moved from
\fB/srv/salt/qa/webserver/src/foobarcom\fP to
\fB/srv/salt/prod/webserver/src/foobarcom\fP, and deployed using the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-\-pillar \(aqwebserver_role:prod\(aq state.sls webserver.foobarcom
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Thanks to Salt\(aqs fileserver inheritance, even though the files have been moved
to within \fB/srv/salt/prod\fP, they are still available from the same
\fBsalt://\fP URI in both the qa and dev environments.
.SS Continue Learning
.sp
The best way to continue learning about Salt States is to read through the
\fBreference documentation\fP and to look through examples
of existing state trees. Many pre\-configured state trees
can be found on Github in the \fI\%saltstack\-formulas\fP collection of repositories.
.sp
If you have any questions, suggestions, or just want to chat with other people
who are using Salt, we have a very \fIactive community\fP
and we\(aqd love to hear from you.
.sp
In addition, by continuing to \fBpart 5\fP, you can learn about
the powerful orchestration of which Salt is capable.
.SS States Tutorial, Part 5 \- Orchestration with Salt
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This tutorial builds on some of the topics covered in the earlier
\fBStates Walkthrough\fP pages. It is recommended to start with
\fBPart 1\fP if you are not familiar with how to use states.
.UNINDENT
.UNINDENT
.sp
Orchestration is accomplished in salt primarily through the \fI\%Orchestrate
Runner\fP\&. Added in version 0.17.0, this Salt \fBRunner\fP can use the full suite of \fBrequisites\fP available in states, and can also execute
states/functions using salt\-ssh. This runner replaces the \fI\%OverState\fP\&.
.SS The Orchestrate Runner
.sp
New in version 0.17.0.
.sp
As noted above in the introduction, the Orchestrate Runner (originally called
the state.sls runner) offers all the functionality of the OverState, but with a
couple advantages:
.INDENT 0.0
.IP \(bu 2
All \fBrequisites\fP available in states can be
used.
.IP \(bu 2
The states/functions can be executed using salt\-ssh.
.UNINDENT
.sp
The Orchestrate Runner was added with the intent to eventually deprecate the
OverState system, however the OverState will still be maintained for the
foreseeable future.
.SS Configuration Syntax
.sp
The configuration differs slightly from that of the OverState, and more closely
resembles the configuration schema used for states.
.sp
To execute a state, use \fBsalt.state\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
install_nginx:
salt.state:
\- tgt: \(aqweb*\(aq
\- sls:
\- nginx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To execute a function, use \fBsalt.function\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd.run:
salt.function:
\- tgt: \(aq*\(aq
\- arg:
\- rm \-rf /tmp/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Triggering a Highstate
.sp
Whereas with the OverState, a Highstate is run by simply omitting an \fBsls\fP or
\fBfunction\fP argument, with the Orchestrate Runner the Highstate must
explicitly be requested by using \fBhighstate: True\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
webserver_setup:
salt.state:
\- tgt: \(aqweb*\(aq
\- highstate: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Executing the Orchestrate Runner
.sp
The Orchestrate Runner can be executed using the \fBstate.orchestrate\fP runner
function. \fBstate.orch\fP also works, for those that would like to type less.
.sp
Assuming that your \fBbase\fP environment is located at \fB/srv/salt\fP, and you
have placed a configuration file in \fB/srv/salt/orchestration/webserver.sls\fP,
then the following could both be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.orchestrate orchestration.webserver
salt\-run state.orch orchestration.webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.1.1: The runner function was renamed to \fBstate.orchestrate\fP\&. In versions
0.17.0 through 2014.1.0, \fBstate.sls\fP must be used. This was renamed to
avoid confusion with the \fBstate.sls\fP
execution function.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.sls orchestration.webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.SS More Complex Orchestration
.sp
Many states/functions can be configured in a single file, which when combined
with the full suite of \fBrequisites\fP, can be used
to easily configure complex orchestration tasks. Additionally, the
states/functions will be executed in the order in which they are defined,
unless prevented from doing so by any \fBrequisites\fP, as is the default in SLS files since 0.17.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd.run:
salt.function:
\- tgt: 10.0.0.0/24
\- tgt_type: ipcidr
\- arg:
\- bootstrap
storage_setup:
salt.state:
\- tgt: \(aqrole:storage\(aq
\- tgt_type: grain
\- sls: ceph
\- require:
\- salt: webserver_setup
webserver_setup:
salt.state:
\- tgt: \(aqweb*\(aq
\- highstate: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Given the above setup, the orchestration will be carried out as follows:
.INDENT 0.0
.IP 1. 3
The shell command \fBbootstrap\fP will be executed on all minions in the
10.0.0.0/24 subnet.
.IP 2. 3
A Highstate will be run on all minions whose ID starts with "web", since
the \fBstorage_setup\fP state requires it.
.IP 3. 3
Finally, the \fBceph\fP SLS target will be executed on all minions which have
a grain called \fBrole\fP with a value of \fBstorage\fP\&.
.UNINDENT
.SS The OverState System
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
The OverState runner is deprecated, and will be removed in the feature
release of Salt codenamed Boron. (Three feature releases after 2014.7.0,
which is codenamed Helium)
.UNINDENT
.UNINDENT
.sp
Often, servers need to be set up and configured in a specific order, and systems
should only be set up if systems earlier in the sequence have been set up
without any issues.
.sp
The OverState system can be used to orchestrate deployment in a smooth and
reliable way across multiple systems in small to large environments.
.SS The OverState SLS
.sp
The OverState system is managed by an SLS file named \fBoverstate.sls\fP, located
in the root of a Salt fileserver environment.
.sp
The overstate.sls configures an unordered list of stages, each stage defines
the minions on which to execute the state, and can define what sls files to
run, execute a \fBstate.highstate\fP, or
execute a function. Here\(aqs a sample \fBoverstate.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mysql:
match: \(aqdb*\(aq
sls:
\- mysql.server
\- drbd
webservers:
match: \(aqweb*\(aq
require:
\- mysql
all:
match: \(aq*\(aq
require:
\- mysql
\- webservers
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBmatch\fP argument uses \fIcompound matching\fP
.UNINDENT
.UNINDENT
.sp
Given the above setup, the OverState will be carried out as follows:
.INDENT 0.0
.IP 1. 3
The \fBmysql\fP stage will be executed first because it is required by the
\fBwebservers\fP and \fBall\fP stages. It will execute \fBstate.sls\fP once for each of the two listed SLS targets
(\fBmysql.server\fP and \fBdrbd\fP). These states will be executed on all
minions whose minion ID starts with "db".
.IP 2. 3
The \fBwebservers\fP stage will then be executed, but only if the \fBmysql\fP
stage executes without any failures. The \fBwebservers\fP stage will execute a
\fBstate.highstate\fP on all minions whose
minion IDs start with "web".
.IP 3. 3
Finally, the \fBall\fP stage will execute, running \fBstate.highstate\fP on all systems, if and only if the \fBmysql\fP
and \fBwebservers\fP stages completed without any failures.
.UNINDENT
.sp
Any failure in the above steps would cause the requires to fail, preventing the
dependent stages from executing.
.SS Using Functions with OverState
.sp
In the above example, you\(aqll notice that the stages lacking an \fBsls\fP entry
run a \fBstate.highstate\fP\&. As mentioned
earlier, it is also possible to execute other functions in a stage. This
functionality was added in version 0.15.0.
.sp
Running a function is easy:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
http:
function:
pkg.install:
\- httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The list of function arguments are defined after the declared function. So, the
above stage would run \fBpkg.install http\fP\&. Requisites only function properly
if the given function supports returning a custom return code.
.SS Executing an OverState
.sp
Since the OverState is a \fBRunner\fP, it is executed
using the \fBsalt\-run\fP command. The runner function for the OverState is
\fBstate.over\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.over
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The function will by default look in the root of the \fBbase\fP environment (as
defined in \fBfile_roots\fP) for a file called \fBoverstate.sls\fP, and
then execute the stages defined within that file.
.sp
Different environments and paths can be used as well, by adding them as
positional arguments:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.over dev /root/other\-overstate.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above would run an OverState using the \fBdev\fP fileserver environment, with
the stages defined in \fB/root/other\-overstate.sls\fP\&.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Since these are positional arguments, when defining the path to the
overstate file the environment must also be specified, even if it is the
\fBbase\fP environment.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Remember, salt\-run is always executed on the master.
.UNINDENT
.UNINDENT
.SS Syslog\-ng usage
.sp
The syslog_ng state modul is to generate syslog\-ng
configurations. You can do the following things:
.INDENT 0.0
.IP \(bu 2
generate syslog\-ng configuration from YAML,
.IP \(bu 2
use non\-YAML configuration,
.IP \(bu 2
start, stop or reload syslog\-ng.
.UNINDENT
.sp
There is also an execution module, which can check the syntax of the
configuration, get the version and other information about syslog\-ng.
.SS Configuration
.sp
The following configuration is an example, how a complete syslog\-ng
state configuration looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Set the location of the configuration file
"/home/tibi/install/syslog\-ng/etc/syslog\-ng.conf":
syslog_ng.set_config_file
# The syslog\-ng and syslog\-ng\-ctl binaries are here. You needn\(aqt use
# this method if these binaries can be found in a directory in your PATH.
"/home/tibi/install/syslog\-ng/sbin":
syslog_ng.set_binary_path
# Writes the first lines into the config file, also erases its previous
# content
"3.6":
syslog_ng.write_version
# Some global options
global_options:
syslog_ng.config:
\- config:
options:
\- time_reap: 30
\- mark_freq: 10
\- keep_hostname: "yes"
s_localhost:
syslog_ng.config:
\- config:
source:
\- tcp:
\- ip: "127.0.0.1"
\- port: 1233
d_log_server:
syslog_ng.config:
\- config:
destination:
\- tcp:
\- "127.0.0.1"
\- port: 1234
l_log_to_central_server:
syslog_ng.config:
\- config:
log:
\- source: s_localhost
\- destination: d_log_server
some_comment:
syslog_ng.write_config:
\- config: |
# Multi line
# comment
auto_start_or_reload:
{% set pids = salt["ps.pgrep"]("syslog\-ng") %}
{% if pids == None or pids|length == 0 %}
syslog_ng.started:
\- user: tibi
{% else %}
syslog_ng.reloaded
{% endif %}
#auto_stop:
# syslog_ng.stopped
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB3.6\fP, \fBs_devlog\fP, \fBd_log_server\fP, etc. are identifiers. The
second lines in each block are functions and their first parameter is
their id. The \fB\- config\fP is the second named parameter of the
\fBsyslog_ng.config\fP function. This function can generate the syslog\-ng
configuration from YAML. If the statement (source, destination, parser,
etc.) has a name, this function uses the id as the name, otherwise (log
statement) it\(aqs purpose is like a mandatory comment.
.sp
You can use \fBset_binary_path\fP to set the directory which contains the
syslog\-ng and syslog\-ng\-ctl binaries. If this directory is in your PATH,
you don\(aqt need to use this function.
.sp
Under \fBauto_start_or_reload\fP you can see a Jinja template. If
syslog\-ng isn\(aqt running it will start it, otherwise reload it. It uses
the process name \fBsyslog\-ng\fP to determine its running state. I suggest
that you use \fBservice\fP state if it\(aqs available on your system.
.sp
After execution this example the syslog_ng state will generate this
file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#Generated by Salt on 2014\-06\-19 16:53:11
@version: 3.6
options {
time_reap(30);
mark_freq(10);
keep_hostname(yes);
};
source s_localhost {
tcp(
ip("127.0.0.1"),
port(1233)
);
};
destination d_log_server {
tcp(
"127.0.0.1",
port(1234)
);
};
log {
source(s_localhost);
destination(d_log_server);
};
# Multi line
# comment
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Users can include arbitrary texts in the generated configuration with
using the \fBwrite_config\fP function.
.SS Examples
.SS Simple source
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source s_tail {
file(
"/var/log/apache/access.log",
follow_freq(1),
flags(no\-parse, validate\-utf8)
);
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
s_tail:
# Salt will call the source function of syslog_ng module
syslog_ng.config:
\- config:
source:
\- file:
\- file: "/var/log/apache/access.log"
\- follow_freq : 1
\- flags:
\- no\-parse
\- validate\-utf8
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
OR
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
s_tail:
syslog_ng.config:
\- config:
source:
\- file:
\- "/var/log/apache/access.log"
\- follow_freq : 1
\- flags:
\- no\-parse
\- validate\-utf8
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Complex source
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source s_gsoc2014 {
tcp(
ip("0.0.0.0"),
port(1234),
flags(no\-parse)
);
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
s_gsoc2014:
syslog_ng.config:
\- config:
source:
\- tcp:
\- ip: 0.0.0.0
\- port: 1234
\- flags: no\-parse
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Filter
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
filter f_json {
match(
"@json:"
);
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
f_json:
syslog_ng.config:
\- config:
filter:
\- match:
\- "@json:"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Template
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
template t_demo_filetemplate {
template(
"$ISODATE $HOST $MSG "
);
template_escape(
no
);
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
t_demo_filetemplate:
syslog_ng.config:
\-config:
template:
\- template:
\- "$ISODATE $HOST $MSG\en"
\- template_escape:
\- "no"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Rewrite
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rewrite r_set_message_to_MESSAGE {
set(
"${.json.message}",
value("$MESSAGE")
);
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
r_set_message_to_MESSAGE:
syslog_ng.config:
\- config:
rewrite:
\- set:
\- "${.json.message}"
\- value : "$MESSAGE"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Global options
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
options {
time_reap(30);
mark_freq(10);
keep_hostname(yes);
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
global_options:
syslog_ng.config:
\- config:
options:
\- time_reap: 30
\- mark_freq: 10
\- keep_hostname: "yes"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Log
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log {
source(s_gsoc2014);
junction {
channel {
filter(f_json);
parser(p_json);
rewrite(r_set_json_tag);
rewrite(r_set_message_to_MESSAGE);
destination {
file(
"/tmp/json\-input.log",
template(t_gsoc2014)
);
};
flags(final);
};
channel {
filter(f_not_json);
parser {
syslog\-parser(
);
};
rewrite(r_set_syslog_tag);
flags(final);
};
};
destination {
file(
"/tmp/all.log",
template(t_gsoc2014)
);
};
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
l_gsoc2014:
syslog_ng.config:
\- config:
log:
\- source: s_gsoc2014
\- junction:
\- channel:
\- filter: f_json
\- parser: p_json
\- rewrite: r_set_json_tag
\- rewrite: r_set_message_to_MESSAGE
\- destination:
\- file:
\- "/tmp/json\-input.log"
\- template: t_gsoc2014
\- flags: final
\- channel:
\- filter: f_not_json
\- parser:
\- syslog\-parser: []
\- rewrite: r_set_syslog_tag
\- flags: final
\- destination:
\- file:
\- "/tmp/all.log"
\- template: t_gsoc2014
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Advanced Topics
.SS SaltStack Walk\-through
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Welcome to SaltStack! I am excited that you are interested in Salt and
starting down the path to better infrastructure management. I developed
(and am continuing to develop) Salt with the goal of making the best
software available to manage computers of almost any kind. I hope you enjoy
working with Salt and that the software can solve your real world needs!
.INDENT 0.0
.IP \(bu 2
Thomas S Hatch
.IP \(bu 2
Salt creator and Chief Developer
.IP \(bu 2
CTO of SaltStack, Inc.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Getting Started
.SS What is Salt?
.sp
Salt is a different approach to infrastructure management, founded on
the idea that high\-speed communication with large numbers of systems can open
up new capabilities. This approach makes Salt a powerful multitasking system
that can solve many specific problems in an infrastructure.
.sp
The backbone of Salt is the remote execution engine, which creates a high\-speed,
secure and bi\-directional communication net for groups of systems. On top of this
communication system, Salt provides an extremely fast, flexible and easy\-to\-use
configuration management system called \fBSalt States\fP\&.
.SS Installing Salt
.sp
SaltStack has been made to be very easy to install and get started. Setting up
Salt should be as easy as installing Salt via distribution packages on Linux or
via the Windows installer. The \fBinstallation documents\fP cover platform\-specific installation in depth.
.SS Starting Salt
.sp
Salt functions on a master/minion topology. A master server acts as a
central control bus for the clients, which are called \fBminions\fP\&. The minions
connect back to the master.
.SS Setting Up the Salt Master
.sp
Turning on the Salt Master is easy \-\- just turn it on! The default configuration
is suitable for the vast majority of installations. The Salt Master can be
controlled by the local Linux/Unix service manager:
.sp
On Systemd based platforms (OpenSuse, Fedora):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
systemctl start salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Upstart based systems (Ubuntu, older Fedora/RHEL):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
service salt\-master start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On SysV Init systems (Debian, Gentoo etc.):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/init.d/salt\-master start
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, the Master can be started directly on the command\-line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master \-d
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Salt Master can also be started in the foreground in debug mode, thus
greatly increasing the command output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Salt Master needs to bind to two TCP network ports on the system. These ports
are \fB4505\fP and \fB4506\fP\&. For more in depth information on firewalling these ports,
the firewall tutorial is available \fBhere\fP\&.
.SS Setting up a Salt Minion
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The Salt Minion can operate with or without a Salt Master. This walk\-through
assumes that the minion will be connected to the master, for information on
how to run a master\-less minion please see the master\-less quick\-start guide:
.sp
\fBMasterless Minion Quickstart\fP
.UNINDENT
.UNINDENT
.sp
The Salt Minion only needs to be aware of one piece of information to run, the
network location of the master.
.sp
By default the minion will look for the DNS name \fBsalt\fP for the master,
making the easiest approach to set internal DNS to resolve the name \fBsalt\fP
back to the Salt Master IP.
.sp
Otherwise, the minion configuration file will need to be edited so that the
configuration option \fBmaster\fP points to the DNS name or the IP of the Salt Master:
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The default location of the configuration files is \fB/etc/salt\fP\&. Most
platforms adhere to this convention, but platforms such as FreeBSD and
Microsoft Windows place this file in different locations.
.UNINDENT
.UNINDENT
.sp
\fB/etc/salt/minion:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master: saltmaster.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now that the master can be found, start the minion in the same way as the
master; with the platform init system or via the command line directly:
.sp
As a daemon:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion \-d
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the foreground in debug mode:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When the minion is started, it will generate an \fBid\fP value, unless it has
been generated on a previous run and cached in the configuration directory, which
is \fB/etc/salt\fP by default. This is the name by which the minion will attempt
to authenticate to the master. The following steps are attempted, in order to
try to find a value that is not \fBlocalhost\fP:
.INDENT 0.0
.IP 1. 3
The Python function \fBsocket.getfqdn()\fP is run
.IP 2. 3
\fB/etc/hostname\fP is checked (non\-Windows only)
.IP 3. 3
\fB/etc/hosts\fP (\fB%WINDIR%\esystem32\edrivers\eetc\ehosts\fP on Windows hosts) is
checked for hostnames that map to anything within \fB127.0.0.0/8\fP\&.
.UNINDENT
.sp
If none of the above are able to produce an id which is not \fBlocalhost\fP, then
a sorted list of IP addresses on the minion (excluding any within
\fB127.0.0.0/8\fP) is inspected. The first publicly\-routable IP address is
used, if there is one. Otherwise, the first privately\-routable IP address is
used.
.sp
If all else fails, then \fBlocalhost\fP is used as a fallback.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Overriding the \fBid\fP
.sp
The minion id can be manually specified using the \fBid\fP
parameter in the minion config file. If this configuration value is
specified, it will override all other sources for the \fBid\fP\&.
.UNINDENT
.UNINDENT
.sp
Now that the minion is started, it will generate cryptographic keys and attempt
to connect to the master. The next step is to venture back to the master server
and accept the new minion\(aqs public key.
.SS Using salt\-key
.sp
Salt authenticates minions using public\-key encryption and authentication. For
a minion to start accepting commands from the master, the minion keys need to be
accepted by the master.
.sp
The \fBsalt\-key\fP command is used to manage all of the keys on the
master. To list the keys that are on the master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-key \-L
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The keys that have been rejected, accepted and pending acceptance are listed.
The easiest way to accept the minion key is to accept all pending keys:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-key \-A
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Keys should be verified! The secure thing to do before accepting a key is
to run \fBsalt\-key \-f minion\-id\fP to print the fingerprint of the minion\(aqs
public key. This fingerprint can then be compared against the fingerprint
generated on the minion.
.sp
On the master:
.sp
On the minion:
.sp
If they match, approve the key with \fBsalt\-key \-a foo.domain.com\fP\&.
.UNINDENT
.UNINDENT
.SS Sending the First Commands
.sp
Now that the minion is connected to the master and authenticated, the master
can start to command the minion.
.sp
Salt commands allow for a vast set of functions to be executed and for
specific minions and groups of minions to be targeted for execution.
.sp
The \fBsalt\fP command is comprised of command options, target specification,
the function to execute, and arguments to the function.
.sp
A simple command to
start with looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB*\fP is the target, which specifies all minions.
.sp
\fBtest.ping\fP tells the minion to run the \fBtest.ping\fP function.
.sp
In the case of \fBtest.ping\fP, \fBtest\fP refers to a \fBexecution module\fP\&. \fBping\fP refers to the \fBping\fP function contained in the aforementioned \fBtest\fP
module.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Execution modules are the workhorses of Salt. They do the work on the
system to perform various tasks, such as manipulating files and restarting
services.
.UNINDENT
.UNINDENT
.sp
The result of running this command will be the master instructing all of the
minions to execute \fBtest.ping\fP in parallel
and return the result.
.sp
This is not an actual ICMP ping, but rather a simple function which returns \fBTrue\fP\&.
Using \fBtest.ping\fP is a good way of confirming that a minion is
connected.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Each minion registers itself with a unique minion ID. This ID defaults to
the minion\(aqs hostname, but can be explicitly defined in the minion config as
well by using the \fBid\fP parameter.
.UNINDENT
.UNINDENT
.sp
Of course, there are hundreds of other modules that can be called just as
\fBtest.ping\fP can. For example, the following would return disk usage on all
targeted minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq disk.percent
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting to Know the Functions
.sp
Salt comes with a vast library of functions available for execution, and Salt
functions are self\-documenting. To see what functions are available on the
minions execute the \fBsys.doc\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will display a very large list of available functions and documentation on
them.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Module documentation is also available \fBon the web\fP\&.
.UNINDENT
.UNINDENT
.sp
These functions cover everything from shelling out to package management to
manipulating database servers. They comprise a powerful system management API
which is the backbone to Salt configuration management and many other aspects
of Salt.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Salt comes with many plugin systems. The functions that are available via
the \fBsalt\fP command are called \fBExecution Modules\fP\&.
.UNINDENT
.UNINDENT
.SS Helpful Functions to Know
.sp
The \fBcmd\fP module contains
functions to shell out on minions, such as \fBcmd.run\fP and \fBcmd.run_all\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run \(aqls \-l /etc\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBpkg\fP functions automatically map local system package managers to the
same salt functions. This means that \fBpkg.install\fP will install packages via
\fByum\fP on Red Hat based systems, \fBapt\fP on Debian systems, etc.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Some custom Linux spins and derivatives of other distributions are not properly
detected by Salt. If the above command returns an error message saying that
\fBpkg.install\fP is not available, then you may need to override the pkg
provider. This process is explained \fBhere\fP\&.
.UNINDENT
.UNINDENT
.sp
The \fBnetwork.interfaces\fP function will
list all interfaces on a minion, along with their IP addresses, netmasks, MAC
addresses, etc:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Changing the Output Format
.sp
The default output format used for most Salt commands is called the \fBnested\fP
outputter, but there are several other outputters that can be used to change
the way the output is displayed. For instance, the \fBpprint\fP outputter can be
used to display the return data using Python\(aqs \fBpprint\fP module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root@saltmaster:~# salt myminion grains.item pythonpath \-\-out=pprint
{\(aqmyminion\(aq: {\(aqpythonpath\(aq: [\(aq/usr/lib64/python2.7\(aq,
\(aq/usr/lib/python2.7/plat\-linux2\(aq,
\(aq/usr/lib64/python2.7/lib\-tk\(aq,
\(aq/usr/lib/python2.7/lib\-tk\(aq,
\(aq/usr/lib/python2.7/site\-packages\(aq,
\(aq/usr/lib/python2.7/site\-packages/gst\-0.10\(aq,
\(aq/usr/lib/python2.7/site\-packages/gtk\-2.0\(aq]}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The full list of Salt outputters, as well as example output, can be found
\fIhere\fP\&.
.SS \fBsalt\-call\fP
.sp
The examples so far have described running commands from the Master using the
\fBsalt\fP command, but when troubleshooting it can be more beneficial to login
to the minion directly and use \fBsalt\-call\fP\&.
.sp
Doing so allows you to see the minion log messages specific to the command you
are running (which are \fInot\fP part of the return data you see when running the
command from the Master using \fBsalt\fP), making it unnecessary to tail the
minion log. More information on \fBsalt\-call\fP and how to use it can be found
\fIhere\fP\&.
.SS Grains
.sp
Salt uses a system called \fBGrains\fP to build up
static data about minions. This data includes information about the operating
system that is running, CPU architecture and much more. The grains system is
used throughout Salt to deliver platform data to many components and to users.
.sp
Grains can also be statically set, this makes it easy to assign values to
minions for grouping and managing.
.sp
A common practice is to assign grains to minions to specify what the role or
roles a minion might be. These static grains can be set in the minion
configuration file or via the \fBgrains.setval\fP
function.
.SS Targeting
.sp
Salt allows for minions to be targeted based on a wide range of criteria. The
default targeting system uses globular expressions to match minions, hence if
there are minions named \fBlarry1\fP, \fBlarry2\fP, \fBcurly1\fP and \fBcurly2\fP, a
glob of \fBlarry*\fP will match \fBlarry1\fP and \fBlarry2\fP, and a glob of \fB*1\fP
will match \fBlarry1\fP and \fBcurly1\fP\&.
.sp
Many other targeting systems can be used other than globs, these systems
include:
.INDENT 0.0
.TP
.B Regular Expressions
Target using PCRE\-compliant regular expressions
.TP
.B Grains
Target based on grains data:
\fBTargeting with Grains\fP
.TP
.B Pillar
Target based on pillar data:
\fBTargeting with Pillar\fP
.TP
.B IP
Target based on IP address/subnet/range
.TP
.B Compound
Create logic to target based on multiple targets:
\fBTargeting with Compound\fP
.TP
.B Nodegroup
Target with nodegroups:
\fBTargeting with Nodegroup\fP
.UNINDENT
.sp
The concepts of targets are used on the command line with Salt, but also
function in many other areas as well, including the state system and the
systems used for ACLs and user permissions.
.SS Passing in Arguments
.sp
Many of the functions available accept arguments which can be passed in on
the command line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example passes the argument \fBvim\fP to the pkg.install function. Since
many functions can accept more complex input then just a string, the arguments
are parsed through YAML, allowing for more complex data to be sent on the
command line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.echo \(aqfoo: bar\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this case Salt translates the string \(aqfoo: bar\(aq into the dictionary
"{\(aqfoo\(aq: \(aqbar\(aq}"
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Any line that contains a newline will not be parsed by YAML.
.UNINDENT
.UNINDENT
.SS Salt States
.sp
Now that the basics are covered the time has come to evaluate \fBStates\fP\&. Salt
\fBStates\fP, or the \fBState System\fP is the component of Salt made for
configuration management.
.sp
The state system is already available with a basic Salt setup, no additional
configuration is required. States can be set up immediately.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Before diving into the state system, a brief overview of how states are
constructed will make many of the concepts clearer. Salt states are based
on data modeling and build on a low level data structure that is used to
execute each state function. Then more logical layers are built on top of
each other.
.sp
The high layers of the state system which this tutorial will
cover consists of everything that needs to be known to use states, the two
high layers covered here are the \fIsls\fP layer and the highest layer
\fIhighstate\fP\&.
.sp
Understanding the layers of data management in the State System will help with
understanding states, but they never need to be used. Just as understanding
how a compiler functions assists when learning a programming language,
understanding what is going on under the hood of a configuration management
system will also prove to be a valuable asset.
.UNINDENT
.UNINDENT
.SS The First SLS Formula
.sp
The state system is built on SLS formulas. These formulas are built out in
files on Salt\(aqs file server. To make a very basic SLS formula open up a file
under /srv/salt named vim.sls. The following state ensures that vim is installed
on a system to which that state has been applied.
.sp
\fB/srv/salt/vim.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now install vim on the minions by calling the SLS directly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.sls vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This command will invoke the state system and run the \fBvim\fP SLS.
.sp
Now, to beef up the vim SLS formula, a \fBvimrc\fP can be added:
.sp
\fB/srv/salt/vim.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed: []
/etc/vimrc:
file.managed:
\- source: salt://vimrc
\- mode: 644
\- user: root
\- group: root
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the desired \fBvimrc\fP needs to be copied into the Salt file server to
\fB/srv/salt/vimrc\fP\&. In Salt, everything is a file, so no path redirection needs
to be accounted for. The \fBvimrc\fP file is placed right next to the \fBvim.sls\fP file.
The same command as above can be executed to all the vim SLS formulas and now
include managing the file.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Salt does not need to be restarted/reloaded or have the master manipulated
in any way when changing SLS formulas. They are instantly available.
.UNINDENT
.UNINDENT
.SS Adding Some Depth
.sp
Obviously maintaining SLS formulas right in a single directory at the root of
the file server will not scale out to reasonably sized deployments. This is
why more depth is required. Start by making an nginx formula a better way,
make an nginx subdirectory and add an init.sls file:
.sp
\fB/srv/salt/nginx/init.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nginx:
pkg.installed: []
service.running:
\- require:
\- pkg: nginx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A few concepts are introduced in this SLS formula.
.sp
First is the service statement which ensures that the \fBnginx\fP service is running.
.sp
Of course, the nginx service can\(aqt be started unless the package is installed \-\-
hence the \fBrequire\fP statement which sets up a dependency between the two.
.sp
The \fBrequire\fP statement makes sure that the required component is executed before
and that it results in success.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fIrequire\fP option belongs to a family of options called \fIrequisites\fP\&.
Requisites are a powerful component of Salt States, for more information
on how requisites work and what is available see:
\fBRequisites\fP
.sp
Also evaluation ordering is available in Salt as well:
\fBOrdering States\fP
.UNINDENT
.UNINDENT
.sp
This new sls formula has a special name \-\- \fBinit.sls\fP\&. When an SLS formula is
named \fBinit.sls\fP it inherits the name of the directory path that contains it.
This formula can be referenced via the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.sls nginx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Reminder!
.sp
Just as one could call the \fBtest.ping\fP or \fBdisk.usage\fP execution modules,
\fBstate.sls\fP is simply another execution module. It simply takes the name of an
SLS file as an argument.
.UNINDENT
.UNINDENT
.sp
Now that subdirectories can be used, the \fBvim.sls\fP formula can be cleaned up.
To make things more flexible, move the \fBvim.sls\fP and vimrc into a new subdirectory
called \fBedit\fP and change the \fBvim.sls\fP file to reflect the change:
.sp
\fB/srv/salt/edit/vim.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed
/etc/vimrc:
file.managed:
\- source: salt://edit/vimrc
\- mode: 644
\- user: root
\- group: root
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Only the source path to the vimrc file has changed. Now the formula is
referenced as \fBedit.vim\fP because it resides in the edit subdirectory.
Now the edit subdirectory can contain formulas for emacs, nano, joe or any other
editor that may need to be deployed.
.SS Next Reading
.sp
Two walk\-throughs are specifically recommended at this point. First, a deeper
run through States, followed by an explanation of Pillar.
.INDENT 0.0
.IP 1. 3
\fBStarting States\fP
.IP 2. 3
\fBPillar Walkthrough\fP
.UNINDENT
.sp
An understanding of Pillar is extremely helpful in using States.
.SS Getting Deeper Into States
.sp
Two more in\-depth States tutorials exist, which delve much more deeply into States
functionality.
.INDENT 0.0
.IP 1. 3
Thomas\(aq original states tutorial, \fBHow Do I Use Salt
States?\fP, covers much more to get off the
ground with States.
.IP 2. 3
The \fBStates Tutorial\fP also provides a
fantastic introduction.
.UNINDENT
.sp
These tutorials include much more in\-depth information including templating
SLS formulas etc.
.SS So Much More!
.sp
This concludes the initial Salt walk\-through, but there are many more things still
to learn! These documents will cover important core aspects of Salt:
.INDENT 0.0
.IP \(bu 2
\fBPillar\fP
.IP \(bu 2
\fBJob Management\fP
.UNINDENT
.sp
A few more tutorials are also available:
.INDENT 0.0
.IP \(bu 2
\fBRemote Execution Tutorial\fP
.IP \(bu 2
\fBStandalone Minion\fP
.UNINDENT
.sp
This still is only scratching the surface, many components such as the reactor
and event systems, extending Salt, modular components and more are not covered
here. For an overview of all Salt features and documentation, look at the
\fBTable of Contents\fP\&.
.SS MinionFS Backend Walkthrough
.sp
New in version 2014.1.0.
.sp
Sometimes, you might need to propagate files that are generated on a minion.
Salt already has a feature to send files from a minion to the master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\-id\(aq cp.push /path/to/the/file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This command will store the file, including its full path, under
\fBcachedir\fP \fB/master/minions/minion\-id/files\fP\&. With the default
\fBcachedir\fP the example file above would be stored as
\fI/var/cache/salt/master/minions/minion\-id/files/path/to/the/file\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This walkthrough assumes basic knowledge of Salt and \fBcp.push\fP\&. To get up to speed, check out the
\fBwalkthrough\fP\&.
.UNINDENT
.UNINDENT
.sp
Since it is not a good idea to expose the whole \fBcachedir\fP, MinionFS
should be used to send these files to other minions.
.SS Simple Configuration
.sp
To use the minionfs backend only two configuration changes are required on the
master. The \fBfileserver_backend\fP option needs to contain a value of
\fBminion\fP and \fBfile_recv\fP needs to be set to true:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- roots
\- minion
file_recv: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These changes require a restart of the master, then new requests for the
\fBsalt://minion\-id/\fP protocol will send files that are pushed by \fBcp.push\fP
from \fBminion\-id\fP to the master.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
All of the files that are pushed to the master are going to be available to
all of the minions. If this is not what you want, please remove \fBminion\fP
from \fBfileserver_backend\fP in the master config file.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Having directories with the same name as your minions in the root
that can be accessed like \fBsalt://minion\-id/\fP might cause confusion.
.UNINDENT
.UNINDENT
.SS Commandline Example
.sp
Lets assume that we are going to generate SSH keys on a minion called
\fBminion\-source\fP and put the public part in \fB~/.ssh/authorized_keys\fP of root
user of a minion called \fBminion\-destination\fP\&.
.sp
First, lets make sure that \fB/root/.ssh\fP exists and has the right permissions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@salt\-master file]# salt \(aq*\(aq file.mkdir dir_path=/root/.ssh user=root group=root mode=700
minion\-source:
None
minion\-destination:
None
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
We create an RSA key pair without a passphrase [*]:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@salt\-master file]# salt \(aqminion\-source\(aq cmd.run \(aqssh\-keygen \-N "" \-f /root/.ssh/id_rsa\(aq
minion\-source:
Generating public/private rsa key pair.
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
9b:cd:1c:b9:c2:93:8e:ad:a3:52:a0:8b:0a:cc:d4:9b root@minion\-source
The key\(aqs randomart image is:
+\-\-[ RSA 2048]\-\-\-\-+
| |
| |
| |
| o . |
| o o S o |
|= + . B o |
|o+ E B = |
|+ . .+ o |
|o ...ooo |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and we send the public part to the master to be available to all minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@salt\-master file]# salt \(aqminion\-source\(aq cp.push /root/.ssh/id_rsa.pub
minion\-source:
True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
now it can be seen by everyone:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@salt\-master file]# salt \(aqminion\-destination\(aq cp.list_master_dirs
minion\-destination:
\- .
\- etc
\- minion\-source/root
\- minion\-source/root/.ssh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lets copy that as the only authorized key to \fBminion\-destination\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@salt\-master file]# salt \(aqminion\-destination\(aq cp.get_file salt://minion\-source/root/.ssh/id_rsa.pub /root/.ssh/authorized_keys
minion\-destination:
/root/.ssh/authorized_keys
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or we can use a more elegant and salty way to add an SSH key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@salt\-master file]# salt \(aqminion\-destination\(aq ssh.set_auth_key_from_file user=root source=salt://minion\-source/root/.ssh/id_rsa.pub
minion\-destination:
new
.ft P
.fi
.UNINDENT
.UNINDENT
.IP [*] 5
Yes, that was the actual key on my server, but the server is already destroyed.
.SS Automatic Updates / Frozen Deployments
.sp
New in version 0.10.3.d.
.sp
Salt has support for the
\fI\%Esky\fP application freezing and update
tool. This tool allows one to build a complete zipfile out of the salt scripts
and all their dependencies \- including shared objects / DLLs.
.SS Getting Started
.sp
To build frozen applications, you\(aqll need a suitable build environment for each
of your platforms. You should probably set up a virtualenv in order to limit
the scope of Q/A.
.sp
This process does work on Windows. Follow the directions at
\fI\%https://github.com/saltstack/salt\-windows\-install\fP for details on
installing Salt in Windows. Only the 32\-bit Python and dependencies have been
tested, but they have been tested on 64\-bit Windows.
.sp
You will need to install \fBesky\fP and \fBbbfreeze\fP from PyPI in order to enable
the \fBbdist_esky\fP command in \fBsetup.py\fP\&.
.SS Building and Freezing
.sp
Once you have your tools installed and the environment configured, you can then
\fBpython setup.py bdist\fP to get the eggs prepared. After that is done, run
\fBpython setup.py bdist_esky\fP to have Esky traverse the module tree and pack
all the scripts up into a redistributable. There will be an appropriately
versioned \fBsalt\-VERSION.zip\fP in \fBdist/\fP if everything went smoothly.
.SS Windows
.sp
You will need to add \fBC:\ePython27\elib\esite\-packages\ezmq\fP to your PATH
variable. This helps bbfreeze find the zmq DLL so it can pack it up.
.SS Using the Frozen Build
.sp
Unpack the zip file in your desired install location. Scripts like
\fBsalt\-minion\fP and \fBsalt\-call\fP will be in the root of the zip file. The
associated libraries and bootstrapping will be in the directories at the same
level. (Check the \fI\%Esky\fP documentation
for more information)
.sp
To support updating your minions in the wild, put your builds on a web server
that your minions can reach. \fBsalt.modules.saltutil.update()\fP will
trigger an update and (optionally) a restart of the minion service under the
new version.
.SS Gotchas
.SS My Windows minion isn\(aqt responding
.sp
The process dispatch on Windows is slower than it is on *nix. You may need to
add \(aq\-t 15\(aq to your salt calls to give them plenty of time to return.
.SS Windows and the Visual Studio Redist
.sp
You will need to install the Visual C++ 2008 32\-bit redistributable on all
Windows minions. Esky has an option to pack the library into the zipfile,
but OpenSSL does not seem to acknowledge the new location. If you get a
\fBno OPENSSL_Applink\fP error on the console when trying to start your
frozen minion, you have forgotten to install the redistributable.
.SS Mixed Linux environments and Yum
.sp
The Yum Python module doesn\(aqt appear to be available on any of the standard
Python package mirrors. If you need to support RHEL/CentOS systems, you
should build on that platform to support all your Linux nodes. Also remember
to build your virtualenv with \fB\-\-system\-site\-packages\fP so that the
\fByum\fP module is included.
.SS Automatic (Python) module discovery
.sp
Automatic (Python) module discovery does not work with the late\-loaded scheme that
Salt uses for (Salt) modules. You will need to explicitly add any
misbehaving modules to the \fBfreezer_includes\fP in Salt\(aqs \fBsetup.py\fP\&.
Always check the zipped application to make sure that the necessary modules
were included.
.SS Multi Master Tutorial
.sp
As of Salt 0.16.0, the ability to connect minions to multiple masters has been
made available. The multi\-master system allows for redundancy of Salt
masters and facilitates multiple points of communication out to minions. When
using a multi\-master setup, all masters are running hot, and any active master
can be used to send commands out to the minions.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you need failover capabilities with multiple masters, there is also a
MultiMaster\-PKI setup available, that uses a different topology
\fI\%MultiMaster\-PKI with Failover Tutorial\fP
.UNINDENT
.UNINDENT
.sp
In 0.16.0, the masters do not share any information, keys need to be accepted
on both masters, and shared files need to be shared manually or use tools like
the git fileserver backend to ensure that the \fBfile_roots\fP are
kept consistent.
.SS Summary of Steps
.INDENT 0.0
.IP 1. 3
Create a redundant master server
.IP 2. 3
Copy primary master key to redundant master
.IP 3. 3
Start redundant master
.IP 4. 3
Configure minions to connect to redundant master
.IP 5. 3
Restart minions
.IP 6. 3
Accept keys on redundant master
.UNINDENT
.SS Prepping a Redundant Master
.sp
The first task is to prepare the redundant master. If the redundant master is
already running, stop it. There is only one requirement when preparing a
redundant master, which is that masters share the same private key. When the
first master was created, the master\(aqs identifying key pair was generated and
placed in the master\(aqs \fBpki_dir\fP\&. The default location of the master\(aqs key
pair is \fB/etc/salt/pki/master/\fP\&. Take the private key, \fBmaster.pem\fP and
copy it to the same location on the redundant master. Do the same for the
master\(aqs public key, \fBmaster.pub\fP\&. Assuming that no minions have yet been
connected to the new redundant master, it is safe to delete any existing key
in this location and replace it.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
There is no logical limit to the number of redundant masters that can be
used.
.UNINDENT
.UNINDENT
.sp
Once the new key is in place, the redundant master can be safely started.
.SS Configure Minions
.sp
Since minions need to be master\-aware, the new master needs to be added to the
minion configurations. Simply update the minion configurations to list all
connected masters:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master:
\- saltmaster1.example.com
\- saltmaster2.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the minion can be safely restarted.
.sp
Now the minions will check into the original master and also check into the new
redundant master. Both masters are first\-class and have rights to the minions.
.SS Sharing Files Between Masters
.sp
Salt does not automatically share files between multiple masters. A number of
files should be shared or sharing of these files should be strongly considered.
.SS Minion Keys
.sp
Minion keys can be accepted the normal way using \fBsalt\-key\fP on both
masters. Keys accepted, deleted, or rejected on one master will NOT be
automatically managed on redundant masters; this needs to be taken care of by
running salt\-key on both masters or sharing the
\fB/etc/salt/pki/master/{minions,minions_pre,minions_rejected}\fP directories
between masters.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
While sharing the \fB/etc/salt/pki/master\fP directory will work, it is
strongly discouraged, since allowing access to the \fBmaster.pem\fP key
outside of Salt creates a \fISERIOUS\fP security risk.
.UNINDENT
.UNINDENT
.SS File_Roots
.sp
The \fBfile_roots\fP contents should be kept consistent between
masters. Otherwise state runs will not always be consistent on minions since
instructions managed by one master will not agree with other masters.
.sp
The recommended way to sync these is to use a fileserver backend like gitfs or
to keep these files on shared storage.
.SS Pillar_Roots
.sp
Pillar roots should be given the same considerations as
\fBfile_roots\fP\&.
.SS Master Configurations
.sp
While reasons may exist to maintain separate master configurations, it is wise
to remember that each master maintains independent control over minions.
Therefore, access controls should be in sync between masters unless a valid
reason otherwise exists to keep them inconsistent.
.sp
These access control options include but are not limited to:
.INDENT 0.0
.IP \(bu 2
external_auth
.IP \(bu 2
client_acl
.IP \(bu 2
peer
.IP \(bu 2
peer_run
.UNINDENT
.SS Multi\-Master\-PKI Tutorial With Failover
.sp
This tutorial will explain, how to run a salt\-environment where a single
minion can have multiple masters and fail\-over between them if its current
master fails.
.sp
The individual steps are
.INDENT 0.0
.IP \(bu 2
setup the master(s) to sign its auth\-replies
.IP \(bu 2
setup minion(s) to verify master\-public\-keys
.IP \(bu 2
enable multiple masters on minion(s)
.IP \(bu 2
enable master\-check on minion(s)
.INDENT 2.0
.INDENT 3.5
Please note, that it is advised to have good knowledge of the salt\-
authentication and communication\-process to understand this tutorial.
All of the settings described here, go on top of the default
authentication/communication process.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Motivation
.sp
The default behaviour of a salt\-minion is to connect to a master and accept
the masters public key. With each publication, the master sends his public\-key
for the minion to check and if this public\-key ever changes, the minion
complains and exits. Practically this means, that there can only be a single
master at any given time.
.sp
Would it not be much nicer, if the minion could have any number of masters
(1:n) and jump to the next master if its current master died because of a
network or hardware failure?
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
There is also a MultiMaster\-Tutorial with a different approach and topology
than this one, that might also suite your needs or might even be better suited
\fI\%Multi\-Master Tutorial\fP
.UNINDENT
.UNINDENT
.sp
It is also desirable, to add some sort of authenticity\-check to the very first
public key a minion receives from a master. Currently a minions takes the
first masters public key for granted.
.SS The Goal
.sp
Setup the master to sign the public key it sends to the minions and enable the
minions to verify this signature for authenticity.
.SS Prepping the master to sign its public key
.sp
For signing to work, both master and minion must have the signing and/or
verification settings enabled. If the master signs the public key but the
minion does not verify it, the minion will complain and exit. The same
happens, when the master does not sign but the minion tries to verify.
.sp
The easiest way to have the master sign its public key is to set
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign_pubkey: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After restarting the salt\-master service, the master will automatically
generate a new key\-pair
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign.pem
master_sign.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A custom name can be set for the signing key\-pair by setting
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign_key_name: <name_without_suffix>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The master will then generate that key\-pair upon restart and use it for
creating the public keys signature attached to the auth\-reply.
.sp
The computation is done for every auth\-request of a minion. If many minions
auth very often, it is advised to use conf_master:\fImaster_pubkey_signature\fP
and conf_master:\fImaster_use_pubkey_signature\fP settings described below.
.sp
If multiple masters are in use and should sign their auth\-replies, the signing
key\-pair master_sign.* has to be copied to each master. Otherwise a minion
will fail to verify the masters public when connecting to a different master
than it did initially. That is because the public keys signature was created
with a different signing key\-pair.
.SS Prepping the minion to verify received public keys
.sp
The minion must have the public key (and only that one!) available to be
able to verify a signature it receives. That public key (defaults to
master_sign.pub) must be copied from the master to the minions pki\-directory.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/pki/minion/master_sign.pub
DO NOT COPY THE master_sign.pem FILE. IT MUST STAY ON THE MASTER AND
ONLY THERE!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When that is done, enable the signature checking in the minions configuration
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
verify_master_pubkey_sign: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and restart the minion. For the first try, the minion should be run in manual
debug mode.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-minion \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Upon connecting to the master, the following lines should appear on the output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
[DEBUG ] salt.crypt.verify_signature: Loading public key
[DEBUG ] salt.crypt.verify_signature: Verifying signature
[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
[INFO ] Received signed and verified master pubkey from master 172.16.0.10
[DEBUG ] Decrypting the current master AES key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the signature verification fails, something went wrong and it will look
like this
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
[DEBUG ] salt.crypt.verify_signature: Loading public key
[DEBUG ] salt.crypt.verify_signature: Verifying signature
[DEBUG ] Failed to verify signature of public key
[CRITICAL] The Salt Master server\(aqs public key did not authenticate!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In a case like this, it should be checked, that the verification pubkey
(master_sign.pub) on the minion is the same as the one on the master.
.sp
Once the verification is successful, the minion can be started in daemon mode
again.
.sp
For the paranoid among us, its also possible to verify the public whenever it
is received from the master. That is, for every single auth\-attempt which can be
quite frequent. For example just the start of the minion will force the signature
to be checked 6 times for various things like auth, mine, highstate, etc.
.sp
If that is desired, enable the setting
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
always_verify_signature: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Multiple Masters For A Minion
.sp
Configuring multiple masters on a minion is done by specifying two settings:
.INDENT 0.0
.IP \(bu 2
a list of masters addresses
.IP \(bu 2
what type of master is defined
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master:
\- 172.16.0.10
\- 172.16.0.11
\- 172.16.0.12
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_type: failover
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This tells the minion that all the master above are available for it to
connect to. When started with this configuration, it will try the master
in the order they are defined. To randomize that order, set
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_shuffle: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The master\-list will then be shuffled before the first connection attempt.
.sp
The first master that accepts the minion, is used by the minion. If the
master does not yet know the minion, that counts as accepted and the minion
stays on that master.
.sp
For the minion to be able to detect if its still connected to its current
master enable the check for it
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_alive_interval: <seconds>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the loss of the connection is detected, the minion will temporarily
remove the failed master from the list and try one of the other masters
defined (again shuffled if that is enabled).
.SS Testing the setup
.sp
At least two running masters are needed to test the failover setup.
.sp
Both masters should be running and the minion should be running on the command
line in debug mode
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-minion \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The minion will connect to the first master from its master list
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
[DEBUG ] salt.crypt.verify_signature: Loading public key
[DEBUG ] salt.crypt.verify_signature: Verifying signature
[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
[INFO ] Received signed and verified master pubkey from master 172.16.0.10
[DEBUG ] Decrypting the current master AES key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A test.ping on the master the minion is currently connected to should be run to
test connectivity.
.sp
If successful, that master should be turned off. A firewall\-rule denying the
minions packets will also do the trick.
.sp
Depending on the configured conf_minion:\fImaster_alive_interval\fP, the minion
will notice the loss of the connection and log it to its logfile.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[INFO ] Connection to master 172.16.0.10 lost
[INFO ] Trying to tune in to next master from master\-list
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The minion will then remove the current master from the list and try connecting
to the next master
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[INFO ] Removing possibly failed master 172.16.0.10 from list of masters
[WARNING ] Master ip address changed from 172.16.0.10 to 172.16.0.11
[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.11
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If everything is configured correctly, the new masters public key will be
verified successfully
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
[DEBUG ] salt.crypt.verify_signature: Loading public key
[DEBUG ] salt.crypt.verify_signature: Verifying signature
[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the authentication with the new master is successful
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[INFO ] Received signed and verified master pubkey from master 172.16.0.11
[DEBUG ] Decrypting the current master AES key
[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
[INFO ] Authentication with master successful!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and the minion can be pinged again from its new master.
.SS Performance Tuning
.sp
With the setup described above, the master computes a signature for every
auth\-request of a minion. With many minions and many auth\-requests, that
can chew up quite a bit of CPU\-Power.
.sp
To avoid that, the master can use a pre\-created signature of its public\-key.
The signature is saved as a base64 encoded string which the master reads
once when starting and attaches only that string to auth\-replies.
.sp
DO ME HERE
Enabling this also gives paranoid users the possibility, to have the signing
key\-pair on a different system than the actual salt\-master and create the public
keys signature there. Probably on a system with more restrictive firewall rules,
without internet access, less users, etc.
.sp
That signature can be created with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-key \-\-gen\-signature
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create a default signature file in the master pki\-directory
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/pki/master/master_pubkey_signature
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is a simple text\-file with the binary\-signature converted to base64.
.sp
If no signing\-pair is present yet, this will auto\-create the signing pair and
the signature file in one call
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-key \-\-gen\-signature \-\-auto\-create
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Telling the master to use the pre\-created signature is done with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_use_pubkey_signature: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That requires the file \(aqmaster_pubkey_signature\(aq to be present in the masters
pki\-directory with the correct signature.
.sp
If the signature file is named differently, its name can be set with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_pubkey_signature: <filename>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With many masters and many public\-keys (default and signing), it is advised to
use the salt\-masters hostname for the signature\-files name. Signatures can be
easily confused because they do not provide any information about the key the
signature was created from.
.sp
Verifying that everything works is done the same way as above.
.SS How the signing and verification works
.sp
The default key\-pair of the salt\-master is
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/pki/master/master.pem
/etc/salt/pki/master/master.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To be able to create a signature of a message (in this case a public\-key),
another key\-pair has to be added to the setup. Its default name is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign.pem
master_sign.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The combination of the master.* and master_sign.* key\-pairs give the
possibility of generating signatures. The signature of a given message
is unique and can be verified, if the public\-key of the signing\-key\-pair
is available to the recipient (the minion).
.sp
The signature of the masters public\-key in master.pub is computed with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign.pem
master.pub
M2Crypto.EVP.sign_update()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This results in a binary signature which is converted to base64 and attached
to the auth\-reply send to the minion.
.sp
With the signing\-pairs public\-key available to the minion, the attached
signature can be verified with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign.pub
master.pub
M2Cryptos EVP.verify_update().
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When running multiple masters, either the signing key\-pair has to be present
on all of them, or the master_pubkey_signature has to be pre\-computed for
each master individually (because they all have different public\-keys).
.INDENT 0.0
.INDENT 3.5
DO NOT PUT THE SAME master.pub ON ALL MASTERS FOR EASE OF USE.
.UNINDENT
.UNINDENT
.SS Preseed Minion with Accepted Key
.sp
In some situations, it is not convenient to wait for a minion to start before
accepting its key on the master. For instance, you may want the minion to
bootstrap itself as soon as it comes online. You may also want to to let your
developers provision new development machines on the fly.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
Many ways to preseed minion keys
.sp
Salt has other ways to generate and pre\-accept minion keys in addition to
the manual steps outlined below.
.sp
salt\-cloud performs these same steps automatically when new cloud VMs are
created (unless instructed not to).
.sp
salt\-api exposes an HTTP call to Salt\(aqs REST API to \fBgenerate and
download the new minion keys as a tarball\fP\&.
.UNINDENT
.UNINDENT
.sp
There is a general four step process to do this:
.INDENT 0.0
.IP 1. 3
Generate the keys on the master:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root@saltmaster# salt\-key \-\-gen\-keys=[key_name]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Pick a name for the key, such as the minion\(aqs id.
.INDENT 0.0
.IP 2. 3
Add the public key to the accepted minion folder:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root@saltmaster# cp key_name.pub /etc/salt/pki/master/minions/[minion_id]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is necessary that the public key file has the same name as your minion id.
This is how Salt matches minions with their keys. Also note that the pki folder
could be in a different location, depending on your OS or if specified in the
master config file.
.INDENT 0.0
.IP 3. 3
Distribute the minion keys.
.UNINDENT
.sp
There is no single method to get the keypair to your minion. The difficulty is
finding a distribution method which is secure. For Amazon EC2 only, an AWS best
practice is to use IAM Roles to pass credentials. (See blog post,
\fI\%http://blogs.aws.amazon.com/security/post/Tx610S2MLVZWEA/Using\-IAM\-roles\-to\-distribute\-non\-AWS\-credentials\-to\-your\-EC2\-instances\fP )
.INDENT 0.0
.INDENT 3.5
.IP "Security Warning"
.sp
Since the minion key is already accepted on the master, distributing
the private key poses a potential security risk. A malicious party
will have access to your entire state tree and other sensitive data if they
gain access to a preseeded minion key.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 4. 3
Preseed the Minion with the keys
.UNINDENT
.sp
You will want to place the minion keys before starting the salt\-minion daemon:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/pki/minion/minion.pem
/etc/salt/pki/minion/minion.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once in place, you should be able to start salt\-minion and run
\fBsalt\-call state.highstate\fP or any other salt commands that require master
authentication.
.SS Salt Bootstrap
.sp
The Salt Bootstrap script allows for a user to install the Salt Minion or
Master on a variety of system distributions and versions. This shell script
known as \fBbootstrap\-salt.sh\fP runs through a series of checks to determine
the operating system type and version. It then installs the Salt binaries
using the appropriate methods. The Salt Bootstrap script installs the
minimum number of packages required to run Salt. This means that in the event
you run the bootstrap to install via package, Git will not be installed.
Installing the minimum number of packages helps ensure the script stays as
lightweight as possible, assuming the user will install any other required
packages after the Salt binaries are present on the system. The script source
is available on GitHub: \fI\%https://github.com/saltstack/salt\-bootstrap\fP
.SS Supported Operating Systems
.INDENT 0.0
.IP \(bu 2
Amazon Linux 2012.09
.IP \(bu 2
Arch
.IP \(bu 2
CentOS 5/6
.IP \(bu 2
Debian 6.x/7.x/8(git installations only)
.IP \(bu 2
Fedora 17/18
.IP \(bu 2
FreeBSD 9.1/9.2/10
.IP \(bu 2
Gentoo
.IP \(bu 2
Linaro
.IP \(bu 2
Linux Mint 13/14
.IP \(bu 2
OpenSUSE 12.x
.IP \(bu 2
Oracle Linux 5/5
.IP \(bu 2
Red Hat 5/6
.IP \(bu 2
Red Hat Enterprise 5/6
.IP \(bu 2
Scientific Linux 5/6
.IP \(bu 2
SmartOS
.IP \(bu 2
SuSE 11 SP1/11 SP2
.IP \(bu 2
Ubuntu 10.x/11.x/12.x/13.04/13.10
.IP \(bu 2
Elementary OS 0.2
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In the event you do not see your distribution or version available please
review the develop branch on Github as it main contain updates that are
not present in the stable release:
\fI\%https://github.com/saltstack/salt\-bootstrap/tree/develop\fP
.UNINDENT
.UNINDENT
.SS Example Usage
.sp
If you\(aqre looking for the \fIone\-liner\fP to install salt, please scroll to the
bottom and use the instructions for \fI\%Installing via an Insecure One\-Liner\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In every two\-step example, you would be well\-served to examine the downloaded file and examine
it to ensure that it does what you expect.
.UNINDENT
.UNINDENT
.sp
Using \fBcurl\fP to install latest git:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com \-o install_salt.sh
sudo sh install_salt.sh git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using \fBwget\fP to install your distribution\(aqs stable packages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install a specific version from git using \fBwget\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh \-P git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you already have python installed, \fBpython 2.6\fP, then it\(aqs as easy as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-m urllib "https://bootstrap.saltstack.com" > install_salt.sh
sudo sh install_salt.sh git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All python versions should support the following one liner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-c \(aqimport urllib; print urllib.urlopen("https://bootstrap.saltstack.com").read()\(aq > install_salt.sh
sudo sh install_salt.sh git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On a FreeBSD base system you usually don\(aqt have either of the above binaries available. You \fBdo\fP
have \fBfetch\fP available though:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fetch \-o install_salt.sh https://bootstrap.saltstack.com
sudo sh install_salt.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If all you want is to install a \fBsalt\-master\fP using latest git:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-o install_salt.sh.sh \-L https://bootstrap.saltstack.com
sudo sh install_salt.sh.sh \-M \-N git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you want to install a specific release version (based on the git tags):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-o install_salt.sh.sh \-L https://bootstrap.saltstack.com
sudo sh install_salt.sh.sh git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To install a specific branch from a git fork:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-o install_salt.sh.sh \-L https://bootstrap.saltstack.com
sudo sh install_salt.sh.sh \-g https://github.com/myuser/salt.git git mybranch
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Installing via an Insecure One\-Liner
.sp
The following examples illustrate how to install Salt via a one\-liner.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Warning! These methods do not involve a verification step and assume that
the delivered file is trustworthy.
.UNINDENT
.UNINDENT
.SS Examples
.sp
Installing the latest develop branch of Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Any of the example above which use two\-lines can be made to run in a single\-line
configuration with minor modifications.
.SS Example Usage
.sp
The Salt Bootstrap script has a wide variety of options that can be passed as
well as several ways of obtaining the bootstrap script itself.
.sp
For example, using \fBcurl\fP to install your distribution\(aqs stable packages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using \fBwget\fP to install your distribution\(aqs stable packages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O \- https://bootstrap.saltstack.com | sudo sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Installing the latest version available from git with \fBcurl\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install a specific version from git using \fBwget\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget \-O \- https://bootstrap.saltstack.com | sh \-s \-\- \-P git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you already have python installed, \fBpython 2.6\fP, then it\(aqs as easy as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-m urllib "https://bootstrap.saltstack.com" | sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All python versions should support the following one liner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-c \(aqimport urllib; print urllib.urlopen("https://bootstrap.saltstack.com").read()\(aq | \e
sudo sh \-s \-\- git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On a FreeBSD base system you usually don\(aqt have either of the above binaries
available. You \fBdo\fP have \fBfetch\fP available though:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fetch \-o \- https://bootstrap.saltstack.com | sudo sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If all you want is to install a \fBsalt\-master\fP using latest git:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- \-M \-N git develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you want to install a specific release version (based on the git tags):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- git v0.16.4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Downloading the develop branch (from here standard command line options may be
passed):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget https://bootstrap.saltstack.com/develop
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Command Line Options
.sp
Here\(aqs a summary of the command line options:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sh bootstrap\-salt.sh \-h
Usage : bootstrap\-salt.sh [options] <install\-type> <install\-type\-args>
Installation types:
\- stable (default)
\- daily (ubuntu specific)
\- git
Examples:
$ bootstrap\-salt.sh
$ bootstrap\-salt.sh stable
$ bootstrap\-salt.sh daily
$ bootstrap\-salt.sh git
$ bootstrap\-salt.sh git develop
$ bootstrap\-salt.sh git v0.17.0
$ bootstrap\-salt.sh git 8c3fadf15ec183e5ce8c63739850d543617e4357
Options:
\-h Display this message
\-v Display script version
\-n No colours.
\-D Show debug output.
\-c Temporary configuration directory
\-g Salt repository URL. (default: git://github.com/saltstack/salt.git)
\-k Temporary directory holding the minion keys which will pre\-seed
the master.
\-M Also install salt\-master
\-S Also install salt\-syndic
\-N Do not install salt\-minion
\-X Do not start daemons after installation
\-C Only run the configuration function. This option automatically
bypasses any installation.
\-P Allow pip based installations. On some distributions the required salt
packages or its dependencies are not available as a package for that
distribution. Using this flag allows the script to use pip as a last
resort method. NOTE: This only works for functions which actually
implement pip based installations.
\-F Allow copied files to overwrite existing(config, init.d, etc)
\-U If set, fully upgrade the system prior to bootstrapping salt
\-K If set, keep the temporary files in the temporary directories specified
with \-c and \-k.
\-I If set, allow insecure connections while downloading any files. For
example, pass \(aq\-\-no\-check\-certificate\(aq to \(aqwget\(aq or \(aq\-\-insecure\(aq to \(aqcurl\(aq
\-A Pass the salt\-master DNS name or IP. This will be stored under
${BS_SALT_ETC_DIR}/minion.d/99\-master\-address.conf
\-i Pass the salt\-minion id. This will be stored under
${BS_SALT_ETC_DIR}/minion_id
\-L Install the Apache Libcloud package if possible(required for salt\-cloud)
\-p Extra\-package to install while installing salt dependencies. One package
per \-p flag. You\(aqre responsible for providing the proper package name.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Git Fileserver Backend Walkthrough
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This walkthrough assumes basic knowledge of Salt. To get up to speed, check
out the \fBSalt Walkthrough\fP\&.
.UNINDENT
.UNINDENT
.sp
The gitfs backend allows Salt to serve files from git repositories. It can be
enabled by adding \fBgit\fP to the \fBfileserver_backend\fP list, and
configuring one or more repositories in \fBgitfs_remotes\fP\&.
.sp
Branches and tags become Salt fileserver environments.
.SS Installing Dependencies
.sp
Beginning with version 2014.7.0, both \fI\%pygit2\fP and \fI\%Dulwich\fP are supported as
alternatives to \fI\%GitPython\fP\&. The desired provider can be configured using the
\fBgitfs_provider\fP parameter in the master config file.
.sp
If \fBgitfs_provider\fP is not configured, then Salt will prefer
\fI\%pygit2\fP if a suitable version is available, followed by \fI\%GitPython\fP and
\fI\%Dulwich\fP\&.
.SS pygit2
.sp
The minimum supported version of \fI\%pygit2\fP is 0.20.3. Availability for this
version of \fI\%pygit2\fP is still limited, though the SaltStack team is working to
get compatible versions available for as many platforms as possible.
.sp
For the Fedora/EPEL versions which have a new enough version packaged, the
following command would be used to install \fI\%pygit2\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# yum install python\-pygit2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Provided a valid version is packaged for Debian/Ubuntu (which is not currently
the case), the package name would be the same, and the following command would
be used to install it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# apt\-get install python\-pygit2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If \fI\%pygit2\fP is not packaged for the platform on which the Master is running, the
\fI\%pygit2\fP website has installation instructions \fI\%here\fP\&. Keep in mind however that
following these instructions will install libgit2 and \fI\%pygit2\fP without system
packages.
.SS GitPython
.sp
\fI\%GitPython\fP 0.3.0 or newer is required to use GitPython for gitfs. For
RHEL\-based Linux distros, a compatible version is available in EPEL, and can be
easily installed on the master using yum:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# yum install GitPython
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Ubuntu 14.04 LTS and Debian Wheezy (7.x) also have a compatible version packaged:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# apt\-get install python\-git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If your master is running an older version (such as Ubuntu 12.04 LTS or Debian
Squeeze), then you will need to install GitPython using either \fI\%pip\fP or
easy_install (it is recommended to use pip). Version 0.3.2.RC1 is now marked as
the stable release in PyPI, so it should be a simple matter of running \fBpip
install GitPython\fP (or \fBeasy_install GitPython\fP) as root.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Keep in mind that if GitPython has been previously installed on the master
using pip (even if it was subsequently uninstalled), then it may still
exist in the build cache (typically \fB/tmp/pip\-build\-root/GitPython\fP) if
the cache is not cleared after installation. The package in the build cache
will override any requirement specifiers, so if you try upgrading to
version 0.3.2.RC1 by running \fBpip install \(aqGitPython==0.3.2.RC1\(aq\fP then it
will ignore this and simply install the version from the cache directory.
Therefore, it may be necessary to delete the GitPython directory from the
build cache in order to ensure that the specified version is installed.
.UNINDENT
.UNINDENT
.SS Dulwich
.sp
Dulwich 0.9.4 or newer is required to use Dulwich as backend for gitfs.
.sp
Dulwich is available in EPEL, and can be easily installed on the master using
yum:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# yum install python\-dulwich
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For APT\-based distros such as Ubuntu and Debian:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# apt\-get install python\-dulwich
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
If switching to Dulwich from GitPython/pygit2, or switching from
GitPython/pygit2 to Dulwich, it is necessary to clear the gitfs cache to
avoid unpredictable behavior. This is probably a good idea whenever
switching to a new \fBgitfs_provider\fP, but it is less important
when switching between GitPython and pygit2.
.sp
Beginning in version 2015.2.0, the gitfs cache can be easily cleared using
the \fBfileserver.clear_cache\fP
runner.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.clear_cache backend=git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the Master is running an earlier version, then the cache can be cleared
by removing the \fBgitfs\fP and \fBfile_lists/gitfs\fP directories (both paths
relative to the master cache directory, usually
\fB/var/cache/salt/master\fP).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rm \-rf /var/cache/salt/master{,/file_lists}/gitfs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Simple Configuration
.sp
To use the gitfs backend, only two configuration changes are required on the
master:
.INDENT 0.0
.IP 1. 3
Include \fBgit\fP in the \fBfileserver_backend\fP list in the master
config file:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- git
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Specify one or more \fBgit://\fP, \fBhttps://\fP, \fBfile://\fP, or \fBssh://\fP
URLs in \fBgitfs_remotes\fP to configure which repositories to
cache and search for requested files:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- https://github.com/saltstack\-formulas/salt\-formula.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
SSH remotes can also be configured using scp\-like syntax:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- git@github.com:user/repo.git
\- ssh://user@domain.tld/path/to/repo.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Information on how to authenticate to SSH remotes can be found \fI\%here\fP\&.
.sp
\fBNOTE:\fP
.INDENT 3.0
.INDENT 3.5
Dulwich does not recognize \fBssh://\fP URLs, \fBgit+ssh://\fP must be used
instead. Salt version 2015.2.0 and later will automatically add the
\fBgit+\fP to the beginning of these URLs before fetching, but earlier
Salt versions will fail to fetch unless the URL is specified using
\fBgit+ssh://\fP\&.
.UNINDENT
.UNINDENT
.IP 3. 3
Restart the master to load the new configuration.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In a master/minion setup, files from a gitfs remote are cached once by the
master, so minions do not need direct access to the git repository.
.UNINDENT
.UNINDENT
.SS Multiple Remotes
.sp
The \fBgitfs_remotes\fP option accepts an ordered list of git remotes to
cache and search, in listed order, for requested files.
.sp
A simple scenario illustrates this cascading lookup behavior:
.sp
If the \fBgitfs_remotes\fP option specifies three remotes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- git://github.com/example/first.git
\- https://github.com/example/second.git
\- file:///root/third
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And each repository contains some files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
first.git:
top.sls
edit/vim.sls
edit/vimrc
nginx/init.sls
second.git:
edit/dev_vimrc
haproxy/init.sls
third:
haproxy/haproxy.conf
edit/dev_vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt will attempt to lookup the requested file from each gitfs remote
repository in the order in which they are defined in the configuration. The
\fBgit://github.com/example/first.git\fP remote will be searched first.
If the requested file is found, then it is served and no further searching
is executed. For example:
.INDENT 0.0
.IP \(bu 2
A request for the file \fBsalt://haproxy/init.sls\fP will be served from
the \fBhttps://github.com/example/second.git\fP git repo.
.IP \(bu 2
A request for the file \fBsalt://haproxy/haproxy.conf\fP will be served from the
\fBfile:///root/third\fP repo.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This example is purposefully contrived to illustrate the behavior of the
gitfs backend. This example should not be read as a recommended way to lay
out files and git repos.
.sp
The \fBfile://\fP prefix denotes a git repository in a local directory.
However, it will still use the given \fBfile://\fP URL as a remote,
rather than copying the git repo to the salt cache. This means that any
refs you want accessible must exist as \fIlocal\fP refs in the specified repo.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Salt versions prior to 2014.1.0 are not tolerant of changing the
order of remotes or modifying the URI of existing remotes. In those
versions, when modifying remotes it is a good idea to remove the gitfs
cache directory (\fB/var/cache/salt/master/gitfs\fP) before restarting the
salt\-master service.
.UNINDENT
.UNINDENT
.SS Per\-remote Configuration Parameters
.sp
New in version 2014.7.0.
.sp
The following master config parameters are global (that is, they apply to all
configured gitfs remotes):
.INDENT 0.0
.IP \(bu 2
\fBgitfs_base\fP
.IP \(bu 2
\fBgitfs_root\fP
.IP \(bu 2
\fBgitfs_mountpoint\fP (new in 2014.7.0)
.IP \(bu 2
\fBgitfs_user\fP (\fBpygit2 only\fP, new in 2014.7.0)
.IP \(bu 2
\fBgitfs_password\fP (\fBpygit2 only\fP, new in 2014.7.0)
.IP \(bu 2
\fBgitfs_insecure_auth\fP (\fBpygit2 only\fP, new in 2014.7.0)
.IP \(bu 2
\fBgitfs_pubkey\fP (\fBpygit2 only\fP, new in 2014.7.0)
.IP \(bu 2
\fBgitfs_privkey\fP (\fBpygit2 only\fP, new in 2014.7.0)
.IP \(bu 2
\fBgitfs_passphrase\fP (\fBpygit2 only\fP, new in 2014.7.0)
.UNINDENT
.sp
These parameters can now be overridden on a per\-remote basis. This allows for a
tremendous amount of customization. Here\(aqs some example usage:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_provider: pygit2
gitfs_base: develop
gitfs_remotes:
\- https://foo.com/foo.git
\- https://foo.com/bar.git:
\- root: salt
\- mountpoint: salt://foo/bar/baz
\- base: salt\-base
\- http://foo.com/baz.git:
\- root: salt/states
\- user: joe
\- password: mysupersecretpassword
\- insecure_auth: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
There are two important distinctions which should be noted for per\-remote
configuration:
.INDENT 0.0
.IP 1. 3
The URL of a remote which has per\-remote configuration must be suffixed
with a colon.
.IP 2. 3
Per\-remote configuration parameters are named like the global versions,
with the \fBgitfs_\fP removed from the beginning.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In the example configuration above, the following is true:
.INDENT 0.0
.IP 1. 3
The first and third gitfs remotes will use the \fBdevelop\fP branch/tag as the
\fBbase\fP environment, while the second one will use the \fBsalt\-base\fP
branch/tag as the \fBbase\fP environment.
.IP 2. 3
The first remote will serve all files in the repository. The second
remote will only serve files from the \fBsalt\fP directory (and its
subdirectories), while the third remote will only serve files from the
\fBsalt/states\fP directory (and its subdirectories).
.IP 3. 3
The files from the second remote will be located under
\fBsalt://foo/bar/baz\fP, while the files from the first and third remotes
will be located under the root of the Salt fileserver namespace
(\fBsalt://\fP).
.IP 4. 3
The third remote overrides the default behavior of \fI\%not authenticating to
insecure (non\-HTTPS) remotes\fP\&.
.UNINDENT
.SS Serving from a Subdirectory
.sp
The \fBgitfs_root\fP parameter allows files to be served from a
subdirectory within the repository. This allows for only part of a repository
to be exposed to the Salt fileserver.
.sp
Assume the below layout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.gitignore
README.txt
foo/
foo/bar/
foo/bar/one.txt
foo/bar/two.txt
foo/bar/three.txt
foo/baz/
foo/baz/top.sls
foo/baz/edit/vim.sls
foo/baz/edit/vimrc
foo/baz/nginx/init.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The below configuration would serve only the files under \fBfoo/baz\fP, ignoring
the other files in the repository:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- git://mydomain.com/stuff.git
gitfs_root: foo/baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The root can also be configured on a \fI\%per\-remote basis\fP\&.
.SS Mountpoints
.sp
New in version 2014.7.0.
.sp
The \fBgitfs_mountpoint\fP parameter will prepend the specified path
to the files served from gitfs. This allows an existing repository to be used,
rather than needing to reorganize a repository or design it around the layout
of the Salt fileserver.
.sp
Before the addition of this feature, if a file being served up via gitfs was
deeply nested within the root directory (for example,
\fBsalt://webapps/foo/files/foo.conf\fP, it would be necessary to ensure that the
file was properly located in the remote repository, and that all of the the
parent directories were present (for example, the directories
\fBwebapps/foo/files/\fP would need to exist at the root of the repository).
.sp
The below example would allow for a file \fBfoo.conf\fP at the root of the
repository to be served up from the Salt fileserver path
\fBsalt://webapps/foo/files/foo.conf\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- https://mydomain.com/stuff.git
gitfs_mountpoint: salt://webapps/foo/files
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Mountpoints can also be configured on a \fI\%per\-remote basis\fP\&.
.SS Using gitfs Alongside Other Backends
.sp
Sometimes it may make sense to use multiple backends; for instance, if \fBsls\fP
files are stored in git but larger files are stored directly on the master.
.sp
The cascading lookup logic used for multiple remotes is also used with
multiple backends. If the \fBfileserver_backend\fP option contains
multiple backends:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- roots
\- git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then the \fBroots\fP backend (the default backend of files in \fB/srv/salt\fP) will
be searched first for the requested file; then, if it is not found on the
master, each configured git remote will be searched.
.SS Branches, Environments and Top Files
.sp
When using the gitfs backend, branches and tags will be mapped to environments
using the branch/tag name as an identifier.
.sp
There is one exception to this rule: the \fBmaster\fP branch is implicitly mapped
to the \fBbase\fP environment.
.sp
So, for a typical \fBbase\fP, \fBqa\fP, \fBdev\fP setup, the following branches could
be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master
qa
dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBtop.sls\fP files from different branches will be merged into one at runtime.
Since this can lead to overly complex configurations, the recommended setup is
to have the \fBtop.sls\fP file only in the master branch and use
environment\-specific branches for state definitions.
.sp
To map a branch other than \fBmaster\fP as the \fBbase\fP environment, use the
\fBgitfs_base\fP parameter.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_base: salt\-base
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The base can also be configured on a \fI\%per\-remote basis\fP\&.
.SS Environment Whitelist/Blacklist
.sp
New in version 2014.7.0.
.sp
The \fBgitfs_env_whitelist\fP and \fBgitfs_env_blacklist\fP
parameters allow for greater control over which branches/tags are exposed as
fileserver environments. Exact matches, globs, and regular expressions are
supported, and are evaluated in that order. If using a regular expression,
\fB^\fP and \fB$\fP must be omitted, and the expression must match the entire
branch/tag.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_env_whitelist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBv1.*\fP, in this example, will match as both a glob and a regular
expression (though it will have been matched as a glob, since globs are
evaluated before regular expressions).
.UNINDENT
.UNINDENT
.sp
The behavior of the blacklist/whitelist will differ depending on which
combination of the two options is used:
.INDENT 0.0
.IP \(bu 2
If only \fBgitfs_env_whitelist\fP is used, then \fBonly\fP branches/tags
which match the whitelist will be available as environments
.IP \(bu 2
If only \fBgitfs_env_blacklist\fP is used, then the branches/tags
which match the blacklist will \fBnot\fP be available as environments
.IP \(bu 2
If both are used, then the branches/tags which match the whitelist, but do
\fBnot\fP match the blacklist, will be available as environments.
.UNINDENT
.SS Authentication
.SS pygit2
.sp
New in version 2014.7.0.
.sp
Both HTTPS and SSH authentication are supported as of version 0.20.3, which is
the earliest version of \fI\%pygit2\fP supported by Salt for gitfs.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The examples below make use of per\-remote configuration parameters, a
feature new to Salt 2014.7.0. More information on these can be found
\fI\%here\fP\&.
.UNINDENT
.UNINDENT
.SS HTTPS
.sp
For HTTPS repositories which require authentication, the username and password
can be provided like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- https://domain.tld/myrepo.git:
\- user: git
\- password: mypassword
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the repository is served over HTTP instead of HTTPS, then Salt will by
default refuse to authenticate to it. This behavior can be overridden by adding
an \fBinsecure_auth\fP parameter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- http://domain.tld/insecure_repo.git:
\- user: git
\- password: mypassword
\- insecure_auth: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS SSH
.sp
SSH repositories can be configured using the \fBssh://\fP protocol designation,
or using scp\-like syntax. So, the following two configurations are equivalent:
.INDENT 0.0
.IP \(bu 2
\fBssh://git@github.com/user/repo.git\fP
.IP \(bu 2
\fBgit@github.com:user/repo.git\fP
.UNINDENT
.sp
Both \fBgitfs_pubkey\fP and \fBgitfs_privkey\fP (or their
\fI\%per\-remote counterparts\fP) must be configured in
order to authenticate to SSH\-based repos. If the private key is protected with
a passphrase, it can be configured using \fBgitfs_passphrase\fP (or
simply \fBpassphrase\fP if being configured \fI\%per\-remote\fP). For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- git@github.com:user/repo.git:
\- pubkey: /root/.ssh/id_rsa.pub
\- privkey: /root/.ssh/id_rsa
\- passphrase: myawesomepassphrase
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, the SSH host key must be \fI\%added to the known_hosts file\fP\&.
.SS GitPython
.sp
With \fI\%GitPython\fP, only passphrase\-less SSH public key authentication is
supported. \fBThe auth parameters (pubkey, privkey, etc.) shown in the pygit2
authentication examples above do not work with GitPython.\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- ssh://git@github.com/example/salt\-states.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since \fI\%GitPython\fP wraps the git CLI, the private key must be located in
\fB~/.ssh/id_rsa\fP for the user under which the Master is running, and should
have permissions of \fB0600\fP\&. Also, in the absence of a user in the repo URL,
\fI\%GitPython\fP will (just as SSH does) attempt to login as the current user (in
other words, the user under which the Master is running, usually \fBroot\fP).
.sp
If a key needs to be used, then \fB~/.ssh/config\fP can be configured to use
the desired key. Information on how to do this can be found by viewing the
manpage for \fBssh_config\fP\&. Here\(aqs an example entry which can be added to the
\fB~/.ssh/config\fP to use an alternate key for gitfs:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Host github.com
IdentityFile /root/.ssh/id_rsa_gitfs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBHost\fP parameter should be a hostname (or hostname glob) that matches the
domain name of the git repository.
.sp
It is also necessary to \fI\%add the SSH host key to the known_hosts file\fP\&. The exception to this would be if strict host key
checking is disabled, which can be done by adding \fBStrictHostKeyChecking no\fP
to the entry in \fB~/.ssh/config\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Host github.com
IdentityFile /root/.ssh/id_rsa_gitfs
StrictHostKeyChecking no
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, this is generally regarded as insecure, and is not recommended.
.SS Adding the SSH Host Key to the known_hosts File
.sp
To use SSH authentication, it is necessary to have the remote repository\(aqs SSH
host key in the \fB~/.ssh/known_hosts\fP file. If the master is also a minion,
this can be done using the \fBssh.set_known_host\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt mymaster ssh.set_known_host user=root hostname=github.com
mymaster:
\-\-\-\-\-\-\-\-\-\-
new:
\-\-\-\-\-\-\-\-\-\-
enc:
ssh\-rsa
fingerprint:
16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48
hostname:
|1|OiefWWqOD4kwO3BhoIGa0loR5AA=|BIXVtmcTbPER+68HvXmceodDcfI=
key:
AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==
old:
None
status:
updated
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If not, then the easiest way to add the key is to su to the user (usually
\fBroot\fP) under which the salt\-master runs and attempt to login to the
server via SSH:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ su
Password:
# ssh github.com
The authenticity of host \(aqgithub.com (192.30.252.128)\(aq can\(aqt be established.
RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added \(aqgithub.com,192.30.252.128\(aq (RSA) to the list of known hosts.
Permission denied (publickey).
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It doesn\(aqt matter if the login was successful, as answering \fByes\fP will write
the fingerprint to the known_hosts file.
.SS Verifying the Fingerprint
.sp
To verify that the correct fingerprint was added, it is a good idea to look it
up. One way to do this is to use nmap:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ nmap github.com \-\-script ssh\-hostkey
Starting Nmap 5.51 ( http://nmap.org ) at 2014\-08\-18 17:47 CDT
Nmap scan report for github.com (192.30.252.129)
Host is up (0.17s latency).
Not shown: 996 filtered ports
PORT STATE SERVICE
22/tcp open ssh
| ssh\-hostkey: 1024 ad:1c:08:a4:40:e3:6f:9c:f5:66:26:5d:4b:33:5d:8c (DSA)
|_2048 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 (RSA)
80/tcp open http
443/tcp open https
9418/tcp open git
Nmap done: 1 IP address (1 host up) scanned in 28.78 seconds
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Another way is to check one\(aqs own known_hosts file, using this one\-liner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ ssh\-keygen \-l \-f /dev/stdin <<<\(gassh\-keyscan \-t rsa github.com 2>/dev/null\(ga | awk \(aq{print $2}\(aq
16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Refreshing gitfs Upon Push
.sp
By default, Salt updates the remote fileserver backends every 60 seconds.
However, if it is desirable to refresh quicker than that, the \fIReactor
System\fP can be used to signal the master to update the fileserver on
each push, provided that the git server is also a Salt minion. There are three
steps to this process:
.INDENT 0.0
.IP 1. 3
On the master, create a file \fB/srv/reactor/update_fileserver.sls\fP, with
the following contents:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
update_fileserver:
runner.fileserver.update
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Add the following reactor configuration to the master config file:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
reactor:
\- \(aqsalt/fileserver/gitfs/update\(aq:
\- /srv/reactor/update_fileserver.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
On the git server, add a \fI\%post\-receive hook\fP with the following contents:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
#!/usr/bin/env sh
salt\-call event.fire_master update salt/fileserver/gitfs/update
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fBupdate\fP argument right after \fBevent.fire_master\fP in this example can really be anything, as it
represents the data being passed in the event, and the passed data is ignored
by this reactor.
.sp
Similarly, the tag name \fBsalt/fileserver/gitfs/update\fP can be replaced by
anything, so long as the usage is consistent.
.SS Using Git as an External Pillar Source
.sp
Git repositories can also be used to provide \fBPillar\fP data, using the \fBExternal Pillar\fP system. Note that this is different
from gitfs, and is not yet at feature parity with it.
.sp
To define a git external pillar, add a section like the following to the salt
master config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- git: <branch> <repo> [root=<gitroot>]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: The optional \fBroot\fP parameter was added
.sp
The \fB<branch>\fP param is the branch containing the pillar SLS tree. The
\fB<repo>\fP param is the URI for the repository. To add the
\fBmaster\fP branch of the specified repo as an external pillar source:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- git: master https://domain.com/pillar.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use the \fBroot\fP parameter to use pillars from a subdirectory of a git
repository:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- git: master https://domain.com/pillar.git root=subdirectory
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
More information on the git external pillar can be found in the
\fBsalt.pillar.get_pillar docs\fP\&.
.SS Why aren\(aqt my custom modules/states/etc. syncing to my Minions?
.sp
In versions 0.16.3 and older, when using the \fBgit fileserver backend\fP, certain versions of GitPython may generate errors
when fetching, which Salt fails to catch. While not fatal to the fetch process,
these interrupt the fileserver update that takes place before custom types are
synced, and thus interrupt the sync itself. Try disabling the git fileserver
backend in the master config, restarting the master, and attempting the sync
again.
.sp
This issue is worked around in Salt 0.16.4 and newer.
.SS The MacOS X (Maverick) Developer Step By Step Guide To Salt Installation
.sp
This document provides a step\-by\-step guide to installing a Salt cluster
consisting of one master, and one minion running on a local VM hosted on Mac OS X.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This guide is aimed at developers who wish to run Salt in a virtual machine.
The official (Linux) walkthrough can be found
\fI\%here\fP\&.
.UNINDENT
.UNINDENT
.SS The 5 Cent Salt Intro
.sp
Since you\(aqre here you\(aqve probably already heard about Salt, so you already
know Salt lets you configure and run commands on hordes of servers easily.
Here\(aqs a brief overview of a Salt cluster:
.INDENT 0.0
.IP \(bu 2
Salt works by having a "master" server sending commands to one or multiple
"minion" servers [1]\&. The master server is the "command center". It is
going to be the place where you store your configuration files, aka: "which
server is the db, which is the web server, and what libraries and software
they should have installed". The minions receive orders from the master.
Minions are the servers actually performing work for your business.
.IP \(bu 2
Salt has two types of configuration files:
.sp
1. the "salt communication channels" or "meta" or "config" configuration
files (not official names): one for the master (usually is /etc/salt/master
, \fBon the master server\fP), and one for minions (default is
/etc/salt/minion or /etc/salt/minion.conf, \fBon the minion servers\fP). Those
files are used to determine things like the Salt Master IP, port, Salt
folder locations, etc.. If these are configured incorrectly, your minions
will probably be unable to receive orders from the master, or the master
will not know which software a given minion should install.
.sp
2. the "business" or "service" configuration files (once again, not an
official name): these are configuration files, ending with ".sls" extension,
that describe which software should run on which server, along with
particular configuration properties for the software that is being
installed. These files should be created in the /srv/salt folder by default,
but their location can be changed using ... /etc/salt/master configuration file!
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This tutorial contains a third important configuration file, not to
be confused with the previous two: the virtual machine provisioning
configuration file. This in itself is not specifically tied to Salt, but
it also contains some Salt configuration. More on that in step 3. Also
note that all configuration files are YAML files. So indentation matters.
.UNINDENT
.UNINDENT
.IP [1] 5
Salt also works with "masterless" configuration where a minion is
autonomous (in which case salt can be seen as a local configuration tool),
or in "multiple master" configuration. See the documentation for more on
that.
.SS Before Digging In, The Architecture Of The Salt Cluster
.SS Salt Master
.sp
The "Salt master" server is going to be the Mac OS machine, directly. Commands
will be run from a terminal app, so Salt will need to be installed on the Mac.
This is going to be more convenient for toying around with configuration files.
.SS Salt Minion
.sp
We\(aqll only have one "Salt minion" server. It is going to be running on a
Virtual Machine running on the Mac, using VirtualBox. It will run an Ubuntu
distribution.
.SS Step 1 \- Configuring The Salt Master On Your Mac
.sp
\fI\%official documentation\fP
.sp
Because Salt has a lot of dependencies that are not built in Mac OS X, we will
use Homebrew to install Salt. Homebrew is a package manager for Mac, it\(aqs
great, use it (for this tutorial at least!). Some people spend a lot of time
installing libs by hand to better understand dependencies, and then realize how
useful a package manager is once they\(aqre configuring a brand new machine and
have to do it all over again. It also lets you \fIuninstall\fP things easily.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Brew is a Ruby program (Ruby is installed by default with your Mac). Brew
downloads, compiles and links software. The linking phase is when compiled
software is deployed on your machine. It may conflict with manually
installed software, especially in the /usr/local directory. It\(aqs ok,
remove the manually installed version then refresh the link by typing
\fBbrew link \(aqpackageName\(aq\fP\&. Brew has a \fBbrew doctor\fP command that can
help you troubleshoot. It\(aqs a great command, use it often. Brew requires
xcode command line tools. When you run brew the first time it asks you to
install them if they\(aqre not already on your system. Brew installs
software in /usr/local/bin (system bins are in /usr/bin). In order to use
those bins you need your $PATH to search there first. Brew tells you if
your $PATH needs to be fixed.
.UNINDENT
.UNINDENT
.sp
\fBTIP:\fP
.INDENT 0.0
.INDENT 3.5
Use the keyboard shortcut \fBcmd + shift + period\fP in the "open" Mac OS X
dialog box to display hidden files and folders, such as .profile.
.UNINDENT
.UNINDENT
.SS Install Homebrew
.sp
Install Homebrew here \fI\%http://brew.sh/\fP
Or just type
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ruby \-e "$(curl \-fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now type the following commands in your terminal (you may want to type \fBbrew
doctor\fP after each to make sure everything\(aqs fine):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
brew install python
brew install swig
brew install zmq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
zmq is ZeroMQ. It\(aqs a fantastic library used for server to server network
communication and is at the core of Salt efficiency.
.UNINDENT
.UNINDENT
.SS Install Salt
.sp
You should now have everything ready to launch this command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
There should be no need for \fBsudo pip install salt\fP\&. Brew installed
Python for your user, so you should have all the access. In case you
would like to check, type \fBwhich python\fP to ensure that it\(aqs
/usr/local/bin/python, and \fBwhich pip\fP which should be
/usr/local/bin/pip.
.UNINDENT
.UNINDENT
.sp
Now type \fBpython\fP in a terminal then, \fBimport salt\fP\&. There should be no
errors. Now exit the Python terminal using \fBexit()\fP\&.
.SS Create The Master Configuration
.sp
If the default /etc/salt/master configuration file was not created,
copy\-paste it from here:
\fI\%http://docs.saltstack.com/ref/configuration/examples.html#configuration\-examples\-master\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fB/etc/salt/master\fP is a file, not a folder.
.UNINDENT
.UNINDENT
.sp
Salt Master configuration changes. The Salt master needs a few customization
to be able to run on Mac OS X:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo launchctl limit maxfiles 4096 8192
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the /etc/salt/master file, change max_open_files to 8192 (or just add the
line: \fBmax_open_files: 8192\fP (no quote) if it doesn\(aqt already exists).
.sp
You should now be able to launch the Salt master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo salt\-master \-\-log\-level=all
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There should be no errors when running the above command.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This command is supposed to be a daemon, but for toying around, we\(aqll keep
it running on a terminal to monitor the activity.
.UNINDENT
.UNINDENT
.sp
Now that the master is set, let\(aqs configure a minion on a VM.
.SS Step 2 \- Configuring The Minion VM
.sp
The Salt minion is going to run on a Virtual Machine. There are a lot of
software options that let you run virtual machines on a mac, But for this
tutorial we\(aqre going to use VirtualBox. In addition to virtualBox, we will use
Vagrant, which allows you to create the base VM configuration.
.sp
Vagrant lets you build ready to use VM images, starting from an OS image and
customizing it using "provisioners". In our case, we\(aqll use it to:
.INDENT 0.0
.IP \(bu 2
Download the base Ubuntu image
.IP \(bu 2
Install salt on that Ubuntu image (Salt is going to be the "provisioner"
for the VM).
.IP \(bu 2
Launch the VM
.IP \(bu 2
SSH into the VM to debug
.IP \(bu 2
Stop the VM once you\(aqre done.
.UNINDENT
.SS Install VirtualBox
.sp
Go get it here: \fI\%https://www.virtualBox.org/wiki/Downloads\fP (click on VirtualBox
for OS X hosts => x86/amd64)
.SS Install Vagrant
.sp
Go get it here: \fI\%http://downloads.vagrantup.com/\fP and choose the latest version
(1.3.5 at time of writing), then the .dmg file. Double\-click to install it.
Make sure the \fBvagrant\fP command is found when run in the terminal. Type
\fBvagrant\fP\&. It should display a list of commands.
.SS Create The Minion VM Folder
.sp
Create a folder in which you will store your minion\(aqs VM. In this tutorial,
it\(aqs going to be a minion folder in the $home directory.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd $home
mkdir minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Initialize Vagrant
.sp
From the minion folder, type
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vagrant init
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This command creates a default Vagrantfile configuration file. This
configuration file will be used to pass configuration parameters to the Salt
provisioner in Step 3.
.SS Import Precise64 Ubuntu Box
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vagrant box add precise64 http://files.vagrantup.com/precise64.box
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This box is added at the global Vagrant level. You only need to do it
once as each VM will use this same file.
.UNINDENT
.UNINDENT
.SS Modify the Vagrantfile
.sp
Modify ./minion/Vagrantfile to use th precise64 box. Change the \fBconfig.vm.box\fP
line to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
config.vm.box = "precise64"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Uncomment the line creating a host\-only IP. This is the ip of your minion
(you can change it to something else if that IP is already in use):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
config.vm.network :private_network, ip: "192.168.33.10"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
At this point you should have a VM that can run, although there won\(aqt be much
in it. Let\(aqs check that.
.SS Checking The VM
.sp
From the $home/minion folder type:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vagrant up
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A log showing the VM booting should be present. Once it\(aqs done you\(aqll be back
to the terminal:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ping 192.168.33.10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The VM should respond to your ping request.
.sp
Now log into the VM in ssh using Vagrant again:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vagrant ssh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You should see the shell prompt change to something similar to
\fBvagrant@precise64:~$\fP meaning you\(aqre inside the VM. From there, enter the
following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ping 10.0.2.2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
That ip is the ip of your VM host (the Mac OS X OS). The number is a
VirtualBox default and is displayed in the log after the Vagrant ssh
command. We\(aqll use that IP to tell the minion where the Salt master is.
Once you\(aqre done, end the ssh session by typing \fBexit\fP\&.
.UNINDENT
.UNINDENT
.sp
It\(aqs now time to connect the VM to the salt master
.SS Step 3 \- Connecting Master and Minion
.SS Creating The Minion Configuration File
.sp
Create the \fB/etc/salt/minion\fP file. In that file, put the
following lines, giving the ID for this minion, and the IP of the master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master: 10.0.2.2
id: \(aqminion1\(aq
file_client: remote
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Minions authenticate with the master using keys. Keys are generated
automatically if you don\(aqt provide one and can accept them later on. However,
this requires accepting the minion key every time the minion is destroyed or
created (which could be quite often). A better way is to create those keys in
advance, feed them to the minion, and authorize them once.
.SS Preseed minion keys
.sp
From the minion folder on your Mac run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo salt\-key \-\-gen\-keys=minion1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This should create two files: minion1.pem, and minion1.pub.
Since those files have been created using sudo, but will be used by vagrant,
you need to change ownership:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo chown youruser:yourgroup minion1.pem
sudo chown youruser:yourgroup minion1.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then copy the .pub file into the list of accepted minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo cp minion1.pub /etc/salt/pki/master/minions/minion1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Modify Vagrantfile to Use Salt Provisioner
.sp
Let\(aqs now modify the Vagrantfile used to provision the Salt VM. Add the
following section in the Vagrantfile (note: it should be at the same
indentation level as the other properties):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-vagrant config
config.vm.provision :salt do |salt|
salt.run_highstate = true
salt.minion_config = "/etc/salt/minion"
salt.minion_key = "./minion1.pem"
salt.minion_pub = "./minion1.pub"
end
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now destroy the vm and recreate it from the /minion folder:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vagrant destroy
vagrant up
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If everything is fine you should see the following message:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
"Bootstrapping Salt... (this may take a while)
Salt successfully configured and installed!"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Checking Master\-Minion Communication
.sp
To make sure the master and minion are talking to each other, enter the
following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You should see your minion answering the ping. It\(aqs now time to do some
configuration.
.SS Step 4 \- Configure Services to Install On the Minion
.sp
In this step we\(aqll use the Salt master to instruct our minion to install
Nginx.
.SS Checking the system\(aqs original state
.sp
First, make sure that an HTTP server is not installed on our minion.
When opening a browser directed at \fBhttp://192.168.33.10/\fP You should get an
error saying the site cannot be reached.
.SS Initialize the top.sls file
.sp
System configuration is done in the /srv/salt/top.sls file (and
subfiles/folders), and then applied by running the \fBstate.highstate\fP
command to have the Salt master give orders so minions will update their
instructions and run the associated commands.
.sp
First Create an empty file on your Salt master (Mac OS X machine):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
touch /srv/salt/top.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When the file is empty, or if no configuration is found for our minion
an error is reported:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo salt \(aqminion1\(aq state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Should return an error stating:
"No Top file or external nodes data matches found".
.SS Create The Nginx Configuration
.sp
Now is finally the time to enter the real meat of our server\(aqs configuration.
For this tutorial our minion will be treated as a web server that needs to
have Nginx installed.
.sp
Insert the following lines into the \fB/srv/salt/top.sls\fP file (which should
current be empty).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqminion1\(aq:
\- bin.nginx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now create a \fB/srv/salt/bin/nginx.sls\fP file containing the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nginx:
pkg.installed:
\- name: nginx
service.running:
\- enable: True
\- reload: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Check Minion State
.sp
Finally run the state.highstate command again:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo salt \(aqminion1\(aq state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You should see a log showing that the Nginx package has been installed
and the service configured. To prove it, open your browser and navigate to
\fI\%http://192.168.33.10/\fP, you should see the standard Nginx welcome page.
.sp
Congratulations!
.SS Where To Go From Here
.sp
A full description of configuration management within Salt (sls files among
other things) is available here:
\fI\%http://docs.saltstack.com/index.html#configuration\-management\fP
.SS Writing Salt Tests
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
THIS TUTORIAL IS A WORK IN PROGRESS
.UNINDENT
.UNINDENT
.sp
Salt comes with a powerful integration and unit test suite. The test suite
allows for the fully automated run of integration and/or unit tests from a
single interface. The integration tests are surprisingly easy to write and can
be written to be either destructive or non\-destructive.
.SS Getting Set Up For Tests
.sp
To walk through adding an integration test, start by getting the latest
development code and the test system from GitHub:
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The develop branch often has failing tests and should always be considered
a staging area. For a checkout that tests should be running perfectly on,
please check out a specific release tag (such as v2014.1.4).
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone git@github.com:saltstack/salt.git
pip install git+https://github.com/saltstack/salt\-testing.git#egg=SaltTesting
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now that a fresh checkout is available run the test suite
.SS Destructive vs Non\-destructive
.sp
Since Salt is used to change the settings and behavior of systems, often, the
best approach to run tests is to make actual changes to an underlying system.
This is where the concept of destructive integration tests comes into play.
Tests can be written to alter the system they are running on. This capability
is what fills in the gap needed to properly test aspects of system management
like package installation.
.sp
To write a destructive test import and use the \fIdestructiveTest\fP decorator for
the test method:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import integration
from salttesting.helpers import destructiveTest
class PkgTest(integration.ModuleCase):
@destructiveTest
def test_pkg_install(self):
ret = self.run_function(\(aqpkg.install\(aq, name=\(aqfinch\(aq)
self.assertSaltTrueReturn(ret)
ret = self.run_function(\(aqpkg.purge\(aq, name=\(aqfinch\(aq)
self.assertSaltTrueReturn(ret)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Automated Test Runs
.sp
SaltStack maintains a Jenkins server which can be viewed at
\fI\%http://jenkins.saltstack.com\fP\&. The tests executed from this Jenkins server
create fresh virtual machines for each test run, then execute the destructive
tests on the new clean virtual machine. This allows for the execution of tests
across supported platforms.
.SS Salt Virt
.SS Salt as a Cloud Controller
.sp
In Salt 0.14.0, an advanced cloud control system were introduced, allow
private cloud vms to be managed directly with Salt. This system is generally
referred to as \fBSalt Virt\fP\&.
.sp
The Salt Virt system already exists and is installed within Salt itself, this
means that beside setting up Salt, no additional salt code needs to be
deployed.
.sp
The main goal of Salt Virt is to facilitate a very fast and simple cloud. The
cloud that can scale and fully featured. Salt Virt comes with the
ability to set up and manage complex virtual machine networking, powerful
image and disk management, as well as virtual machine migration with and without
shared storage.
.sp
This means that Salt Virt can be used to create a cloud from a blade center
and a SAN, but can also create a cloud out of a swarm of Linux Desktops
without a single shared storage system. Salt Virt can make clouds from
truly commodity hardware, but can also stand up the power of specialized
hardware as well.
.SS Setting up Hypervisors
.sp
The first step to set up the hypervisors involves getting the correct software
installed and setting up the hypervisor network interfaces.
.SS Installing Hypervisor Software
.sp
Salt Virt is made to be hypervisor agnostic but currently the only fully
implemented hypervisor is KVM via libvirt.
.sp
The required software for a hypervisor is libvirt and kvm. For advanced
features install libguestfs or qemu\-nbd.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Libguestfs and qemu\-nbd allow for virtual machine images to be mounted
before startup and get pre\-seeded with configurations and a salt minion
.UNINDENT
.UNINDENT
.sp
This sls will set up the needed software for a hypervisor, and run the routines
to set up the libvirt pki keys.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Package names and setup used is Red Hat specific, different package names
will be required for different platforms
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
libvirt:
pkg.installed: []
file.managed:
\- name: /etc/sysconfig/libvirtd
\- contents: \(aqLIBVIRTD_ARGS="\-\-listen"\(aq
\- require:
\- pkg: libvirt
libvirt.keys:
\- require:
\- pkg: libvirt
service.running:
\- name: libvirtd
\- require:
\- pkg: libvirt
\- network: br0
\- libvirt: libvirt
\- watch:
\- file: libvirt
libvirt\-python:
pkg.installed: []
libguestfs:
pkg.installed:
\- pkgs:
\- libguestfs
\- libguestfs\-tools
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Hypervisor Network Setup
.sp
The hypervisors will need to be running a network bridge to serve up network
devices for virtual machines, this formula will set up a standard bridge on
a hypervisor connecting the bridge to eth0:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
eth0:
network.managed:
\- enabled: True
\- type: eth
\- bridge: br0
br0:
network.managed:
\- enabled: True
\- type: bridge
\- proto: dhcp
\- require:
\- network: eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Virtual Machine Network Setup
.sp
Salt Virt comes with a system to model the network interfaces used by the
deployed virtual machines; by default a single interface is created for the
deployed virtual machine and is bridged to \fBbr0\fP\&. To get going with the
default networking setup, ensure that the bridge interface named \fBbr0\fP exists
on the hypervisor and is bridged to an active network device.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
To use more advanced networking in Salt Virt, read the \fISalt Virt
Networking\fP document:
.sp
\fBSalt Virt Networking\fP
.UNINDENT
.UNINDENT
.SS Libvirt State
.sp
One of the challenges of deploying a libvirt based cloud is the distribution
of libvirt certificates. These certificates allow for virtual machine
migration. Salt comes with a system used to auto deploy these certificates.
Salt manages the signing authority key and generates keys for libvirt clients
on the master, signs them with the certificate authority and uses pillar to
distribute them. This is managed via the \fBlibvirt\fP state. Simply execute this
formula on the minion to ensure that the certificate is in place and up to
date:
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The above formula includes the calls needed to set up libvirt keys.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
libvirt_keys:
libvirt.keys
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Virtual Machine Images Ready
.sp
Salt Virt, requires that virtual machine images be provided as these are not
generated on the fly. Generating these virtual machine images differs greatly
based on the underlying platform.
.sp
Virtual machine images can be manually created using KVM and running through
the installer, but this process is not recommended since it is very manual and
prone to errors.
.sp
Virtual Machine generation applications are available for many platforms:
.INDENT 0.0
.TP
.B vm\-builder:
\fI\%https://wiki.debian.org/VMBuilder\fP
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%vmbuilder\-formula\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Once virtual machine images are available, the easiest way to make them
available to Salt Virt is to place them in the Salt file server. Just copy an
image into \fB/srv/salt\fP and it can now be used by Salt Virt.
.sp
For purposes of this demo, the file name \fBcentos.img\fP will be used.
.SS Existing Virtual Machine Images
.sp
Many existing Linux distributions distribute virtual machine images which
can be used with Salt Virt. Please be advised that NONE OF THESE IMAGES ARE
SUPPORTED BY SALTSTACK.
.SS CentOS
.sp
These images have been prepared for OpenNebula but should work without issue with
Salt Virt, only the raw qcow image file is needed:
\fI\%http://wiki.centos.org/Cloud/OpenNebula\fP
.SS Fedora Linux
.sp
Images for Fedora Linux can be found here:
\fI\%http://fedoraproject.org/en/get\-fedora#clouds\fP
.SS Ubuntu Linux
.sp
Images for Ubuntu Linux can be found here:
\fI\%http://cloud\-images.ubuntu.com/\fP
.SS Using Salt Virt
.sp
With hypervisors set up and virtual machine images ready, Salt can start
issuing cloud commands.
.sp
Start by running a Salt Virt hypervisor info command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run virt.hyper_info
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will query what the running hypervisor stats are and display information
for all configured hypervisors. This command will also validate that the
hypervisors are properly configured.
.sp
Now that hypervisors are available a virtual machine can be provisioned. The
\fBvirt.init\fP routine will create a new virtual machine:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run virt.init centos1 2 512 salt://centos.img
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This command assumes that the CentOS virtual machine image is sitting in the
root of the Salt fileserver. Salt Virt will now select a hypervisor to deploy
the new virtual machine on and copy the virtual machine image down to the
hypervisor.
.sp
Once the VM image has been copied down the new virtual machine will be seeded.
Seeding the VMs involves setting pre\-authenticated Salt keys on the new VM and
if needed, will install the Salt Minion on the new VM before it is started.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The biggest bottleneck in starting VMs is when the Salt Minion needs to be
installed. Making sure that the source VM images already have Salt
installed will GREATLY speed up virtual machine deployment.
.UNINDENT
.UNINDENT
.sp
Now that the new VM has been prepared, it can be seen via the \fBvirt.query\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run virt.query
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This command will return data about all of the hypervisors and respective
virtual machines.
.sp
Now that the new VM is booted it should have contacted the Salt Master, a
\fBtest.ping\fP will reveal if the new VM is running.
.SS Migrating Virtual Machines
.sp
Salt Virt comes with full support for virtual machine migration, and using
the libvirt state in the above formula makes migration possible.
.sp
A few things need to be available to support migration. Many operating systems
turn on firewalls when originally set up, the firewall needs to be opened up
to allow for libvirt and kvm to cross communicate and execution migration
routines. On Red Hat based hypervisors in particular port 16514 needs to be
opened on hypervisors:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
iptables \-A INPUT \-m state \-\-state NEW \-m tcp \-p tcp \-\-dport 16514 \-j ACCEPT
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
More in\-depth information regarding distribution specific firewall settings can read in:
.sp
\fBOpening the Firewall up for Salt\fP
.UNINDENT
.UNINDENT
.sp
Salt also needs an additional flag to be turned on as well. The \fBvirt.tunnel\fP
option needs to be turned on. This flag tells Salt to run migrations securely
via the libvirt TLS tunnel and to use port 16514. Without \fBvirt.tunnel\fP libvirt
tries to bind to random ports when running migrations. To turn on \fBvirt.tunnel\fP
simple apply it to the master config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virt.tunnel: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once the master config has been updated, restart the master and send out a call
to the minions to refresh the pillar to pick up on the change:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \e* saltutil.refresh_modules
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now, migration routines can be run! To migrate a VM, simply run the Salt Virt
migrate routine:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run virt.migrate centos <new hypervisor>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS VNC Consoles
.sp
Salt Virt also sets up VNC consoles by default, allowing for remote visual
consoles to be oped up. The information from a \fBvirt.query\fP routine will
display the vnc console port for the specific vms:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
centos
CPU: 2
Memory: 524288
State: running
Graphics: vnc \- hyper6:5900
Disk \- vda:
Size: 2.0G
File: /srv/salt\-images/ubuntu2/system.qcow2
File Format: qcow2
Nic \- ac:de:48:98:08:77:
Source: br0
Type: bridge
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The line \fIGraphics: vnc \- hyper6:5900\fP holds the key. First the port named,
in this case 5900, will need to be available in the hypervisor\(aqs firewall.
Once the port is open, then the console can be easily opened via vncviewer:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vncviewer hyper6:5900
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default there is no VNC security set up on these ports, which suggests that
keeping them firewalled and mandating that SSH tunnels be used to access these
VNC interfaces. Keep in mind that activity on a VNC interface that is accessed
can be viewed by any other user that accesses that same VNC interface, and any other
user logging in can also operate with the logged in user on the virtual
machine.
.SS Conclusion
.sp
Now with Salt Virt running, new hypervisors can be seamlessly added just by
running the above states on new bare metal machines, and these machines will be
instantly available to Salt Virt.
.SS Halite
.SS Installing and Configuring Halite
.sp
In this tutorial, we\(aqll walk through installing and setting up Halite. The
current version of Halite is considered pre\-alpha and is supported only in Salt
\fBv2014.1.0\fP or greater. Additional information is available on GitHub:
\fI\%https://github.com/saltstack/halite\fP
.sp
Before beginning this tutorial, ensure that the salt\-master is installed. To
install the salt\-master, please review the installation documentation:
\fI\%http://docs.saltstack.com/topics/installation/index.html\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Halite only works with Salt versions greater than 2014.1.0.
.UNINDENT
.UNINDENT
.SS Installing Halite Via Package
.sp
On CentOS, RHEL, or Fedora:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ yum install python\-halite
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
By default python\-halite only installs CherryPy. If you would like to use
a different webserver please review the instructions below to install
pip and your server of choice. The package does not modify the master
configuration with \fB/etc/salt/master\fP\&.
.UNINDENT
.UNINDENT
.SS Installing Halite Using pip
.sp
To begin the installation of Halite from PyPI, you\(aqll need to install pip. The
Salt package, as well as the bootstrap, do not install pip by default.
.sp
On CentOS, RHEL, or Fedora:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ yum install python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Debian:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ apt\-get install python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once you have pip installed, use it to install halite:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip install \-U halite
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Depending on the webserver you want to run halite through, you\(aqll need to
install that piece as well. On RHEL based distros, use one of the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip install cherrypy
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip install paste
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ yum install python\-devel
$ yum install gcc
$ pip install gevent
$ pip install pyopenssl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Debian based distributions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip install CherryPy
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip install paste
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ apt\-get install gcc
$ apt\-get install python\-dev
$ apt\-get install libevent\-dev
$ pip install gevent
$ pip install pyopenssl
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configuring Halite Permissions
.sp
Configuring Halite access permissions is easy. By default, you only need to
ensure that the @runner group is configured. In the \fB/etc/salt/master\fP file,
uncomment and modify the following lines:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
testuser:
\- .*
\- \(aq@runner\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
You cannot use the root user for pam login; it will fail to authenticate.
.UNINDENT
.UNINDENT
.sp
Halite uses the runner manage.present to get the status of minions, so runner
permissions are required. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
mytestuser:
\- .*
\- \(aq@runner\(aq
\- \(aq@wheel\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Currently Halite allows, but does not require, any wheel modules.
.SS Configuring Halite Settings
.sp
Once you\(aqve configured the permissions for Halite, you\(aqll need to set up the
Halite settings in the /etc/salt/master file. Halite supports CherryPy, Paste
and Gevent out of the box.
.sp
To configure cherrypy, add the following to the bottom of your /etc/salt/master file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
halite:
level: \(aqdebug\(aq
server: \(aqcherrypy\(aq
host: \(aq0.0.0.0\(aq
port: \(aq8080\(aq
cors: False
tls: True
certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq
keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq
pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you wish to use paste:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
halite:
level: \(aqdebug\(aq
server: \(aqpaste\(aq
host: \(aq0.0.0.0\(aq
port: \(aq8080\(aq
cors: False
tls: True
certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq
keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq
pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To use gevent:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
halite:
level: \(aqdebug\(aq
server: \(aqgevent\(aq
host: \(aq0.0.0.0\(aq
port: \(aq8080\(aq
cors: False
tls: True
certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq
keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq
pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The "cherrypy" and "gevent" servers require the certpath and keypath files
to run tls/ssl. The .crt file holds the public cert and the .key file holds
the private key. Whereas the "paste" server requires a single .pem file that
contains both the cert and key. This can be created simply by concatenating
the .crt and .key files.
.sp
If you want to use a self\-signed cert, you can create one using the Salt.tls
module:
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The following command needs to be run on your salt master.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call tls.create_self_signed_cert tls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that certs generated by the above command can be found under the \fB/etc/pki/tls/certs/\fP directory.
When using self\-signed certs, browsers will need approval before accepting the
cert. If the web application page has been cached with a non\-HTTPS version of
the app, then the browser cache will have to be cleared before it will
recognize and prompt to accept the self\-signed certificate.
.SS Starting Halite
.sp
Once you\(aqve configured the halite section of your /etc/salt/master, you can
restart the salt\-master service, and your halite instance will be available.
Depending on your configuration, the instance will be available either at
\fI\%http://localhost:8080/app\fP, \fI\%http://domain:8080/app\fP, or
\fI\%http://123.456.789.012:8080/app\fP .
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
halite requires an HTML 5 compliant browser.
.UNINDENT
.UNINDENT
.sp
All logs relating to halite are logged to the default /var/log/salt/master file.
.SS Using Salt at scale
.SS Using salt at scale
.sp
The focus of this tutorial will be building a Salt infrastructure for handling
large numbers of minions. This will include tuning, topology, and best practices.
.sp
For how to install the saltmaster please
go here: \fI\%Installing saltstack\fP
.INDENT 0.0
.INDENT 3.5
Note
This tutorial is intended for large installations, although these same settings
won\(aqt hurt, it may not be worth the complexity to smaller installations.
.sp
When used with minions, the term \(aqmany\(aq refers to at least a thousand
and \(aqa few\(aq always means 500.
.sp
For simplicity reasons, this tutorial will default to the standard ports
used by salt.
.UNINDENT
.UNINDENT
.SS The Master
.sp
The most common problems on the salt\-master are:
.INDENT 0.0
.IP 1. 3
too many minions authing at once
.IP 2. 3
too many minions re\-authing at once
.IP 3. 3
too many minions re\-connecting at once
.IP 4. 3
too many minions returning at once
.IP 5. 3
too few resources (CPU/HDD)
.UNINDENT
.sp
The first three are all "thundering herd" problems. To mitigate these issues
we must configure the minions to back\-off appropriately when the master is
under heavy load.
.sp
The fourth is caused by masters with little hardware resources in combination
with a possible bug in ZeroMQ. At least thats what it looks like till today
(\fI\%Issue 118651\fP,
\fI\%Issue 5948\fP,
\fI\%Mail thread\fP)
.sp
To fully understand each problem, it is important to understand, how salt works.
.sp
Very briefly, the saltmaster offers two services to the minions.
.INDENT 0.0
.IP \(bu 2
a job publisher on port 4505
.IP \(bu 2
an open port 4506 to receive the minions returns
.UNINDENT
.sp
All minions are always connected to the publisher on port 4505 and only connect
to the open return port 4506 if necessary. On an idle master, there will only
be connections on port 4505.
.SS Too many minions authing
.sp
When the minion service is first started up, it will connect to its master\(aqs publisher
on port 4505. If too many minions are started at once, this can cause a "thundering herd".
This can be avoided by not starting too many minions at once.
.sp
The connection itself usually isn\(aqt the culprit, the more likely cause of master\-side
issues is the authentication that the minion must do with the master. If the master
is too heavily loaded to handle the auth request it will time it out. The minion
will then wait \fIacceptance_wait_time\fP to retry. If \fIacceptance_wait_time_max\fP is
set then the minion will increase its wait time by the \fIacceptance_wait_time\fP each
subsequent retry until reaching \fIacceptance_wait_time_max\fP\&.
.SS Too many minions re\-authing
.sp
This is most likely to happen in the testing phase, when all minion keys have
already been accepted, the framework is being tested and parameters change
frequently in the masters configuration file.
.sp
In a few cases (master restart, remove minion key, etc.) the salt\-master generates
a new AES\-key to encrypt its publications with. The minions aren\(aqt notified of
this but will realize this on the next pub job they receive. When the minion
receives such a job it will then re\-auth with the master. Since Salt does minion\-side
filtering this means that all the minions will re\-auth on the next command published
on the master\-\- causing another "thundering herd". This can be avoided by
setting the
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
random_reauth_delay: 60
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
in the minions configuration file to a higher value and stagger the amount
of re\-auth attempts. Increasing this value will of course increase the time
it takes until all minions are reachable via salt commands.
.SS Too many minions re\-connecting
.sp
By default the zmq socket will re\-connect every 100ms which for some larger
installations may be too quick. This will control how quickly the TCP session is
re\-established, but has no bearing on the auth load.
.sp
To tune the minions sockets reconnect attempts, there are a few values in
the sample configuration file (default values)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
recon_default: 100ms
recon_max: 5000
recon_randomize: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
recon_default: the default value the socket should use, i.e. 100ms
.IP \(bu 2
recon_max: the max value that the socket should use as a delay before trying to reconnect
.IP \(bu 2
recon_randomize: enables randomization between recon_default and recon_max
.UNINDENT
.sp
To tune this values to an existing environment, a few decision have to be made.
.INDENT 0.0
.IP 1. 3
How long can one wait, before the minions should be online and reachable via salt?
.IP 2. 3
How many reconnects can the master handle without a syn flood?
.UNINDENT
.sp
These questions can not be answered generally. Their answers depend on the
hardware and the administrators requirements.
.sp
Here is an example scenario with the goal, to have all minions reconnect
within a 60 second time\-frame on a salt\-master service restart.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
recon_default: 1000
recon_max: 59000
recon_randomize: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Each minion will have a randomized reconnect value between \(aqrecon_default\(aq
and \(aqrecon_default + recon_max\(aq, which in this example means between 1000ms
and 60000ms (or between 1 and 60 seconds). The generated random\-value will
be doubled after each attempt to reconnect (ZeroMQ default behavior).
.sp
Lets say the generated random value is 11 seconds (or 11000ms).
.sp
reconnect 1: wait 11 seconds
reconnect 2: wait 22 seconds
reconnect 3: wait 33 seconds
reconnect 4: wait 44 seconds
reconnect 5: wait 55 seconds
reconnect 6: wait time is bigger than 60 seconds (recon_default + recon_max)
reconnect 7: wait 11 seconds
reconnect 8: wait 22 seconds
reconnect 9: wait 33 seconds
reconnect x: etc.
.sp
With a thousand minions this will mean
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1000/60 = ~16
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
round about 16 connection attempts a second. These values should be altered to
values that match your environment. Keep in mind though, that it may grow over
time and that more minions might raise the problem again.
.SS Too many minions returning at once
.sp
This can also happen during the testing phase, if all minions are addressed at
once with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt * test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
it may cause thousands of minions trying to return their data to the salt\-master
open port 4506. Also causing a flood of syn\-flood if the master can\(aqt handle that many
returns at once.
.sp
This can be easily avoided with salts batch mode:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt * test.ping \-b 50
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will only address 50 minions at once while looping through all addressed
minions.
.SS Too few resources
.sp
The masters resources always have to match the environment. There is no way
to give good advise without knowing the environment the master is supposed to
run in. But here are some general tuning tips for different situations:
.SS The master is CPU bound
.sp
Salt uses RSA\-Key\-Pairs on the masters and minions end. Both generate 4096
bit key\-pairs on first start. While the key\-size for the master is currently
not configurable, the minions keysize can be configured with different
key\-sizes. For example with a 2048 bit key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
keysize: 2048
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With thousands of decryptions, the amount of time that can be saved on the
masters end should not be neglected. See here for reference:
\fI\%Pull Request 9235\fP how much
influence the key\-size can have.
.sp
Downsizing the salt\-masters key is not that important, because the minions
do not encrypt as many messages as the master does.
.SS The master is disk IO bound
.sp
By default, the master saves every minion\(aqs return for every job in its
job\-cache. The cache can then be used later, to lookup results for previous
jobs. The default directory for this is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cachedir: /var/cache/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and then in the \fB/proc\fP directory.
.sp
Each job return for every minion is saved in a single file. Over time this
directory can grow quite large, depending on the number of published jobs. The
amount of files and directories will scale with the number of jobs published and
the retention time defined by
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
keep_jobs: 24
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
250 jobs/day * 2000 minions returns = 500.000 files a day
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If no job history is needed, the job cache can be disabled:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job_cache: False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the job cache is necessary there are (currently) 2 options:
.INDENT 0.0
.IP \(bu 2
ext_job_cache: this will have the minions store their return data directly
into a returner (not sent through the master)
.IP \(bu 2
master_job_cache (New in \fI2014.7.0\fP): this will make the master store the job
data using a returner (instead of the local job cache on disk).
.UNINDENT
.SH TARGETING MINIONS
.sp
Targeting minions is specifying which minions should run a command or execute a
state by matching against hostnames, or system information, or defined groups,
or even combinations thereof.
.sp
For example the command \fBsalt web1 apache.signal restart\fP to restart the
Apache httpd server specifies the machine \fBweb1\fP as the target and the
command will only be run on that one minion.
.sp
Similarly when using States, the following \fItop file\fP specifies that only
the \fBweb1\fP minion should execute the contents of \fBwebserver.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqweb1\(aq:
\- webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There are many ways to target individual minions or groups of minions in Salt:
.SS Matching the \fBminion id\fP
.sp
Each minion needs a unique identifier. By default when a minion starts for the
first time it chooses its FQDN as that
identifier. The minion id can be overridden via the minion\(aqs \fBid\fP
configuration setting.
.sp
\fBTIP:\fP
.INDENT 0.0
.INDENT 3.5
minion id and minion keys
.sp
The \fIminion id\fP is used to generate the minion\(aqs public/private keys
and if it ever changes the master must then accept the new key as though
the minion was a new host.
.UNINDENT
.UNINDENT
.SS Globbing
.sp
The default matching that Salt utilizes is \fI\%shell\-style globbing\fP around the \fIminion id\fP\&. This also works for states
in the \fItop file\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
You must wrap \fBsalt\fP calls that use globbing in single\-quotes to
prevent the shell from expanding the globs before Salt is invoked.
.UNINDENT
.UNINDENT
.sp
Match all minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Match all minions in the example.net domain or any of the example domains:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*.example.net\(aq test.ping
salt \(aq*.example.*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Match all the \fBwebN\fP minions in the example.net domain (\fBweb1.example.net\fP,
\fBweb2.example.net\fP … \fBwebN.example.net\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqweb?.example.net\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Match the \fBweb1\fP through \fBweb5\fP minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqweb[1\-5]\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Match the \fBweb1\fP and \fBweb3\fP minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqweb[1,3]\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Match the \fBweb\-x\fP, \fBweb\-y\fP, and \fBweb\-z\fP minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqweb\-[x\-z]\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For additional targeting methods please review the
\fBcompound matchers\fP documentation.
.UNINDENT
.UNINDENT
.SS Regular Expressions
.sp
Minions can be matched using Perl\-compatible \fI\%regular expressions\fP (which is globbing on steroids and a ton of caffeine).
.sp
Match both \fBweb1\-prod\fP and \fBweb1\-devel\fP minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-E \(aqweb1\-(prod|devel)\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When using regular expressions in a State\(aqs \fItop file\fP, you must specify
the matcher as the first option. The following example executes the contents of
\fBwebserver.sls\fP on the above\-mentioned minions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqweb1\-(prod|devel)\(aq:
\- match: pcre
\- webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Lists
.sp
At the most basic level, you can specify a flat list of minion IDs:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-L \(aqweb1,web2,web3\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS 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.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Grains resolve to lowercase letters. For example, \fBFOO\fP and \fBfoo\fP
target the same grain.
.UNINDENT
.UNINDENT
.sp
Match all CentOS minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos:CentOS\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Match all minions with 64\-bit CPUs, and return number of CPU cores for each
matching minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqcpuarch:x86_64\(aq grains.item num_cpus
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Additionally, globs can be used in grain matches, and grains that are nested in
a \fI\%dictionary\fP can be matched by adding a colon for
each level that is traversed. For example, the following will match hosts that
have a grain called \fBec2_tags\fP, which itself is a
\fI\%dict\fP with a key named \fBenvironment\fP, which
has a value that contains the word \fBproduction\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqec2_tags:environment:*production*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Listing Grains
.sp
Available grains can be listed by using the \(aqgrains.ls\(aq module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.ls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Grains data can be listed by using the \(aqgrains.items\(aq module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.items
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Grains in the Minion Config
.sp
Grains can also be statically assigned within the minion configuration file.
Just add the option \fBgrains\fP and pass options to it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
grains:
roles:
\- webserver
\- memcache
deployment: datacenter4
cabinet: 13
cab_u: 14\-15
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then status data specific to your servers can be retrieved via Salt, or used
inside of the State system for matching. It also makes targeting, in the case
of the example above, simply based on specific data about your deployment.
.SS Grains in /etc/salt/grains
.sp
If you do not want to place your custom static grains in the minion config
file, you can also put them in \fB/etc/salt/grains\fP on the minion. They are configured in the
same way as in the above example, only without a top\-level \fBgrains:\fP key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
roles:
\- webserver
\- memcache
deployment: datacenter4
cabinet: 13
cab_u: 14\-15
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Matching Grains in the Top File
.sp
With correctly configured grains on the Minion, the \fItop file\fP used in
Pillar or during Highstate can be made very efficient. For example, consider
the following configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqnode_type:web\(aq:
\- match: grain
\- webserver
\(aqnode_type:postgres\(aq:
\- match: grain
\- database
\(aqnode_type:redis\(aq:
\- match: grain
\- redis
\(aqnode_type:lb\(aq:
\- match: grain
\- lb
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For this example to work, you would need to have defined the grain
\fBnode_type\fP for the minions you wish to match. This simple example is nice,
but too much of the code is similar. To go one step further, Jinja templating
can be used to simplify the the \fItop file\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set node_type = salt[\(aqgrains.get\(aq](\(aqnode_type\(aq, \(aq\(aq) %}
{% if node_type %}
\(aqnode_type:{{ self }}\(aq:
\- match: grain
\- {{ self }}
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using Jinja templating, only one match entry needs to be defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The example above uses the \fBgrains.get\fP
function to account for minions which do not have the \fBnode_type\fP grain
set.
.UNINDENT
.UNINDENT
.SS Writing Grains
.sp
Grains are easy to write. The grains interface is derived by executing
all of the "public" functions found in the modules located in the grains
package or the custom grains directory. The functions in the modules of
the grains must return a Python \fI\%dict\fP, where the
keys in the \fI\%dict\fP are the names of the grains and
the values are the values.
.sp
Custom grains should be placed in a \fB_grains\fP directory located under the
\fBfile_roots\fP specified by the master config file. They will be
distributed to the minions when \fBstate.highstate\fP is run, or by executing the
\fBsaltutil.sync_grains\fP or
\fBsaltutil.sync_all\fP functions.
.sp
Grains are easy to write, and only need to return a dictionary. A common
approach would be code something similar to the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/usr/bin/env python
def yourfunction():
# initialize a grains dictionary
grains = {}
# Some code for logic that sets grains like
grains[\(aqyourcustomgrain\(aq]=True
grains[\(aqanothergrain\(aq]=\(aqsomevalue\(aq
return grains
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Before adding a grain to Salt, consider what the grain is and remember that
grains need to be static data. If the data is something that is likely to
change, consider using \fBPillar\fP instead.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Custom grains will not be available in the top file until after the first
\fIhighstate\fP\&. To make custom grains available on a
minion\(aqs first highstate, it is recommended to use \fIthis example\fP to ensure that the custom grains are synced when
the minion starts.
.UNINDENT
.UNINDENT
.SS Precedence
.sp
Core grains can be overridden by custom grains. As there are several ways of
defining custom grains, there is an order of precedence which should be kept in
mind when defining them. The order of evaluation is as follows:
.INDENT 0.0
.IP 1. 3
Core grains.
.IP 2. 3
Custom grain modules in \fB_grains\fP directory, synced to minions.
.IP 3. 3
Custom grains in \fB/etc/salt/grains\fP\&.
.IP 4. 3
Custom grains in \fB/etc/salt/minion\fP\&.
.UNINDENT
.sp
Each successive evaluation overrides the previous ones, so any grains defined
by custom grains modules synced to minions that have the same name as a core
grain will override that core grain. Similarly, grains from
\fB/etc/salt/grains\fP override both core grains and custom grain modules, and
grains in \fB/etc/salt/minion\fP will override \fIany\fP grains of the same name.
.SS Examples of Grains
.sp
The core module in the grains package is where the main grains are loaded by
the Salt minion and provides the principal example of how to write grains:
.sp
\fI\%https://github.com/saltstack/salt/blob/develop/salt/grains/core.py\fP
.SS Syncing Grains
.sp
Syncing grains can be done a number of ways, they are automatically synced when
\fBstate.highstate\fP is called, or (as noted
above) the grains can be manually synced and reloaded by calling the
\fBsaltutil.sync_grains\fP or
\fBsaltutil.sync_all\fP functions.
.SS Subnet/IP Address Matching
.sp
Minions can easily be matched based on IP address, or by subnet (using \fI\%CIDR\fP
notation).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-S 192.168.40.20 test.ping
salt \-S 10.0.0.0/24 test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Only IPv4 matching is supported at this time.
.UNINDENT
.UNINDENT
.SS Compound matchers
.sp
Compound matchers allow very granular minion targeting using any of Salt\(aqs
matchers. The default matcher is a \fI\%glob\fP match, just as
with CLI and \fItop file\fP matching. To match using anything other than a
glob, prefix the match string with the appropriate letter from the table below,
followed by an \fB@\fP sign.
.TS
center;
|l|l|l|.
_
T{
Letter
T} T{
Match Type
T} T{
Example
T}
_
T{
G
T} T{
Grains glob
T} T{
\fBG@os:Ubuntu\fP
T}
_
T{
E
T} T{
PCRE Minion ID
T} T{
\fBE@web\ed+\e.(dev|qa|prod)\e.loc\fP
T}
_
T{
P
T} T{
Grains PCRE
T} T{
\fBP@os:(RedHat|Fedora|CentOS)\fP
T}
_
T{
L
T} T{
List of minions
T} T{
\fBL@minion1.example.com,minion3.domain.com or bl*.domain.com\fP
T}
_
T{
I
T} T{
Pillar glob
T} T{
\fBI@pdata:foobar\fP
T}
_
T{
S
T} T{
Subnet/IP address
T} T{
\fBS@192.168.1.0/24\fP or \fBS@192.168.1.100\fP
T}
_
T{
R
T} T{
Range cluster
T} T{
\fBR@%foo.bar\fP
T}
_
.TE
.sp
Matchers can be joined using boolean \fBand\fP, \fBor\fP, and \fBnot\fP operators.
.sp
For example, the following string matches all Debian minions with a hostname
that begins with \fBwebserv\fP, as well as any minions that have a hostname which
matches the \fI\%regular expression\fP \fBweb\-dc1\-srv.*\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-C \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That same example expressed in a \fItop file\fP looks like the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq:
\- match: compound
\- webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that a leading \fBnot\fP is not supported in compound matches. Instead,
something like the following must be done:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-C \(aq* and not G@kernel:Darwin\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Excluding a minion based on its ID is also possible:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-C \(aq* and not web\-dc1\-srv\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Precedence Matching
.sp
Matches can be grouped together with parentheses to explicitly declare precedence amongst groups.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-C \(aq( ms\-1 or G@id:ms\-3 ) and G@id:ms\-3\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Be certain to note that spaces are required between the parentheses and targets. Failing to obey this
rule may result in incorrect targeting!
.UNINDENT
.UNINDENT
.SS Node groups
.sp
Nodegroups are declared using a compound target specification. The compound
target documentation can be found \fBhere\fP\&.
.sp
The \fBnodegroups\fP master config file parameter is used to define
nodegroups. Here\(aqs an example nodegroup configuration within
\fB/etc/salt/master\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nodegroups:
group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com\(aq
group2: \(aqG@os:Debian and foo.domain.com\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBL\fP within group1 is matching a list of minions, while the \fBG\fP in
group2 is matching specific grains. See the \fBcompound matchers\fP documentation for more details.
.UNINDENT
.UNINDENT
.sp
To match a nodegroup on the CLI, use the \fB\-N\fP command\-line option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-N group1 test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To match a nodegroup in your \fItop file\fP, make sure to put \fB\- match:
nodegroup\fP on the line directly following the nodegroup name.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
group1:
\- match: nodegroup
\- webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When adding or modifying nodegroups to a master configuration file, the master must be restarted
for those changes to be fully recognized.
.sp
A limited amount of functionality, such as targeting with \-N from the command\-line may be
available without a restart.
.UNINDENT
.UNINDENT
.SS Batch Size
.sp
The \fB\-b\fP (or \fB\-\-batch\-size\fP) option allows commands to be executed on only
a specified number of minions at a time. Both percentages and finite numbers are
supported.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq \-b 10 test.ping
salt \-G \(aqos:RedHat\(aq \-\-batch\-size 25% apache.signal restart
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will only run test.ping on 10 of the targeted minions at a time and then
restart apache on 25% of the minions matching \fBos:RedHat\fP at a time and work
through them all until the task is complete. This makes jobs like rolling web
server restarts behind a load balancer or doing maintenance on BSD firewalls
using carp much easier with salt.
.sp
The batch system maintains a window of running minions, so, if there are a
total of 150 minions targeted and the batch size is 10, then the command is
sent to 10 minions, when one minion returns then the command is sent to one
additional minion, so that the job is constantly running on 10 minions.
.SS SECO Range
.sp
SECO range is a cluster\-based metadata store developed and maintained by Yahoo!
.sp
The Range project is hosted here:
.sp
\fI\%https://github.com/ytoolshed/range\fP
.sp
Learn more about range here:
.sp
\fI\%https://github.com/ytoolshed/range/wiki/\fP
.SS Prerequisites
.sp
To utilize range support in Salt, a range server is required. Setting up a
range server is outside the scope of this document. Apache modules are included
in the range distribution.
.sp
With a working range server, cluster files must be defined. These files are
written in YAML and define hosts contained inside a cluster. Full documentation
on writing YAML range files is here:
.sp
\fI\%https://github.com/ytoolshed/range/wiki/%22yamlfile%22\-module\-file\-spec\fP
.sp
Additionally, the Python seco range libraries must be instaled on the salt
master. One can verify that they have been installed correctly via the
following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python \-c \(aqimport seco.range\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If no errors are returned, range is installed successfully on the salt master.
.SS Preparing Salt
.sp
Range support must be enabled on the salt master by setting the hostname and
port of the range server inside the master configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
range_server: my.range.server.com:80
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Following this, the master must be restarted for the change to have an effect.
.SS Targeting with Range
.sp
Once a cluster has been defined, it can be targeted with a salt command by
using the \fB\-R\fP or \fB\-\-range\fP flags.
.sp
For example, given the following range YAML file being served from a range
server:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cat /etc/range/test.yaml
CLUSTER: host1..100.test.com
APPS:
\- frontend
\- backend
\- mysql
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
One might target host1 through host100 in the test.com domain with Salt as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-\-range %test:CLUSTER test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following salt command would target three hosts: \fBfrontend\fP, \fBbackend\fP and \fBmysql\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-\-range %test:APPS test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SH STORING STATIC DATA IN THE PILLAR
.sp
Pillar is an interface for Salt designed to offer global values that can be
distributed to all minions. Pillar data is managed in a similar way as
the Salt State Tree.
.sp
Pillar was added to Salt in version 0.9.8
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Storing sensitive data
.sp
Unlike state tree, pillar data is only available for the targeted
minion specified by the matcher type. This makes it useful for
storing sensitive data specific to a particular minion.
.UNINDENT
.UNINDENT
.SS Declaring the Master Pillar
.sp
The Salt Master server maintains a pillar_roots setup that matches the
structure of the file_roots used in the Salt file server. Like the
Salt file server the \fBpillar_roots\fP option in the master config is based
on environments mapping to directories. The pillar data is then mapped to
minions based on matchers in a top file which is laid out in the same way
as the state top file. Salt pillars can use the same matcher types as the
standard top file.
.sp
The configuration for the \fBpillar_roots\fP in the master config file
is identical in behavior and function as \fBfile_roots\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pillar_roots:
base:
\- /srv/pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example configuration declares that the base environment will be located
in the \fB/srv/pillar\fP directory. It must not be in a subdirectory of the
state tree.
.sp
The top file used matches the name of the top file used for States,
and has the same structure:
.sp
\fB/srv/pillar/top.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- packages
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the above top file, it is declared that in the \(aqbase\(aq environment, the glob
matching all minions will have the pillar data found in the \(aqpackages\(aq pillar
available to it. Assuming the \(aqpillar_roots\(aq value of \(aq/srv/salt\(aq taken from
above, the \(aqpackages\(aq pillar would be located at \(aq/srv/salt/packages.sls\(aq.
.sp
Another example shows how to use other standard top matching types
to deliver specific salt pillar data to minions with different properties.
.sp
Here is an example using the \(aqgrains\(aq matcher to target pillars to minions
by their \(aqos\(aq grain:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dev:
\(aqos:Debian\(aq:
\- match: grain
\- servers
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/packages.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if grains[\(aqos\(aq] == \(aqRedHat\(aq %}
apache: httpd
git: git
{% elif grains[\(aqos\(aq] == \(aqDebian\(aq %}
apache: apache2
git: git\-core
{% endif %}
company: Foo Industries
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above pillar sets two key/value pairs. If a minion is running RedHat, then
the \(aqapache\(aq key is set to \(aqhttpd\(aq and the \(aqgit\(aq key is set to the value of
\(aqgit\(aq. If the minion is running Debian, those values are changed to \(aqapache2\(aq
and \(aqgit\-core\(aq respctively. All minions that have this pillar targeting to them
via a top file will have the key of \(aqcompany\(aq with a value of \(aqFoo Industries\(aq.
.sp
Consequently this data can be used from within modules, renderers, State SLS files, and
more via the shared pillar \fI\%dict\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
\- name: {{ pillar[\(aqapache\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git:
pkg.installed:
\- name: {{ pillar[\(aqgit\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, the above states can utilize the values provided to them via Pillar.
All pillar values targeted to a minion are available via the \(aqpillar\(aq
dictionary. As seen in the above example, Jinja substitution can then be
utilized to access the keys and values in the Pillar dictionary.
.sp
Note that you cannot just list key/value\-information in \fBtop.sls\fP\&. Instead,
target a minion to a pillar file and then list the keys and values in the
pillar. Here is an example top file that illustrates this point:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- common_pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And the actual pillar file at \(aq/srv/salt/common_pillar.sls\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: bar
boo: baz
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Pillar namespace flattened
.sp
The separate pillar files all share the same namespace. Given a \fBtop.sls\fP of:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- packages
\- services
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
a \fBpackages.sls\fP file of:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bind: bind9
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and a \fBservices.sls\fP file of:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bind: named
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then a request for the \fBbind\fP pillar will only return \(aqnamed\(aq; the \(aqbind9\(aq
value is not available. It is better to structure your pillar files with more
hierarchy. For example your \fBpackage.sls\fP file could look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
packages:
bind: bind9
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Pillar Namespace Merges
.sp
With some care, the pillar namespace can merge content from multiple pillar
files under a single key, so long as conflicts are avoided as described above.
.sp
For example, if the above example were modified as follows, the values are
merged below a single key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- packages
\- services
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And a \fBpackages.sls\fP file like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bind:
package\-name: bind9
version: 9.9.5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And a \fBservices.sls\fP file like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bind:
port: 53
listen\-on: any
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The resulting pillar will be as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-call pillar.get bind
local:
\-\-\-\-\-\-\-\-\-\-
listen\-on:
any
package\-name:
bind9
port:
53
version:
9.9.5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Remember: conflicting keys will be overwritten in a non\-deterministic manner!
.UNINDENT
.UNINDENT
.SS Including Other Pillars
.sp
New in version 0.16.0.
.sp
Pillar SLS files may include other pillar files, similar to State files. Two
syntaxes are available for this purpose. The simple form simply includes the
additional pillar as if it were part of the same file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- users
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The full include form allows two additional options \-\- passing default values
to the templating engine for the included pillar file as well as an optional
key under which to nest the results of the included pillar:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- users:
defaults:
sudo: [\(aqbob\(aq, \(aqpaul\(aq]
key: users
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this form, the included file (users.sls) will be nested within the \(aqusers\(aq
key of the compiled pillar. Additionally, the \(aqsudo\(aq value will be available
as a template variable to users.sls.
.SS Viewing Minion Pillar
.sp
Once the pillar is set up the data can be viewed on the minion via the
\fBpillar\fP module, the pillar module comes with two functions,
\fBpillar.items\fP and and \fBpillar.raw\fP\&. \fBpillar.items\fP
will return a freshly reloaded pillar and \fBpillar.raw\fP will return the current pillar without a refresh:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.items
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Prior to version 0.16.2, this function is named \fBpillar.data\fP\&. This
function name is still supported for backwards compatibility.
.UNINDENT
.UNINDENT
.SS Pillar "get" Function
.sp
New in version 0.14.0.
.sp
The \fBpillar.get\fP function works much in the same
way as the \fBget\fP method in a python dict, but with an enhancement: nested
dict components can be extracted using a \fI:\fP delimiter.
.sp
If a structure like this is in pillar:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo:
bar:
baz: qux
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Extracting it from the raw pillar in an sls formula or file template is done
this way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ pillar[\(aqfoo\(aq][\(aqbar\(aq][\(aqbaz\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now, with the new \fBpillar.get\fP function the data
can be safely gathered and a default can be set, allowing the template to fall
back if the value is not available:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ salt[\(aqpillar.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This makes handling nested structures much easier.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBpillar.get()\fP vs \fBsalt[\(aqpillar.get\(aq]()\fP
.sp
It should be noted that within templating, the \fBpillar\fP variable is just
a dictionary. This means that calling \fBpillar.get()\fP inside of a
template will just use the default dictionary \fB\&.get()\fP function which
does not include the extra \fB:\fP delimiter functionality. It must be
called using the above syntax (\fBsalt[\(aqpillar.get\(aq](\(aqfoo:bar:baz\(aq,
\(aqqux\(aq)\fP) to get the salt function, instead of the default dictionary
behavior.
.UNINDENT
.UNINDENT
.SS Refreshing Pillar Data
.sp
When pillar data is changed on the master the minions need to refresh the data
locally. This is done with the \fBsaltutil.refresh_pillar\fP function.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.refresh_pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function triggers the minion to asynchronously refresh the pillar and will
always return \fBNone\fP\&.
.SS Targeting with Pillar
.sp
Pillar data can be used when targeting minions. This allows for ultimate
control and flexibility when targeting minions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-I \(aqsomekey:specialvalue\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Like with \fBGrains\fP, it is possible to use globbing
as well as match nested values in Pillar, by adding colons for each level that
is being traversed. The below example would match minions with a pillar named
\fBfoo\fP, which is a dict containing a key \fBbar\fP, with a value beginning with
\fBbaz\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-I \(aqfoo:bar:baz*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Set Pillar Data at the Command Line
.sp
Pillar data can be set at the command line like the following example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate pillar=\(aq{"cheese": "spam"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create a dict with a key of \(aqcheese\(aq and a value of \(aqspam\(aq. A list
can be created like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate pillar=\(aq["cheese", "milk", "bread"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Master Config In Pillar
.sp
For convenience the data stored in the master configuration file is made
available in all minion\(aqs pillars. This makes global configuration of services
and systems very easy but may not be desired if sensitive data is stored in the
master configuration.
.sp
To disable the master config from being added to the pillar set \fBpillar_opts\fP
to \fBFalse\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pillar_opts: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SH REACTOR SYSTEM
.sp
Salt version 0.11.0 introduced the reactor system. The premise behind the
reactor system is that with Salt\(aqs events and the ability to execute commands,
a logic engine could be put in place to allow events to trigger actions, or
more accurately, reactions.
.sp
This system binds sls files to event tags on the master. These sls files then
define reactions. This means that the reactor system has two parts. First, the
reactor option needs to be set in the master configuration file. The reactor
option allows for event tags to be associated with sls reaction files. Second,
these reaction files use highdata (like the state system) to define reactions
to be executed.
.SS Event System
.sp
A basic understanding of the event system is required to understand reactors.
The event system is a local ZeroMQ PUB interface which fires salt events. This
event bus is an open system used for sending information notifying Salt and
other systems about operations.
.sp
The event system fires events with a very specific criteria. Every event has a
\fBtag\fP\&. Event tags allow for fast top level filtering of events. In
addition to the tag, each event has a data structure. This data structure is a
dict, which contains information about the event.
.SS Mapping Events to Reactor SLS Files
.sp
Reactor SLS files and event tags are associated in the master config file.
By default this is /etc/salt/master, or /etc/salt/master.d/reactor.conf.
.sp
New in version 2014.7.0: Added Reactor support for \fBsalt://\fP file paths.
.sp
In the master config section \(aqreactor:\(aq is a list of event tags to be matched
and each event tag has a list of reactor SLS files to be run.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
reactor: # Master config section "reactor"
\- \(aqsalt/minion/*/start\(aq: # Match tag "salt/minion/*/start"
\- /srv/reactor/start.sls # Things to do when a minion starts
\- /srv/reactor/monitor.sls # Other things to do
\- \(aqsalt/cloud/*/destroyed\(aq: # Globs can be used to matching tags
\- /srv/reactor/destroy/*.sls # Globs can be used to match file names
\- \(aqmyco/custom/event/tag\(aq: # React to custom event tags
\- salt://reactor/mycustom.sls # Put reactor files under file_roots
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Reactor sls files are similar to state and pillar sls files. They are
by default yaml + Jinja templates and are passed familar context variables.
.sp
They differ because of the addition of the \fBtag\fP and \fBdata\fP variables.
.INDENT 0.0
.IP \(bu 2
The \fBtag\fP variable is just the tag in the fired event.
.IP \(bu 2
The \fBdata\fP variable is the event\(aqs data dict.
.UNINDENT
.sp
Here is a simple reactor sls:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if data[\(aqid\(aq] == \(aqmysql1\(aq %}
highstate_run:
local.state.highstate:
\- tgt: mysql1
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This simple reactor file uses Jinja to further refine the reaction to be made.
If the \fBid\fP in the event data is \fBmysql1\fP (in other words, if the name of
the minion is \fBmysql1\fP) then the following reaction is defined. The same
data structure and compiler used for the state system is used for the reactor
system. The only difference is that the data is matched up to the salt command
API and the runner system. In this example, a command is published to the
\fBmysql1\fP minion with a function of \fBstate.highstate\fP\&. Similarly, a runner
can be called:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if data[\(aqdata\(aq][\(aqoverstate\(aq] == \(aqrefresh\(aq %}
overstate_run:
runner.state.over
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example will execute the state.overstate runner and initiate an overstate
execution.
.SS Fire an event
.sp
To fire an event from a minion call \fBevent.send\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call event.send \(aqfoo\(aq \(aq{overstate: refresh}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After this is called, any reactor sls files matching event tag \fBfoo\fP will
execute with \fB{{ data[\(aqdata\(aq][\(aqoverstate\(aq] }}\fP equal to \fB\(aqrefresh\(aq\fP\&.
.sp
See \fBsalt.modules.event\fP for more information.
.SS Knowing what event is being fired
.sp
The best way to see exactly what events are fired and what data is available in
each event is to use the \fBstate.event runner\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fICommon Salt Events\fP
.UNINDENT
.UNINDENT
.sp
Example usage:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.event pretty=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt/job/20150213001905721678/new {
"_stamp": "2015\-02\-13T00:19:05.724583",
"arg": [],
"fun": "test.ping",
"jid": "20150213001905721678",
"minions": [
"jerry"
],
"tgt": "*",
"tgt_type": "glob",
"user": "root"
}
salt/job/20150213001910749506/ret/jerry {
"_stamp": "2015\-02\-13T00:19:11.136730",
"cmd": "_return",
"fun": "saltutil.find_job",
"fun_args": [
"20150213001905721678"
],
"id": "jerry",
"jid": "20150213001910749506",
"retcode": 0,
"return": {},
"success": true
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Debugging the Reactor
.sp
The best window into the Reactor is to run the master in the foreground with
debug logging enabled. The output will include when the master sees the event,
what the master does in response to that event, and it will also include the
rendered SLS file (or any errors generated while rendering the SLS file).
.INDENT 0.0
.IP 1. 3
Stop the master.
.IP 2. 3
Start the master manually:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Understanding the Structure of Reactor Formulas
.sp
While the reactor system uses the same data structure as the state system, this
data does not translate the same way to function calls.
.sp
Changed in version 2014.7.0: The \fBcmd\fP prefix was renamed to \fBlocal\fP for consistency with other
parts of Salt. A backward\-compatible alias was added for \fBcmd\fP\&.
.sp
In state files the minion generates the data structure locally and uses that to
call local state functions. In the reactor system the master generates a data
structure that is used to call methods on one of Salt\(aqs client interfaces
described in \fIthe Python API documentation\fP\&.
.INDENT 0.0
.IP \(bu 2
\fBLocalClient\fP is used to call Execution modules
remotely on minions. (The \fBsalt\fP CLI program uses this also.)
.IP \(bu 2
\fBRunnerClient\fP calls Runner modules locally on the
master.
.IP \(bu 2
\fBWheelClient\fP calls Wheel modules locally on the
master.
.UNINDENT
.sp
The \fBstate declaration\fP field takes a reference to the function to call
in each interface. So to trigger a salt\-run call the \fBstate
declaration\fP field will start with \fBrunner\fP, followed by the runner
function to call. This means that a call to what would be on the command line
\fBsalt\-run manage.up\fP will be \fBrunner.manage.up\fP\&. An example of
this in a reactor formula would look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
manage_up:
runner.manage.up
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the runner takes arguments then they can be specified as well:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
overstate_dev_env:
runner.state.over:
\- env: dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Executing remote commands maps to the \fBLocalClient\fP interface which is
used by the \fBsalt\fP command. This interface more specifically maps to
the \fBcmd_async\fP method inside of the \fBLocalClient\fP class. This
means that the arguments passed are being passed to the \fBcmd_async\fP
method, not the remote method. A field starts with \fBlocal\fP to use the
\fBLocalClient\fP subsystem. The result is, to execute a remote command,
a reactor formula would look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
clean_tmp:
local.cmd.run:
\- tgt: \(aq*\(aq
\- arg:
\- rm \-rf /tmp/*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBarg\fP option takes a list of arguments as they would be presented on the
command line, so the above declaration is the same as running this salt
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run \(aqrm \-rf /tmp/*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use the \fBexpr_form\fP argument to specify a matcher:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
clean_tmp:
local.cmd.run:
\- tgt: \(aqos:Ubuntu\(aq
\- expr_form: grain
\- arg:
\- rm \-rf /tmp/*
clean_tmp:
local.cmd.run:
\- tgt: \(aqG@roles:hbase_master\(aq
\- expr_form: compound
\- arg:
\- rm \-rf /tmp/*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
An interesting trick to pass data from the Reactor script to
\fBstate.highstate\fP or \fBstate.sls\fP is to pass it as inline Pillar data since
both functions take a keyword argument named \fBpillar\fP\&.
.sp
The following example uses Salt\(aqs Reactor to listen for the event that is fired
when the key for a new minion is accepted on the master using \fBsalt\-key\fP\&.
.sp
\fB/etc/salt/master.d/reactor.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
reactor:
\- \(aqsalt/key\(aq:
\- /srv/salt/haproxy/react_new_minion.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Reactor then fires a \fBstate.sls\fP command targeted to the HAProxy servers
and passes the ID of the new minion from the event to the state file via inline
Pillar.
.sp
\fB/srv/salt/haproxy/react_new_minion.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if data[\(aqact\(aq] == \(aqaccept\(aq and data[\(aqid\(aq].startswith(\(aqweb\(aq) %}
add_new_minion_to_pool:
local.state.sls:
\- tgt: \(aqhaproxy*\(aq
\- arg:
\- haproxy.refresh_pool
\- kwarg:
pillar:
new_minion: {{ data[\(aqid\(aq] }}
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above command is equivalent to the following command at the CLI:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqhaproxy*\(aq state.sls haproxy.refresh_pool \(aqpillar={new_minion: minionid}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, that data is available in the state file using the normal Pillar
lookup syntax. The following example is grabbing web server names and IP
addresses from \fISalt Mine\fP\&. If this state is invoked from the
Reactor then the custom Pillar value from above will be available and the new
minion will be added to the pool but with the \fBdisabled\fP flag so that HAProxy
won\(aqt yet direct traffic to it.
.sp
\fB/srv/salt/haproxy/refresh_pool.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set new_minion = salt[\(aqpillar.get\(aq](\(aqnew_minion\(aq) %}
listen web *:80
balance source
{% for server,ip in salt[\(aqmine.get\(aq](\(aqweb*\(aq, \(aqnetwork.interfaces\(aq, [\(aqeth0\(aq]).items() %}
{% if server == new_minion %}
server {{ server }} {{ ip }}:80 disabled
{% else %}
server {{ server }} {{ ip }}:80 check
{% endif %}
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS A Complete Example
.sp
In this example, we\(aqre going to assume that we have a group of servers that
will come online at random and need to have keys automatically accepted. We\(aqll
also add that we don\(aqt want all servers being automatically accepted. For this
example, we\(aqll assume that all hosts that have an id that starts with \(aqink\(aq
will be automatically accepted and have state.highstate executed. On top of
this, we\(aqre going to add that a host coming up that was replaced (meaning a new
key) will also be accepted.
.sp
Our master configuration will be rather simple. All minions that attempte to
authenticate will match the \fBtag\fP of \fBsalt/auth\fP\&. When it comes
to the minion key being accepted, we get a more refined \fBtag\fP that
includes the minion id, which we can use for matching.
.sp
\fB/etc/salt/master.d/reactor.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
reactor:
\- \(aqsalt/auth\(aq:
\- /srv/reactor/auth\-pending.sls
\- \(aqsalt/minion/ink*/start\(aq:
\- /srv/reactor/auth\-complete.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this sls file, we say that if the key was rejected we will delete the key on
the master and then also tell the master to ssh in to the minion and tell it to
restart the minion, since a minion process will die if the key is rejected.
.sp
We also say that if the key is pending and the id starts with ink we will
accept the key. A minion that is waiting on a pending key will retry
authentication every ten seconds by default.
.sp
\fB/srv/reactor/auth\-pending.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{# Ink server faild to authenticate \-\- remove accepted key #}
{% if not data[\(aqresult\(aq] and data[\(aqid\(aq].startswith(\(aqink\(aq) %}
minion_remove:
wheel.key.delete:
\- match: {{ data[\(aqid\(aq] }}
minion_rejoin:
local.cmd.run:
\- tgt: salt\-master.domain.tld
\- arg:
\- ssh \-o UserKnownHostsFile=/dev/null \-o StrictHostKeyChecking=no "{{ data[\(aqid\(aq] }}" \(aqsleep 10 && /etc/init.d/salt\-minion restart\(aq
{% endif %}
{# Ink server is sending new key \-\- accept this key #}
{% if \(aqact\(aq in data and data[\(aqact\(aq] == \(aqpend\(aq and data[\(aqid\(aq].startswith(\(aqink\(aq) %}
minion_add:
wheel.key.accept:
\- match: {{ data[\(aqid\(aq] }}
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
No if statements are needed here because we already limited this action to just
Ink servers in the master configuration.
.sp
\fB/srv/reactor/auth\-complete.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{# When an Ink server connects, run state.highstate. #}
highstate_run:
local.state.highstate:
\- tgt: {{ data[\(aqid\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Syncing Custom Types on Minion Start
.sp
Salt will sync all custom types (by running a \fBsaltutil.sync_all\fP) on every highstate. However, there is a
chicken\-and\-egg issue where, on the initial highstate, a minion will not yet
have these custom types synced when the top file is first compiled. This can be
worked around with a simple reactor which watches for \fBminion_start\fP events,
which each minion fires when it first starts up and connects to the master.
.sp
On the master, create \fB/srv/reactor/sync_grains.sls\fP with the following
contents:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sync_grains:
local.saltutil.sync_grains:
\- tgt: {{ data[\(aqid\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And in the master config file, add the following reactor configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
reactor:
\- \(aqminion_start\(aq:
\- /srv/reactor/sync_grains.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will cause the master to instruct each minion to sync its custom grains
when it starts, making these grains available when the initial highstate is
executed.
.sp
Other types can be synced by replacing \fBlocal.saltutil.sync_grains\fP with
\fBlocal.saltutil.sync_modules\fP, \fBlocal.saltutil.sync_all\fP, or whatever else
suits the intended use case.
.SH THE SALT MINE
.sp
The Salt Mine is used to collect arbitrary data from minions and store it on
the master. This data is then made available to all minions via the
\fBsalt.modules.mine\fP module.
.sp
The data is gathered on the minion and sent back to the master where only
the most recent data is maintained (if long term data is required use
returners or the external job cache).
.SS Mine Functions
.sp
To enable the Salt Mine the \fImine_functions\fP option needs to be applied to a
minion. This option can be applied via the minion\(aqs configuration file, or the
minion\(aqs Pillar. The \fImine_functions\fP option dictates what functions are being
executed and allows for arguments to be passed in. If no arguments are passed,
an empty list must be added:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mine_functions:
test.ping: []
network.ip_addrs:
interface: eth0
cidr: \(aq10.0.0.0/8\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mine Functions Aliases
.sp
Function aliases can be used to provide usage intentions or to allow multiple
calls of the same function with different arguments.
.sp
New in version 2014.7.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mine_functions:
network.ip_addrs: [eth0]
networkplus.internal_ip_addrs: []
internal_ip_addrs:
mine_function: network.ip_addrs
cidr: 192.168.0.0/16
loopback_ip_addrs:
mine_function: network.ip_addrs
lo: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mine Interval
.sp
The Salt Mine functions are executed when the minion starts and at a given
interval by the scheduler. The default interval is every 60 minutes and can
be adjusted for the minion via the \fImine_interval\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mine_interval: 60
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example
.sp
One way to use data from Salt Mine is in a State. The values can be retrieved
via Jinja and used in the SLS file. The following example is a partial HAProxy
configuration file and pulls IP addresses from all minions with the "web" grain
to add them to the pool of load balanced servers.
.sp
\fB/srv/pillar/top.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqG@roles:web\(aq:
\- web
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/web.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mine_functions:
network.ip_addrs: [eth0]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/etc/salt/minion.d/mine.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mine_interval: 5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/haproxy.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
haproxy_config:
file.managed:
\- name: /etc/haproxy/config
\- source: salt://haproxy_config
\- template: jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/haproxy_config\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<...file contents snipped...>
{% for server, addrs in salt[\(aqmine.get\(aq](\(aqroles:web\(aq, \(aqnetwork.ip_addrs\(aq, expr_form=\(aqgrain\(aq).items() %}
server {{ server }} {{ addrs[0] }}:80 check
{% endfor %}
<...file contents snipped...>
.ft P
.fi
.UNINDENT
.UNINDENT
.SH EXTERNAL AUTHENTICATION SYSTEM
.sp
Salt\(aqs External Authentication System (eAuth) allows for Salt to pass through
command authorization to any external authentication system, such as PAM or LDAP.
.SS Access Control System
.sp
New in version 0.10.4.
.sp
Salt maintains a standard system used to open granular control to non
administrative users to execute Salt commands. The access control system
has been applied to all systems used to configure access to non administrative
control interfaces in Salt.These interfaces include, the \fBpeer\fP system, the
\fBexternal auth\fP system and the \fBclient acl\fP system.
.sp
The access control system mandated a standard configuration syntax used in
all of the three aforementioned systems. While this adds functionality to the
configuration in 0.10.4, it does not negate the old configuration.
.sp
Now specific functions can be opened up to specific minions from specific users
in the case of external auth and client ACLs, and for specific minions in the
case of the peer system.
.sp
The access controls are manifested using matchers in these configurations:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
client_acl:
fred:
\- web\e*:
\- pkg.list_pkgs
\- test.*
\- apache.*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the above example, fred is able to send commands only to minions which match
the specified glob target. This can be expanded to include other functions for
other minions based on standard targets.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
dave:
\- test.ping
\- mongo\e*:
\- network.*
\- log\e*:
\- network.*
\- pkg.*
\- \(aqG@os:RedHat\(aq:
\- kmod.*
steve:
\- .*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above allows for all minions to be hit by test.ping by dave, and adds a
few functions that dave can execute on other minions. It also allows steve
unrestricted access to salt commands.
.sp
The external authentication system allows for specific users to be granted
access to execute specific functions on specific minions. Access is configured
in the master configuration file and uses the \fIaccess control system\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
thatch:
\- \(aqweb*\(aq:
\- test.*
\- network.*
steve:
\- .*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above configuration allows the user \fBthatch\fP to execute functions
in the test and network modules on the minions that match the web* target.
User \fBsteve\fP is given unrestricted access to minion commands.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The PAM module does not allow authenticating as \fBroot\fP\&.
.UNINDENT
.UNINDENT
.sp
To allow access to \fIwheel modules\fP or \fIrunner
modules\fP the following \fB@\fP syntax must be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
thatch:
\- \(aq@wheel\(aq # to allow access to all wheel modules
\- \(aq@runner\(aq # to allow access to all runner modules
\- \(aq@jobs\(aq # to allow access to the jobs runner and/or wheel module
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The runner/wheel markup is different, since there are no minions to scope the
acl to.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Globs will not match wheel or runners! They must be explicitly
allowed with @wheel or @runner.
.UNINDENT
.UNINDENT
.sp
The external authentication system can then be used from the command\-line by
any user on the same system as the master with the \fB\-a\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt \-a pam web\e* test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The system will ask the user for the credentials required by the
authentication system and then publish the command.
.sp
To apply permissions to a group of users in an external authentication system,
append a \fB%\fP to the ID:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
admins%:
\- \(aq*\(aq:
\- \(aqpkg.*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Tokens
.sp
With external authentication alone, the authentication credentials will be
required with every call to Salt. This can be alleviated with Salt tokens.
.sp
Tokens are short term authorizations and can be easily created by just
adding a \fB\-T\fP option when authenticating:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt \-T \-a pam web\e* test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now a token will be created that has a expiration of 12 hours (by default).
This token is stored in a file named \fB\&.salt_token\fP in the active user\(aqs home
directory.
.sp
Once the token is created, it is sent with all subsequent communications.
User authentication does not need to be entered again until the token expires.
.sp
Token expiration time can be set in the Salt master config file.
.SS LDAP
.sp
Salt supports both user and group authentication for LDAP.
.sp
LDAP configuration happens in the Salt master configuration file.
.sp
Server configuration values:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
auth.ldap.server: localhost
auth.ldap.port: 389
auth.ldap.tls: False
auth.ldap.scope: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt also needs to know which Base DN to search for users and groups and
the DN to bind to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
auth.ldap.basedn: dc=saltstack,dc=com
auth.ldap.binddn: cn=admin,dc=saltstack,dc=com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To bind to a DN, a password is required
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
auth.ldap.bindpw: mypassword
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt users a filter to find the DN associated with a user. Salt substitutes
the \fB{{ username }}\fP value for the username when querying LDAP.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
auth.ldap.filter: uid={{ username }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If group support for LDAP is desired, one can specify an OU that contains group
data. This is prepended to the basedn to create a search path
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
auth.ldap.groupou: Groups
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once configured, LDAP permissions can be assigned to users and groups.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
ldap:
test_ldap_user:
\- \(aq*\(aq:
\- test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To configure an LDAP group, append a \fB%\fP to the ID:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
ldap:
test_ldap_group%:
\- \(aq*\(aq:
\- test.echo
.ft P
.fi
.UNINDENT
.UNINDENT
.SH JOB MANAGEMENT
.sp
New in version 0.9.7.
.sp
Since Salt executes jobs running on many systems, Salt needs to be able to
manage jobs running on many systems.
.SS The Minion proc System
.sp
Salt Minions maintain a \fIproc\fP directory in the Salt \fBcachedir\fP\&. The \fIproc\fP
directory maintains files named after the executed job ID. These files contain
the information about the current running jobs on the minion and allow for
jobs to be looked up. This is located in the \fIproc\fP directory under the
cachedir, with a default configuration it is under \fI/var/cache/salt/proc\fP\&.
.SS Functions in the saltutil Module
.sp
Salt 0.9.7 introduced a few new functions to the
\fBsaltutil\fP module for managing
jobs. These functions are:
.INDENT 0.0
.IP 1. 3
\fBrunning\fP
Returns the data of all running jobs that are found in the \fIproc\fP directory.
.IP 2. 3
\fBfind_job\fP
Returns specific data about a certain job based on job id.
.IP 3. 3
\fBsignal_job\fP
Allows for a given jid to be sent a signal.
.IP 4. 3
\fBterm_job\fP
Sends a termination signal (SIGTERM, 15) to the process controlling the
specified job.
.IP 5. 3
\fBkill_job\fP
Sends a kill signal (SIGKILL, 9) to the process controlling the
specified job.
.UNINDENT
.sp
These functions make up the core of the back end used to manage jobs at the
minion level.
.SS The jobs Runner
.sp
A convenience runner front end and reporting system has been added as well.
The jobs runner contains functions to make viewing data easier and cleaner.
.sp
The jobs runner contains a number of functions...
.SS active
.sp
The active function runs saltutil.running on all minions and formats the
return data about all running jobs in a much more usable and compact format.
The active function will also compare jobs that have returned and jobs that
are still running, making it easier to see what systems have completed a job
and what systems are still being waited on.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-run jobs.active
.ft P
.fi
.UNINDENT
.UNINDENT
.SS lookup_jid
.sp
When jobs are executed the return data is sent back to the master and cached.
By default it is cached for 24 hours, but this can be configured via the
\fBkeep_jobs\fP option in the master configuration.
Using the lookup_jid runner will display the same return data that the initial
job invocation with the salt command would display.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-run jobs.lookup_jid <job id number>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS list_jobs
.sp
Before finding a historic job, it may be required to find the job id. list_jobs
will parse the cached execution data and display all of the job data for jobs
that have already, or partially returned.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-run jobs.list_jobs
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Scheduling Jobs
.sp
In Salt versions greater than 0.12.0, the scheduling system allows incremental
executions on minions or the master. The schedule system exposes the execution
of any execution function on minions or any runner on the master.
.sp
Scheduling is enabled via the \fBschedule\fP option on either the master or minion
config files, or via a minion\(aqs pillar data.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The scheduler executes different functions on the master and minions. When
running on the master the functions reference runner functions, when
running on the minion the functions specify execution functions.
.UNINDENT
.UNINDENT
.sp
Specify \fBmaxrunning\fP to ensure that there are no more than N copies of
a particular routine running. Use this for jobs that may be long\-running
and could step on each other or otherwise double execute. The default for
\fBmaxrunning\fP is 1.
.sp
States are executed on the minion, as all states are. You can pass positional
arguments and provide a yaml dict of named arguments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
splay: 15
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) splaying the time between 0 and 15 seconds
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
splay:
start: 10
end: 15
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) splaying the time between 10 and 15 seconds
.sp
New in version 2014.7.0.
.sp
Frequency of jobs can also be specified using date strings supported by
the python dateutil library.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
args:
\- httpd
kwargs:
test: True
when: 5:00pm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True at 5:00pm minion
localtime.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
args:
\- httpd
kwargs:
test: True
when:
\- Monday 5:00pm
\- Tuesday 3:00pm
\- Wednesday 5:00pm
\- Thursday 3:00pm
\- Friday 5:00pm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True at 5pm on Monday, Wednesday
and Friday, and 3pm on Tuesday and Thursday.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
range:
start: 8:00am
end: 5:00pm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) between the hours of 8am and 5pm. The range parameter must be a
dictionary with the date strings using the dateutil format.
.sp
New in version 2014.7.0.
.sp
The scheduler also supports ensuring that there are no more than N copies of
a particular routine running. Use this for jobs that may be long\-running
and could step on each other or pile up in case of infrastructure outage.
.sp
The default for maxrunning is 1.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
long_running_job:
function: big_file_transfer
jid_include: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS States
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
log\-loadavg:
function: cmd.run
seconds: 3660
args:
\- \(aqlogger \-t salt < /proc/loadavg\(aq
kwargs:
stateful: False
shell: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Highstates
.sp
To set up a highstate to run on a minion every 60 minutes set this in the
minion config or pillar:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
highstate:
function: state.highstate
minutes: 60
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Time intervals can be specified as seconds, minutes, hours, or days.
.SS Runners
.sp
Runner executions can also be specified on the master within the master
configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
overstate:
function: state.over
seconds: 35
minutes: 30
hours: 3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above configuration will execute the state.over runner every 3 hours,
30 minutes and 35 seconds, or every 12,635 seconds.
.SS Scheduler With Returner
.sp
The scheduler is also useful for tasks like gathering monitoring data about
a minion, this schedule option will gather status data and send it to a MySQL
returner database:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
uptime:
function: status.uptime
seconds: 60
returner: mysql
meminfo:
function: status.meminfo
minutes: 5
returner: mysql
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since specifying the returner repeatedly can be tiresome, the
\fBschedule_returner\fP option is available to specify one or a list of global
returners to be used by the minions when scheduling.
In Salt versions greater than 0.12.0, the scheduling system allows incremental
executions on minions or the master. The schedule system exposes the execution
of any execution function on minions or any runner on the master.
.sp
Scheduling is enabled via the \fBschedule\fP option on either the master or minion
config files, or via a minion\(aqs pillar data.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The scheduler executes different functions on the master and minions. When
running on the master the functions reference runner functions, when
running on the minion the functions specify execution functions.
.UNINDENT
.UNINDENT
.sp
Specify \fBmaxrunning\fP to ensure that there are no more than N copies of
a particular routine running. Use this for jobs that may be long\-running
and could step on each other or otherwise double execute. The default for
\fBmaxrunning\fP is 1.
.sp
States are executed on the minion, as all states are. You can pass positional
arguments and provide a yaml dict of named arguments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
splay: 15
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) splaying the time between 0 and 15 seconds
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
splay:
start: 10
end: 15
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) splaying the time between 10 and 15 seconds
.sp
New in version 2014.7.0.
.sp
Frequency of jobs can also be specified using date strings supported by
the python dateutil library.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
args:
\- httpd
kwargs:
test: True
when: 5:00pm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True at 5:00pm minion
localtime.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
args:
\- httpd
kwargs:
test: True
when:
\- Monday 5:00pm
\- Tuesday 3:00pm
\- Wednesday 5:00pm
\- Thursday 3:00pm
\- Friday 5:00pm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True at 5pm on Monday, Wednesday
and Friday, and 3pm on Tuesday and Thursday.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
job1:
function: state.sls
seconds: 3600
args:
\- httpd
kwargs:
test: True
range:
start: 8:00am
end: 5:00pm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) between the hours of 8am and 5pm. The range parameter must be a
dictionary with the date strings using the dateutil format.
.sp
New in version 2014.7.0.
.sp
The scheduler also supports ensuring that there are no more than N copies of
a particular routine running. Use this for jobs that may be long\-running
and could step on each other or pile up in case of infrastructure outage.
.sp
The default for maxrunning is 1.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
long_running_job:
function: big_file_transfer
jid_include: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS States
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
log\-loadavg:
function: cmd.run
seconds: 3660
args:
\- \(aqlogger \-t salt < /proc/loadavg\(aq
kwargs:
stateful: False
shell: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Highstates
.sp
To set up a highstate to run on a minion every 60 minutes set this in the
minion config or pillar:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
highstate:
function: state.highstate
minutes: 60
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Time intervals can be specified as seconds, minutes, hours, or days.
.SS Runners
.sp
Runner executions can also be specified on the master within the master
configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
overstate:
function: state.over
seconds: 35
minutes: 30
hours: 3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above configuration will execute the state.over runner every 3 hours,
30 minutes and 35 seconds, or every 12,635 seconds.
.SS Scheduler With Returner
.sp
The scheduler is also useful for tasks like gathering monitoring data about
a minion, this schedule option will gather status data and send it to a MySQL
returner database:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
uptime:
function: status.uptime
seconds: 60
returner: mysql
meminfo:
function: status.meminfo
minutes: 5
returner: mysql
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since specifying the returner repeatedly can be tiresome, the
\fBschedule_returner\fP option is available to specify one or a list of global
returners to be used by the minions when scheduling.
.SH SALT EVENT SYSTEM
.sp
The Salt Event System is used to fire off events enabling third party
applications or external processes to react to behavior within Salt.
.sp
The event system is comprised of a two primary components:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
The event sockets which publishes events.
.IP \(bu 2
The event library which can listen to events and send events into the salt system.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Event types
.SS Salt Master Events
.sp
These events are fired on the Salt Master event bus. This list is \fBnot\fP
comprehensive.
.SS Authentication events
.INDENT 0.0
.TP
.B salt/auth
Fired when a minion performs an authentication check with the master.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBid\fP \-\- The minion ID.
.IP \(bu 2
\fBact\fP \-\- The current status of the minion key: \fBaccept\fP, \fBpend\fP,
\fBreject\fP\&.
.IP \(bu 2
\fBpub\fP \-\- The minion public key.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Start events
.INDENT 0.0
.TP
.B salt/minion/<MID>/start
Fired every time a minion connects to the Salt master.
.INDENT 7.0
.TP
.B Variables
\fBid\fP \-\- The minion ID.
.UNINDENT
.UNINDENT
.SS Key events
.INDENT 0.0
.TP
.B salt/key
Fired when accepting and rejecting minions keys on the Salt master.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBid\fP \-\- The minion ID.
.IP \(bu 2
\fBact\fP \-\- The new status of the minion key: \fBaccept\fP, \fBpend\fP,
\fBreject\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Job events
.INDENT 0.0
.TP
.B salt/job/<JID>/new
Fired as a new job is sent out to minions.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBjid\fP \-\- The job ID.
.IP \(bu 2
\fBtgt\fP \-\- The target of the job: \fB*\fP, a minion ID,
\fBG@os_family:RedHat\fP, etc.
.IP \(bu 2
\fBtgt_type\fP \-\- The type of targeting used: \fBglob\fP, \fBgrain\fP,
\fBcompound\fP, etc.
.IP \(bu 2
\fBfun\fP \-\- The function to run on minions: \fBtest.ping\fP,
\fBnetwork.interfaces\fP, etc.
.IP \(bu 2
\fBarg\fP \-\- A list of arguments to pass to the function that will be
called.
.IP \(bu 2
\fBminions\fP \-\- A list of minion IDs that Salt expects will return data for
this job.
.IP \(bu 2
\fBuser\fP \-\- The name of the user that ran the command as defined in Salt\(aqs
Client ACL or external auth.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/job/<JID>/ret/<MID>
Fired each time a minion returns data for a job.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBid\fP \-\- The minion ID.
.IP \(bu 2
\fBjid\fP \-\- The job ID.
.IP \(bu 2
\fBretcode\fP \-\- The return code for the job.
.IP \(bu 2
\fBfun\fP \-\- The function the minion ran. E.g., \fBtest.ping\fP\&.
.IP \(bu 2
\fBreturn\fP \-\- The data returned from the execution module.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Presence events
.INDENT 0.0
.TP
.B salt/presence/present
Events fired on a regular interval about currently connected, newly
connected, or recently disconnected minions. Requires the
\fBpresence_events\fP setting to be enabled.
.INDENT 7.0
.TP
.B Variables
\fBpresent\fP \-\- A list of minions that are currently connected to the Salt
master.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/presence/change
Fired when the Presence system detects new minions connect or disconnect.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBnew\fP \-\- A list of minions that have connected since the last presence
event.
.IP \(bu 2
\fBlost\fP \-\- A list of minions that have disconnected since the last
presence event.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Cloud Events
.sp
Unlike other Master events, \fBsalt\-cloud\fP events are not fired on behalf of a
Salt Minion. Instead, \fBsalt\-cloud\fP events are fired on behalf of a VM. This
is because the minion\-to\-be may not yet exist to fire events to or also may have
been destroyed.
.sp
This behavior is reflected by the \fBname\fP variable in the event data for
\fBsalt\-cloud\fP events as compared to the \fBid\fP variable for Salt
Minion\-triggered events.
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/creating
Fired when salt\-cloud starts the VM creation process.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- the name of the VM being created.
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBprovider\fP \-\- the cloud provider of the VM being created.
.IP \(bu 2
\fBprofile\fP \-\- the cloud profile for the VM being created.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/deploying
Fired when the VM is available and salt\-cloud begins deploying Salt to the
new VM.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- the name of the VM being created.
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBkwargs\fP \-\- options available as the deploy script is invoked:
\fBconf_file\fP, \fBdeploy_command\fP, \fBdisplay_ssh_output\fP, \fBhost\fP,
\fBkeep_tmp\fP, \fBkey_filename\fP, \fBmake_minion\fP, \fBminion_conf\fP,
\fBname\fP, \fBparallel\fP, \fBpreseed_minion_keys\fP, \fBscript\fP,
\fBscript_args\fP, \fBscript_env\fP, \fBsock_dir\fP, \fBstart_action\fP,
\fBsudo\fP, \fBtmp_dir\fP, \fBtty\fP, \fBusername\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/requesting
Fired when salt\-cloud sends the request to create a new VM.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBlocation\fP \-\- the location of the VM being requested.
.IP \(bu 2
\fBkwargs\fP \-\- options available as the VM is being requested:
\fBAction\fP, \fBImageId\fP, \fBInstanceType\fP, \fBKeyName\fP, \fBMaxCount\fP,
\fBMinCount\fP, \fBSecurityGroup.1\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/querying
Fired when salt\-cloud queries data for a new instance.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBinstance_id\fP \-\- the ID of the new VM.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/tagging
Fired when salt\-cloud tags a new instance.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBtags\fP \-\- tags being set on the new instance.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/waiting_for_ssh
Fired while the salt\-cloud deploy process is waiting for ssh to become
available on the new instance.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBip_address\fP \-\- IP address of the new instance.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/deploy_script
Fired once the deploy script is finished.
.INDENT 7.0
.TP
.B Variables
\fBevent\fP \-\- description of the event.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/created
Fired once the new instance has been fully created.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- the name of the VM being created.
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBinstance_id\fP \-\- the ID of the new instance.
.IP \(bu 2
\fBprovider\fP \-\- the cloud provider of the VM being created.
.IP \(bu 2
\fBprofile\fP \-\- the cloud profile for the VM being created.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/destroying
Fired when salt\-cloud requests the destruction of an instance.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- the name of the VM being created.
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBinstance_id\fP \-\- the ID of the new instance.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt/cloud/<VM NAME>/destroyed
Fired when an instance has been destroyed.
.INDENT 7.0
.TP
.B Variables
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- the name of the VM being created.
.IP \(bu 2
\fBevent\fP \-\- description of the event.
.IP \(bu 2
\fBinstance_id\fP \-\- the ID of the new instance.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Listening for Events
.sp
Salt\(aqs Event Bus is used heavily within Salt and it is also written to
integrate heavily with existings tooling and scripts. There is a variety of
ways to consume it.
.SS From the CLI
.sp
The quickest way to watch the event bus is by calling the \fBstate.event
runner\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.event pretty=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That runner is designed to interact with the event bus from external tools and
shell scripts. See the documentation for more examples.
.SS Remotely via the REST API
.sp
Salt\(aqs event bus can be consumed
\fBsalt.netapi.rest_cherrypy.app.Events\fP as an HTTP stream from
external tools or services.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-SsNk https://salt\-api.example.com:8000/events?token=05A3
.ft P
.fi
.UNINDENT
.UNINDENT
.SS From Python
.sp
Python scripts can access the event bus only as the same system user that Salt
is running as.
.sp
The event system is accessed via the event library and can only be accessed
by the same system user that Salt is running as. To listen to events a
SaltEvent object needs to be created and then the get_event function needs to
be run. The SaltEvent object needs to know the location that the Salt Unix
sockets are kept. In the configuration this is the \fBsock_dir\fP option. The
\fBsock_dir\fP option defaults to "/var/run/salt/master" on most systems.
.sp
The following code will check for a single event:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.config
import salt.utils.event
opts = salt.config.client_config(\(aq/etc/salt/master\(aq)
event = salt.utils.event.get_event(
\(aqmaster\(aq,
sock_dir=opts[\(aqsock_dir\(aq],
transport=opts[\(aqtransport\(aq],
opts=opts)
data = event.get_event()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Events will also use a "tag". Tags allow for events to be filtered. By
default all events will be returned. If only authentication events are
desired, then pass the tag "auth".
.sp
The \fBget_event\fP method has a default poll time assigned of 5 seconds. To
change this time set the "wait" option.
.sp
The following example will only listen for auth events and will wait for 10 seconds
instead of the default 5.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
data = event.get_event(wait=10, tag=\(aqsalt/auth\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To retrieve the tag as well as the event data, pass \fBfull=True\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
evdata = event.get_event(wait=10, tag=\(aqsalt/job\(aq, full=True)
tag, data = evdata[\(aqtag\(aq], evdata[\(aqdata\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instead of looking for a single event, the \fBiter_events\fP method can be used to
make a generator which will continually yield salt events.
.sp
The iter_events method also accepts a tag but not a wait time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.utils.event
for data in event.iter_events(tag=\(aqsalt/auth\(aq):
print(data)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And finally event tags can be globbed, such as they can be in the Reactor,
using the fnmatch library.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import fnmatch
import salt.config
import salt.utils.event
opts = salt.config.client_config(\(aq/etc/salt/master\(aq)
sevent = salt.utils.event.get_event(
\(aqmaster\(aq,
sock_dir=opts[\(aqsock_dir\(aq],
transport=opts[\(aqtransport\(aq],
opts=opts)
while True:
ret = sevent.get_event(full=True)
if ret is None:
continue
if fnmatch.fnmatch(ret[\(aqtag\(aq], \(aqsalt/job/*/ret/*\(aq):
do_something_with_job_return(ret[\(aqdata\(aq])
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Firing Events
.sp
It is possible to fire events on either the minion\(aqs local bus or to fire
events intended for the master.
.sp
To fire a local event from the minion on the command line call the
\fBevent.fire\fP execution function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call event.fire \(aq{"data": "message to be sent in the event"}\(aq \(aqtag\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To fire an event to be sent up to the master from the minion call the
\fBevent.send\fP execution function. Remember
YAML can be used at the CLI in function arguments:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call event.send \(aqmyco/mytag/success\(aq \(aq{success: True, message: "It works!"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a process is listening on the minion, it may be useful for a user on the
master to fire an event to it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname event.fire \(aq{"data": "message for the minion"}\(aq \(aqtag\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Firing Events from Python
.SS From Salt execution modules
.sp
Events can be very useful when writing execution modules, in order to inform
various processes on the master when a certain task has taken place. This is
easily done using the normal cross\-calling syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# /srv/salt/_modules/my_custom_module.py
def do_something():
\(aq\(aq\(aq
Do something and fire an event to the master when finished
CLI Example::
salt \(aq*\(aq my_custom_module:do_something
\(aq\(aq\(aq
# do something!
__salt__[\(aqevent.send\(aq](\(aqmyco/my_custom_module/finished\(aq, {
\(aqfinished\(aq: True,
\(aqmessage\(aq: "The something is finished!",
})
.ft P
.fi
.UNINDENT
.UNINDENT
.SS From Custom Python Scripts
.sp
Firing events from custom Python code is quite simple and mirrors how it is
done at the CLI:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.client
caller = salt.client.Caller()
caller.sminion.functions[\(aqevent.send\(aq](
\(aqmyco/myevent/success\(aq,
{
\(aqsuccess\(aq: True,
\(aqmessage\(aq: "It works!",
}
)
.ft P
.fi
.UNINDENT
.UNINDENT
.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 attached 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 attached to a higher level master the
configuration is very simple. On a master that is running a syndic to connect
to a higher level master the \fBsyndic_master\fP option needs to be
set in the master config file. The \fBsyndic_master\fP 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
\fBorder_masters\fP value in the configuration to \fBTrue\fP\&. The
\fBorder_masters\fP 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 \fBorder_masters\fP option makes sure that the extra data is
sent out.
.sp
To sum up, you have those configuration options available on the master side:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBsyndic_master\fP: MasterOfMaster ip/address
.IP \(bu 2
\fBsyndic_master_port\fP: MasterOfMaster ret_port
.IP \(bu 2
\fBsyndic_log_file\fP: path to the logfile (absolute or not)
.IP \(bu 2
\fBsyndic_pidfile\fP: path to the pidfile (absolute or not)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Each Syndic must provide its own \fBfile_roots\fP directory. Files will not be
automatically transferred from the master\-master.
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-syndic
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you have an exceptionally large infrastructure or many layers of
syndics, you may find that the CLI doesn\(aqt wait long enough for the syndics
to return their events. If you think this is the case, you can set the
\fBsyndic_wait\fP value in the upper master config. The default
value is \fB1\fP, and should work for the majority of deployments.
.UNINDENT
.UNINDENT
.SS Topology
.sp
The \fBsalt\-syndic\fP is little more than a command and event forwarder. When a
command is issued from a higher\-level master, it will be received by the
configured syndics on lower\-level masters, and propagated to to their minions,
and other syndics that are bound to them further down in the hierarchy. When
events and job return data are generated by minions, they aggregated back,
through the same syndic(s), to the master which issued the command.
.sp
The master sitting at the top of the hierarchy (the Master of Masters) will \fInot\fP
be running the \fBsalt\-syndic\fP daemon. It will have the \fBsalt\-master\fP
daemon running, and optionally, the \fBsalt\-minion\fP daemon. Each syndic
connected to an upper\-level master will have both the \fBsalt\-master\fP and the
\fBsalt\-syndic\fP daemon running, and optionally, the \fBsalt\-minion\fP daemon.
.sp
Nodes on the lowest points of the hierarchy (minions which do not propagate
data to another level) will only have the \fBsalt\-minion\fP daemon running. There
is no need for either \fBsalt\-master\fP or \fBsalt\-syndic\fP to be running on a
standard minion.
.SH SALT PROXY MINION DOCUMENTATION
.sp
Proxy minions are a developing Salt feature that enables controlling devices
that, for whatever reason, cannot run a standard salt\-minion. Examples include
network gear that has an API but runs a proprietary OS, devices with limited
CPU or memory, or devices that could run a minion, but for security reasons,
will not.
.sp
\fIProxy minions are not an "out of the box" feature\fP\&. Because there are an
infinite number of controllable devices, you will most likely have to write the
interface yourself. Fortunately, this is only as difficult as the actual
interface to the proxied device. Devices that have an existing Python module
(PyUSB for example) would be relatively simple to interface. Code to control a
device that has an HTML REST\-based interface should be easy. Code to control
your typical housecat would be excellent source material for a PhD thesis.
.sp
Salt proxy\-minions provide the \(aqplumbing\(aq that allows device enumeration
and discovery, control, status, remote execution, and state management.
.SS Getting Started
.sp
The following diagram may be helpful in understanding the structure of a Salt
installation that includes proxy\-minions:
[image]
.sp
The key thing to remember is the left\-most section of the diagram. Salt\(aqs
nature is to have a minion connect to a master, then the master may control
the minion. However, for proxy minions, the target device cannot run a minion,
and thus must rely on a separate minion to fire up the proxy\-minion and make the
initial and persistent connection.
.sp
After the proxy minion is started and initiates its connection to the \(aqdumb\(aq
device, it connects back to the salt\-master and ceases to be affiliated in
any way with the minion that started it.
.sp
To create support for a proxied device one needs to create four things:
.INDENT 0.0
.IP 1. 3
The \fI\%proxytype connection class\fP (located in salt/proxy).
.IP 2. 3
The \fI\%grains support code\fP (located in salt/grains).
.IP 3. 3
\fISalt modules\fP specific to the controlled
device.
.IP 4. 3
\fISalt states\fP specific to the controlled device.
.UNINDENT
.SS Configuration parameters on the master
.sp
Proxy minions require no configuration parameters in /etc/salt/master.
.sp
Salt\(aqs Pillar system is ideally suited for configuring proxy\-minions. Proxies
can either be designated via a pillar file in pillar_roots, or through an
external pillar. External pillars afford the opportunity for interfacing with
a configuration management system, database, or other knowledgeable system that
that may already contain all the details of proxy targets. To use static files
in pillar_roots, pattern your files after the following examples, which are
based on the diagram above:
.sp
\fB/srv/pillar/top.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
minioncontroller1:
\- networkswitches
minioncontroller2:
\- reallydumbdevices
minioncontroller3:
\- smsgateway
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/networkswitches.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proxy:
dumbdevice1:
proxytype: networkswitch
host: 172.23.23.5
username: root
passwd: letmein
dumbdevice2:
proxytype: networkswitch
host: 172.23.23.6
username: root
passwd: letmein
dumbdevice3:
proxytype: networkswitch
host: 172.23.23.7
username: root
passwd: letmein
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/reallydumbdevices.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proxy:
dumbdevice4:
proxytype: i2c_lightshow
i2c_address: 1
dumbdevice5:
proxytype: i2c_lightshow
i2c_address: 2
dumbdevice6:
proxytype: 433mhz_wireless
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/smsgateway.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proxy:
minioncontroller3:
dumbdevice7:
proxytype: sms_serial
deventry: /dev/tty04
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note the contents of each minioncontroller key may differ widely based on
the type of device that the proxy\-minion is managing.
.sp
In the above example
.INDENT 0.0
.IP \(bu 2
dumbdevices 1, 2, and 3 are network switches that have a management
interface available at a particular IP address.
.IP \(bu 2
dumbdevices 4 and 5 are very low\-level devices controlled over an i2c bus.
In this case the devices are physically connected to machine
\(aqminioncontroller2\(aq, and are addressable on the i2c bus at their respective
i2c addresses.
.IP \(bu 2
dumbdevice6 is a 433 MHz wireless transmitter, also physically connected to
minioncontroller2
.IP \(bu 2
dumbdevice7 is an SMS gateway connected to machine minioncontroller3 via a
serial port.
.UNINDENT
.sp
Because of the way pillar works, each of the salt\-minions that fork off the
proxy minions will only see the keys specific to the proxies it will be
handling. In other words, from the above example, only minioncontroller1 will
see the connection information for dumbdevices 1, 2, and 3. Minioncontroller2
will see configuration data for dumbdevices 4, 5, and 6, and minioncontroller3
will be privy to dumbdevice7.
.sp
Also, in general, proxy\-minions are lightweight, so the machines that run them
could conceivably control a large number of devices. The example above is just
to illustrate that it is possible for the proxy services to be spread across
many machines if necessary, or intentionally run on machines that need to
control devices because of some physical interface (e.g. i2c and serial above).
Another reason to divide proxy services might be security. In more secure
environments only certain machines may have a network path to certain devices.
.sp
Now our salt\-minions know if they are supposed to spawn a proxy\-minion process
to control a particular device. That proxy\-minion process will initiate
a connection back to the master to enable control.
.SS Proxytypes
.sp
A proxytype is a Python class called \(aqProxyconn\(aq that encapsulates all the code
necessary to interface with a device. Proxytypes are located inside the
salt.proxy module. At a minimum a proxytype object must implement the
following methods:
.sp
\fBproxytype(self)\fP: Returns a string with the name of the proxy type.
.sp
\fBproxyconn(self, **kwargs)\fP: Provides the primary way to connect and communicate
with the device. Some proxyconns instantiate a particular object that opens a
network connection to a device and leaves the connection open for communication.
Others simply abstract a serial connection or even implement endpoints to communicate
via REST over HTTP.
.sp
\fBid(self, opts)\fP: Returns a unique, unchanging id for the controlled device. This is
the "name" of the device, and is used by the salt\-master for targeting and key
authentication.
.sp
Optionally, the class may define a \fBshutdown(self, opts)\fP method if the
controlled device should be informed when the minion goes away cleanly.
.sp
It is highly recommended that the \fBtest.ping\fP execution module also be defined
for a proxytype. The code for \fBping\fP should contact the controlled device and make
sure it is really available.
.sp
Here is an example proxytype used to interface to Juniper Networks devices that run
the Junos operating system. Note the additional library requirements\-\-most of the
"hard part" of talking to these devices is handled by the jnpr.junos, jnpr.junos.utils
and jnpr.junos.cfg modules.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Import python libs
import logging
import os
import jnpr.junos
import jnpr.junos.utils
import jnpr.junos.cfg
HAS_JUNOS = True
class Proxyconn(object):
def __init__(self, details):
self.conn = jnpr.junos.Device(user=details[\(aqusername\(aq], host=details[\(aqhost\(aq], password=details[\(aqpasswd\(aq])
self.conn.open()
self.conn.bind(cu=jnpr.junos.cfg.Resource)
def proxytype(self):
return \(aqjunos\(aq
def id(self, opts):
return self.conn.facts[\(aqhostname\(aq]
def ping(self):
return self.conn.connected
def shutdown(self, opts):
print(\(aqProxy module {} shutting down!!\(aq.format(opts[\(aqid\(aq]))
try:
self.conn.close()
except Exception:
pass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Grains are data about minions. Most proxied devices will have a paltry amount
of data as compared to a typical Linux server. Because proxy\-minions are
started by a regular minion, they inherit a sizeable number of grain settings
which can be useful, especially when targeting (PYTHONPATH, for example).
.sp
All proxy minions set a grain called \(aqproxy\(aq. If it is present, you know the
minion is controlling another device. To add more grains to your proxy minion
for a particular device, create a file in salt/grains named [proxytype].py and
place inside it the different functions that need to be run to collect the data
you are interested in. Here\(aqs an example:
.SS The __proxyenabled__ directive
.sp
Salt states and execution modules, by and large, cannot "automatically" work
with proxied devices. Execution modules like \fBpkg\fP or \fBsqlite3\fP have no
meaning on a network switch or a housecat. For a state/execution module to be
available to a proxy\-minion, the \fB__proxyenabled__\fP variable must be defined
in the module as an array containing the names of all the proxytypes that this
module can support. The array can contain the special value \fB*\fP to indicate
that the module supports all proxies.
.sp
If no \fB__proxyenabled__\fP variable is defined, then by default, the
state/execution module is unavailable to any proxy.
.sp
Here is an excerpt from a module that was modified to support proxy\-minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def ping():
if \(aqproxyobject\(aq in __opts__:
if \(aqping\(aq in __opts__[\(aqproxyobject\(aq].__attr__():
return __opts[\(aqproxyobject\(aq].ping()
else:
return False
else:
return True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And then in salt.proxy.junos we find
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def ping(self):
return self.connected
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Junos API layer lacks the ability to do a traditional \(aqping\(aq, so the
example simply checks the connection object field that indicates
if the ssh connection was successfully made to the device.
.SH WINDOWS SOFTWARE REPOSITORY
.sp
The Salt Windows Software Repository provides a package manager and software
repository similar to what is provided by yum and apt on Linux.
.sp
It permits the installation of software using the installers on remote
windows machines. In many senses, the operation is similar to that of
the other package managers salt is aware of:
.INDENT 0.0
.IP \(bu 2
the \fBpkg.installed\fP and similar states work on Windows.
.IP \(bu 2
the \fBpkg.install\fP and similar module functions work on Windows.
.IP \(bu 2
each windows machine needs to have \fBpkg.refresh_db\fP executed
against it to pick up the latest version of the package database.
.UNINDENT
.sp
High level differences to yum and apt are:
.INDENT 0.0
.IP \(bu 2
The repository metadata (sls files) is hosted through either salt or
git.
.IP \(bu 2
Packages can be downloaded from within the salt repository, a git
repository or from http(s) or ftp urls.
.IP \(bu 2
No dependencies are managed. Dependencies between packages needs to
be managed manually.
.UNINDENT
.SS Operation
.sp
The install state/module function of the windows package manager works
roughly as follows:
.INDENT 0.0
.IP 1. 3
Execute \fBpkg.list_pkgs\fP and store the result
.IP 2. 3
Check if any action needs to be taken. (i.e. compare required package
and version against \fBpkg.list_pkgs\fP results)
.IP 3. 3
If so, run the installer command.
.IP 4. 3
Execute \fBpkg.list_pkgs\fP and compare to the result stored from
before installation.
.IP 5. 3
Success/Failure/Changes will be reported based on the differences
between the original and final \fBpkg.list_pkgs\fP results.
.UNINDENT
.sp
If there are any problems in using the package manager it is likely to
be due to the data in your sls files not matching the difference
between the pre and post \fBpkg.list_pkgs\fP results.
.SS Usage
.sp
By default, the Windows software repository is found at \fB/srv/salt/win/repo\fP
This can be changed in the master config file (default location is
\fB/etc/salt/master\fP) by modifying the \fBwin_repo\fP variable. Each piece of
software should have its own directory which contains the installers and a
package definition file. This package definition file is a YAML file named
\fBinit.sls\fP\&.
.sp
The package definition file should look similar to this example for Firefox:
\fB/srv/salt/win/repo/firefox/init.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Firefox:
17.0.1:
installer: \(aqsalt://win/repo/firefox/English/Firefox Setup 17.0.1.exe\(aq
full_name: Mozilla Firefox 17.0.1 (x86 en\-US)
locale: en_US
reboot: False
install_flags: \(aq \-ms\(aq
uninstaller: \(aq%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe\(aq
uninstall_flags: \(aq /S\(aq
16.0.2:
installer: \(aqsalt://win/repo/firefox/English/Firefox Setup 16.0.2.exe\(aq
full_name: Mozilla Firefox 16.0.2 (x86 en\-US)
locale: en_US
reboot: False
install_flags: \(aq \-ms\(aq
uninstaller: \(aq%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe\(aq
uninstall_flags: \(aq /S\(aq
15.0.1:
installer: \(aqsalt://win/repo/firefox/English/Firefox Setup 15.0.1.exe\(aq
full_name: Mozilla Firefox 15.0.1 (x86 en\-US)
locale: en_US
reboot: False
install_flags: \(aq \-ms\(aq
uninstaller: \(aq%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe\(aq
uninstall_flags: \(aq /S\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
More examples can be found here: \fI\%https://github.com/saltstack/salt\-winrepo\fP
.sp
The version number and \fBfull_name\fP need to match the output from \fBpkg.list_pkgs\fP
so that the status can be verified when running highstate.
Note: It is still possible to successfully install packages using \fBpkg.install\fP
even if they don\(aqt match which can make this hard to troubleshoot.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqtest\-2008\(aq pkg.list_pkgs
test\-2008
\-\-\-\-\-\-\-\-\-\-
7\-Zip 9.20 (x64 edition):
9.20.00.0
Microsoft .NET Framework 4 Client Profile:
4.0.30319,4.0.30319
Microsoft .NET Framework 4 Extended:
4.0.30319,4.0.30319
Microsoft Visual C++ 2008 Redistributable \- x64 9.0.21022:
9.0.21022
Mozilla Firefox 17.0.1 (x86 en\-US):
17.0.1
Mozilla Maintenance Service:
17.0.1
NSClient++ (x64):
0.3.8.76
Notepad++:
6.4.2
Salt Minion 0.16.0:
0.16.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If any of these preinstalled packages already exist in winrepo the full_name
will be automatically renamed to their package name during the next update
(running highstate or installing another package).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
test\-2008:
\-\-\-\-\-\-\-\-\-\-
7zip:
9.20.00.0
Microsoft .NET Framework 4 Client Profile:
4.0.30319,4.0.30319
Microsoft .NET Framework 4 Extended:
4.0.30319,4.0.30319
Microsoft Visual C++ 2008 Redistributable \- x64 9.0.21022:
9.0.21022
Mozilla Maintenance Service:
17.0.1
Notepad++:
6.4.2
Salt Minion 0.16.0:
0.16.0
firefox:
17.0.1
nsclient:
0.3.9.328
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Add \fBmsiexec: True\fP if using an MSI installer requiring the use of \fBmsiexec
/i\fP to install and \fBmsiexec /x\fP to uninstall.
.sp
The \fBinstall_flags\fP and \fBuninstall_flags\fP are flags passed to the software
installer to cause it to perform a silent install. These can often be found by
adding \fB/?\fP or \fB/h\fP when running the installer from the command line. A
great resource for finding these silent install flags can be found on the WPKG
project\(aqs \fI\%wiki\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
7zip:
9.20.00.0:
installer: salt://win/repo/7zip/7z920\-x64.msi
full_name: 7\-Zip 9.20 (x64 edition)
reboot: False
install_flags: \(aq /q \(aq
msiexec: True
uninstaller: salt://win/repo/7zip/7z920\-x64.msi
uninstall_flags: \(aq /qn\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Generate Repo Cache File
.sp
Once the sls file has been created, generate the repository cache file with the winrepo runner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run winrepo.genrepo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then update the repository cache file on your minions, exactly how it\(aqs done for the Linux package managers:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Install Windows Software
.sp
Now you can query the available version of Firefox using the Salt pkg module.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.available_version Firefox
{\(aqFirefox\(aq: {\(aq15.0.1\(aq: \(aqMozilla Firefox 15.0.1 (x86 en\-US)\(aq,
\(aq16.0.2\(aq: \(aqMozilla Firefox 16.0.2 (x86 en\-US)\(aq,
\(aq17.0.1\(aq: \(aqMozilla Firefox 17.0.1 (x86 en\-US)\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As you can see, there are three versions of Firefox available for installation.
You can refer a software package by its \fBname\fP or its \fBfull_name\fP surround
by single quotes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install \(aqFirefox\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above line will install the latest version of Firefox.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install \(aqFirefox\(aq version=16.0.2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above line will install version 16.0.2 of Firefox.
.sp
If a different version of the package is already installed it will
be replaced with the version in winrepo (only if the package itself supports
live updating).
.sp
You can also specify the full name:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install \(aqMozilla Firefox 17.0.1 (x86 en\-US)\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Uninstall Windows Software
.sp
Uninstall software using the pkg module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove \(aqFirefox\(aq
salt \(aq*\(aq pkg.purge \(aqFirefox\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBpkg.purge\fP just executes \fBpkg.remove\fP on Windows. At some point in the
future \fBpkg.purge\fP may direct the installer to remove all configs and
settings for software packages that support that option.
.SS Standalone Minion Salt Windows Repo Module
.sp
In order to facilitate managing a Salt Windows software repo with Salt on a
Standalone Minion on Windows, a new module named winrepo has been added to
Salt. winrepo matches what is available in the salt runner and allows you to
manage the Windows software repo contents. Example: \fBsalt \(aq*\(aq
winrepo.genrepo\fP
.SS Git Hosted Repo
.sp
Windows software package definitions can also be hosted in one or more git
repositories. The default repo is one hosted on Github.com by SaltStack,Inc., which
includes package definitions for open source software. This repo points to the
HTTP or ftp locations of the installer files. Anyone is welcome to send a pull
request to this repo to add new package definitions. Browse the repo
here: \fI\%https://github.com/saltstack/salt\-winrepo\fP .
.sp
Configure which git repos the master can search for package definitions by
modifying or extending the \fBwin_gitrepos\fP configuration option list in the
master config.
.sp
Checkout each git repo in \fBwin_gitrepos\fP, compile your package repository
cache and then refresh each minion\(aqs package cache:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run winrepo.update_git_repos
salt\-run winrepo.genrepo
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Troubleshooting
.SS Incorrect name/version
.sp
If the package seems to install properly, but salt reports a failure
then it is likely you have a version or \fBfull_name\fP mismatch.
.sp
Check the exact \fBfull_name\fP and version used by the package. Use
\fBpkg.list_pkgs\fP to check that the names and version exactly match
what is installed.
.SS Changes to sls files not being picked up
.sp
Ensure you have (re)generated the repository cache file and then
updated the repository cache on the relevant minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run winrepo.genrepo
salt \(aqMINION\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Packages management under Windows 2003
.sp
On windows server 2003, you need to install optional windows component
"wmi windows installer provider" to have full list of installed packages.
If you don\(aqt have this, salt\-minion can\(aqt report some installed software.
.SH WINDOWS-SPECIFIC BEHAVIOUR
.sp
Salt is capable of managing Windows systems, however due to various differences
between the operating systems, there are some things you need to keep in mind.
.sp
This document will contain any quirks that apply across Salt or generally across
multiple module functions. Any Windows\-specific behavior for particular module
functions will be documented in the module function documentation. Therefore
this document should be read in conjunction with the module function
documentation.
.SS Group parameter for files
.sp
Salt was originally written for managing Unix\-based systems, and therefore the
file module functions were designed around that security model. Rather than
trying to shoehorn that model on to Windows, Salt ignores these parameters and
makes non\-applicable module functions unavailable instead.
.sp
One of the commonly ignored parameters is the \fBgroup\fP parameter for managing
files. Under Windows, while files do have a \(aqprimary group\(aq property, this is
rarely used. It generally has no bearing on permissions unless intentionally
configured and is most commonly used to provide Unix compatibility (e.g.
Services For Unix, NFS services).
.sp
Because of this, any file module functions that typically require a group, do
not under Windows. Attempts to directly use file module functions that operate
on the group (e.g. \fBfile.chgrp\fP) will return a pseudo\-value and cause a log
message to appear. No group parameters will be acted on.
.sp
If you do want to access and change the \(aqprimary group\(aq property and understand
the implications, use the \fBfile.get_pgid\fP or \fBfile.get_pgroup\fP functions or
the \fBpgroup\fP parameter on the \fBfile.chown\fP module function.
.SS Dealing with case\-insensitive but case\-preserving names
.sp
Windows is case\-insensitive, but however preserves the case of names and it is
this preserved form that is returned from system functions. This causes some
issues with Salt because it assumes case\-sensitive names. These issues
generally occur in the state functions and can cause bizarre looking errors.
.sp
To avoid such issues, always pretend Windows is case\-sensitive and use the right
case for names, e.g. specify \fBuser=Administrator\fP instead of
\fBuser=administrator\fP\&.
.sp
Follow \fI\%issue 11801\fP for any changes to this behavior.
.SS Dealing with various username forms
.sp
Salt does not understand the various forms that Windows usernames can come in,
e.g. username, mydomainusername, \fI\%username@mydomain.tld\fP can all refer to the
same user. In fact, Salt generally only considers the raw username value, i.e.
the username without the domain or host information.
.sp
Using these alternative forms will likely confuse Salt and cause odd errors to
happen. Use only the raw username value in the correct case to avoid problems.
.sp
Follow \fI\%issue 11801\fP for any changes to this behavior.
.SS Specifying the None group
.sp
Each Windows system has built\-in _None_ group. This is the default \(aqprimary
group\(aq for files for users not on a domain environment.
.sp
Unfortunately, the word _None_ has special meaning in Python \- it is a special
value indicating \(aqnothing\(aq, similar to \fBnull\fP or \fBnil\fP in other languages.
.sp
To specify the None group, it must be specified in quotes, e.g.
\fB\&./salt \(aq*\(aq file.chpgrp C:\epath\eto\efile "\(aqNone\(aq"\fP\&.
.SS Symbolic link loops
.sp
Under Windows, if any symbolic link loops are detected or if there are too many
levels of symlinks (defaults to 64), an error is always raised.
.sp
For some functions, this behavior is different to the behavior on Unix
platforms. In general, avoid symlink loops on either platform.
.SS Modifying security properties (ACLs) on files
.sp
There is no support in Salt for modifying ACLs, and therefore no support for
changing file permissions, besides modifying the owner/user.
.SH SALT CLOUD
.SS Getting Started
.SS Install Salt Cloud
.sp
Salt Cloud is now part of Salt proper. It was merged in as of
\fBSalt version 2014.1.0\fP\&.
.sp
On Ubuntu, install Salt Cloud by using following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo add\-apt\-repository ppa:saltstack/salt
sudo apt\-get install salt\-cloud
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If using Salt Cloud on OS X, \fBcurl\-ca\-bundle\fP must be installed. Presently,
this package is not available via \fBbrew\fP, but it is available using MacPorts:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo port install curl\-ca\-bundle
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt Cloud depends on \fBapache\-libcloud\fP\&. Libcloud can be installed via pip
with \fBpip install apache\-libcloud\fP\&.
.SS Installing Salt Cloud for development
.sp
Installing Salt for development enables Salt Cloud development as well, just
make sure \fBapache\-libcloud\fP is installed as per above paragraph.
.sp
See these instructions: \fBInstalling Salt for development\fP\&.
.SS Using Salt Cloud
.SS Salt Cloud basic usage
.sp
Salt Cloud needs, at least, one configured
\fIProvider\fP
and \fBProfile\fP to be functional.
.SS Creating a VM
.sp
To create a VM with salt cloud, use command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p <profile> name_of_vm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Assuming there is a profile configured as following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fedora_rackspace:
provider: rackspace
image: Fedora 17
size: 256 server
script: bootstrap\-salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, the command to create new VM named \fBfedora_http_01\fP is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p fedora_rackspace fedora_http_01
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Destroying a VM
.sp
To destroy a created\-by\-salt\-cloud VM, use command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-d name_of_vm
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For example, to delete the VM created on above example, use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-d fedora_http_01
.ft P
.fi
.UNINDENT
.UNINDENT
.SS VM Profiles
.sp
Salt cloud designates virtual machines inside the profile configuration file.
The profile configuration file defaults to \fB/etc/salt/cloud.profiles\fP and is
a yaml configuration. The syntax for declaring profiles is simple:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fedora_rackspace:
provider: rackspace
image: Fedora 17
size: 256 server
script: bootstrap\-salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It should be noted that the \fBscript\fP option defaults to \fBbootstrap\-salt\fP,
and does not normally need to be specified. Further examples in this document
will not show the \fBscript\fP option.
.sp
A few key pieces of information need to be declared and can change based on the
public cloud provider. A number of additional parameters can also be inserted:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
centos_rackspace:
provider: rackspace
image: CentOS 6.2
size: 1024 server
minion:
master: salt.example.com
append_domain: webs.example.com
grains:
role: webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The image must be selected from available images. Similarly, sizes must be
selected from the list of sizes. To get a list of available images and sizes
use the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-images openstack
salt\-cloud \-\-list\-sizes openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Some parameters can be specified in the main Salt cloud configuration file and
then are applied to all cloud profiles. For instance if only a single cloud
provider is being used then the provider option can be declared in the Salt
cloud configuration file.
.SS Multiple Configuration Files
.sp
In addition to \fB/etc/salt/cloud.profiles\fP, profiles can also be specified in
any file matching \fBcloud.profiles.d/*conf\fP which is a sub\-directory relative
to the profiles configuration file(with the above configuration file as an
example, \fB/etc/salt/cloud.profiles.d/*.conf\fP). This allows for more
extensible configuration, and plays nicely with various configuration
management tools as well as version control systems.
.SS Larger Example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rhel_ec2:
provider: ec2
image: ami\-e565ba8c
size: Micro Instance
minion:
cheese: edam
ubuntu_ec2:
provider: ec2
image: ami\-7e2da54e
size: Micro Instance
minion:
cheese: edam
ubuntu_rackspace:
provider: rackspace
image: Ubuntu 12.04 LTS
size: 256 server
minion:
cheese: edam
fedora_rackspace:
provider: rackspace
image: Fedora 17
size: 256 server
minion:
cheese: edam
cent_linode:
provider: linode
image: CentOS 6.2 64bit
size: Linode 512
cent_gogrid:
provider: gogrid
image: 12834
size: 512MB
cent_joyent:
provider: joyent
image: centos\-6
size: Small 1GB
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cloud Map File
.sp
A number of options exist when creating virtual machines. They can be managed
directly from profiles and the command line execution, or a more complex map
file can be created. The map file allows for a number of virtual machines to
be created and associated with specific profiles.
.sp
Map files have a simple format, specify a profile and then a list of virtual
machines to make from said profile:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fedora_small:
\- web1
\- web2
\- web3
fedora_high:
\- redis1
\- redis2
\- redis3
cent_high:
\- riak1
\- riak2
\- riak3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This map file can then be called to roll out all of these virtual machines. Map
files are called from the salt\-cloud command with the \-m option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-m /path/to/mapfile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Remember, that as with direct profile provisioning the \-P option can be passed
to create the virtual machines in parallel:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-m /path/to/mapfile \-P
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A map file can also be enforced to represent the total state of a cloud
deployment by using the \fB\-\-hard\fP option. When using the hard option any vms
that exist but are not specified in the map file will be destroyed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-m /path/to/mapfile \-P \-H
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Be careful with this argument, it is very dangerous! In fact, it is so
dangerous that in order to use it, you must explicitly enable it in the main
configuration file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
enable_hard_maps: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A map file can include grains and minion configuration options:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fedora_small:
\- web1:
minion:
log_level: debug
grains:
cheese: tasty
omelet: du fromage
\- web2:
minion:
log_level: warn
grains:
cheese: more tasty
omelet: with peppers
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A map file may also be used with the various query options:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-m /path/to/mapfile \-Q
{\(aqec2\(aq: {\(aqweb1\(aq: {\(aqid\(aq: \(aqi\-e6aqfegb\(aq,
\(aqimage\(aq: None,
\(aqprivate_ips\(aq: [],
\(aqpublic_ips\(aq: [],
\(aqsize\(aq: None,
\(aqstate\(aq: 0}},
\(aqweb2\(aq: {\(aqAbsent\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\&...or with the delete option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-m /path/to/mapfile \-d
The following virtual machines are set to be destroyed:
web1
web2
Proceed? [N/y]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting up New Salt Masters
.sp
Bootstrapping a new master in the map is as simple as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fedora_small:
\- web1:
make_master: True
\- web2
\- web3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice that \fBALL\fP bootstrapped minions from the map will answer to the newly
created salt\-master.
.sp
To make any of the bootstrapped minions answer to the bootstrapping salt\-master
as opposed to the newly created salt\-master, as an example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fedora_small:
\- web1:
make_master: True
minion:
master: <the local master ip address>
local_master: True
\- web2
\- web3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above says the minion running on the newly created salt\-master responds to
the local master, ie, the master used to bootstrap these VMs.
.sp
Another example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fedora_small:
\- web1:
make_master: True
\- web2
\- web3:
minion:
master: <the local master ip address>
local_master: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above example makes the \fBweb3\fP minion answer to the local master, not the
newly created master.
.SS Cloud Actions
.sp
Once a VM has been created, there are a number of actions that can be performed
on it. The "reboot" action can be used across all providers, but all other
actions are specific to the cloud provider. In order to perform an action, you
may specify it from the command line, including the name(s) of the VM to
perform the action on:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-a reboot vm_name
$ salt\-cloud \-a reboot vm1 vm2 vm2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or you may specify a map which includes all VMs to perform the action on:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-a reboot \-m /path/to/mapfile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following is a list of actions currently supported by salt\-cloud:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
all providers:
\- reboot
ec2:
\- start
\- stop
joyent:
\- stop
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cloud Functions
.sp
Cloud functions work much the same way as cloud actions, except that they don\(aqt
perform an operation on a specific instance, and so do not need a machine name
to be specified. However, since they perform an operation on a specific cloud
provider, that provider must be specified.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-f show_image ec2 image=ami\-fd20ad94
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Core Configuration
.SS Core Configuration
.sp
A number of core configuration options and some options that are global to the
VM profiles can be set in the cloud configuration file. By default this file is
located at \fB/etc/salt/cloud\fP\&.
.SS Thread Pool Size
.sp
When salt cloud is operating in parallel mode via the \fB\-P\fP argument, you can
control the thread pool size by specifying the \fBpool_size\fP parameter with
a positive integer value.
.sp
By default, the thread pool size will be set to the number of VMs that salt
cloud is operating on.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pool_size: 10
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Minion Configuration
.sp
The default minion configuration is set up in this file. Minions created by
salt\-cloud derive their configuration from this file. Almost all parameters
found in \fIConfiguring the Salt Minion\fP can
be used here.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
minion:
master: saltmaster.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In particular, this is the location to specify the location of the salt master
and its listening port, if the port is not set to the default.
.SS New Cloud Configuration Syntax
.sp
The data specific to interacting with public clouds is set up here.
.sp
\fBATTENTION\fP: Since version 0.8.7 a new cloud provider configuration syntax
was implemented. It will allow for multiple configurations of the same cloud
provider where only minor details can change, for example, the region for an
EC2 instance. While the old format is still supported and automatically
migrated every time salt\-cloud configuration is parsed, a choice was made to
warn the user or even exit with an error if both formats are mixed.
.SS Migrating Configurations
.sp
If you wish to migrate, there are several alternatives. Since the old syntax
was mainly done on the main cloud configuration file, see the next before and
after migration example.
.INDENT 0.0
.IP \(bu 2
Before migration in \fB/etc/salt/cloud\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
AWS.id: HJGRYCILJLKJYG
AWS.key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
AWS.keyname: test
AWS.securitygroup: quick\-start
AWS.private_key: /root/test.pem
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
After migration in \fB/etc/salt/cloud\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
providers:
my\-aws\-migrated\-config:
id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
keyname: test
securitygroup: quick\-start
private_key: /root/test.pem
provider: aws
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice that it\(aqs no longer required to name a cloud provider\(aqs configuration
after its provider; it can be an alias, though an additional configuration
key is added, \fBprovider\fP\&. This allows for multiple configuration for the same
cloud provider to coexist.
.sp
While moving towards an improved and extensible configuration handling
regarding the cloud providers, \fB\-\-providers\-config\fP, which defaults to
\fB/etc/salt/cloud.providers\fP, was added to the cli parser. It allows for the
cloud providers configuration to be provided in a different file, and/or even
any matching file on a sub\-directory, \fBcloud.providers.d/*.conf\fP which is
relative to the providers configuration file(with the above configuration file
as an example, \fB/etc/salt/cloud.providers.d/*.conf\fP).
.sp
So, using the example configuration above, after migration in
\fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/aws\-migrated.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-aws\-migrated\-config:
id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
keyname: test
securitygroup: quick\-start
private_key: /root/test.pem
provider: aws
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice that on this last migrated example, it \fBno longer\fP includes the
\fBproviders\fP starting key.
.sp
While migrating the cloud providers configuration, if the provider alias (from
the above example \fBmy\-aws\-migrated\-config\fP) changes from what you had (from
the above example \fBaws\fP), you will also need to change the \fBprovider\fP
configuration key in the defined profiles.
.INDENT 0.0
.IP \(bu 2
From:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rhel_aws:
provider: aws
image: ami\-e565ba8c
size: Micro Instance
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
To:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rhel_aws:
provider: my\-aws\-migrated\-config
image: ami\-e565ba8c
size: Micro Instance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This new configuration syntax even allows you to have multiple cloud
configurations under the same alias, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
production\-config:
\- id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
keyname: test
securitygroup: quick\-start
private_key: /root/test.pem
\- user: example_user
apikey: 123984bjjas87034
provider: rackspace
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNotice the dash and indentation on the above example.\fP
.sp
Having multiple entries for a configuration alias also makes the \fBprovider\fP
key on any defined profile to change, see the example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rhel_aws_dev:
provider: production\-config:aws
image: ami\-e565ba8c
size: Micro Instance
rhel_aws_prod:
provider: production\-config:aws
image: ami\-e565ba8c
size: High\-CPU Extra Large Instance
database_prod:
provider: production\-config:rackspace
image: Ubuntu 12.04 LTS
size: 256 server
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice that because of the multiple entries, one has to be explicit about the
provider alias and name, from the above example, \fBproduction\-config:aws\fP\&.
.sp
This new syntax also changes the interaction with the \fBsalt\-cloud\fP binary.
\fB\-\-list\-location\fP, \fB\-\-list\-images\fP and \fB\-\-list\-sizes\fP which needs a cloud
provider as an argument. Since 0.8.7 the argument used should be the configured
cloud provider alias. If the provider alias only has a single entry, use
\fB<provider\-alias>\fP\&. If it has multiple entries,
\fB<provider\-alias>:<provider\-name>\fP should be used.
.SS Pillar Configuration
.sp
It is possible to configure cloud providers using pillars. This is only used
when inside the cloud module. You can setup a variable called \fBclouds\fP that
contains your profile and provider to pass that information to the cloud
servers instead of having to copy the full configuration to every minion.
.sp
In your pillar file, you would use something like this.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cloud:
ssh_key_name: saltstack
ssh_key_file: /root/.ssh/id_rsa
update_cachedir: True
diff_cache_events: True
change_password: True
providers:
my\-nova:
identity_url: https://identity.api.rackspacecloud.com/v2.0/
compute_region: IAD
user: myuser
api_key: apikey
tenant: 123456
provider: nova
my\-openstack:
identity_url: https://identity.api.rackspacecloud.com/v2.0/tokens
user: user2
apikey: apikey2
tenant: 654321
compute_region: DFW
provider: openstack
compute_name: cloudServersOpenStack
profiles:
ubuntu\-nova:
provider: my\-nova
size: performance1\-8
image: bb02b1a3\-bc77\-4d17\-ab5b\-421d89850fca
script_args: git develop
flush_mine_on_destroy: True
ubuntu\-openstack:
provider: my\-openstack
size: performance1\-8
image: bb02b1a3\-bc77\-4d17\-ab5b\-421d89850fca
script_args: git develop
flush_mine_on_destroy: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: This is only valid in the cloud module, so also in the cloud state.
This does not work with the salt\-cloud binary.
.SS Cloud Configurations
.SS Rackspace
.sp
Rackspace cloud requires two configuration options:
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
RACKSPACE.user: example_user
RACKSPACE.apikey: 123984bjjas87034
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-rackspace\-config:
user: example_user
apikey: 123984bjjas87034
provider: rackspace
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider:
rackspace\-config\fP instead of \fBprovider: rackspace\fP on a profile
configuration.
.SS Amazon AWS
.sp
A number of configuration options are required for Amazon AWS:
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
AWS.id: HJGRYCILJLKJYG
AWS.key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
AWS.keyname: test
AWS.securitygroup: quick\-start
AWS.private_key: /root/test.pem
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-aws\-quick\-start:
id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
keyname: test
securitygroup: quick\-start
private_key: /root/test.pem
provider: aws
my\-aws\-default:
id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
keyname: test
securitygroup: default
private_key: /root/test.pem
provider: aws
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have
\fBprovider: my\-aws\-quick\-start\fP or \fBprovider: my\-aws\-default\fP instead of
\fBprovider: aws\fP on a profile configuration.
.SS Linode
.sp
Linode requires a single API key, but the default root password also needs to
be set:
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
LINODE.apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf
LINODE.password: F00barbaz
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-linode\-config:
apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf
password: F00barbaz
provider: linode
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have
\fBprovider: my\-linode\-config\fP instead of \fBprovider: linode\fP on a profile
configuration.
.sp
The password needs to be 8 characters and contain lowercase, uppercase and
numbers.
.SS Joyent Cloud
.sp
The Joyent cloud requires three configuration parameters. The username and
password that are used to log into the Joyent system, and the location of the
private SSH key associated with the Joyent account. The SSH key is needed to
send the provisioning commands up to the freshly created virtual machine.
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
JOYENT.user: fred
JOYENT.password: saltybacon
JOYENT.private_key: /root/joyent.pem
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-joyent\-config:
user: fred
password: saltybacon
private_key: /root/joyent.pem
provider: joyent
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have
\fBprovider: my\-joyent\-config\fP instead of \fBprovider: joyent\fP on a profile
configuration.
.SS GoGrid
.sp
To use Salt Cloud with GoGrid log into the GoGrid web interface and create an
API key. Do this by clicking on "My Account" and then going to the API Keys
tab.
.sp
The GOGRID.apikey and the GOGRID.sharedsecret configuration parameters need to
be set in the configuration file to enable interfacing with GoGrid:
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
GOGRID.apikey: asdff7896asdh789
GOGRID.sharedsecret: saltybacon
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-gogrid\-config:
apikey: asdff7896asdh789
sharedsecret: saltybacon
provider: gogrid
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have
\fBprovider: my\-gogrid\-config\fP instead of \fBprovider: gogrid\fP on a profile
configuration.
.SS OpenStack
.sp
OpenStack configuration differs between providers, and at the moment several
options need to be specified. This module has been officially tested against
the HP and the Rackspace implementations, and some examples are provided for
both.
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# For HP
OPENSTACK.identity_url: \(aqhttps://region\-a.geo\-1.identity.hpcloudsvc.com:35357/v2.0/\(aq
OPENSTACK.compute_name: Compute
OPENSTACK.compute_region: \(aqaz\-1.region\-a.geo\-1\(aq
OPENSTACK.tenant: myuser\-tenant1
OPENSTACK.user: myuser
OPENSTACK.ssh_key_name: mykey
OPENSTACK.ssh_key_file: \(aq/etc/salt/hpcloud/mykey.pem\(aq
OPENSTACK.password: mypass
# For Rackspace
OPENSTACK.identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/tokens\(aq
OPENSTACK.compute_name: cloudServersOpenStack
OPENSTACK.protocol: ipv4
OPENSTACK.compute_region: DFW
OPENSTACK.protocol: ipv4
OPENSTACK.user: myuser
OPENSTACK.tenant: 5555555
OPENSTACK.password: mypass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have an API key for your provider, it may be specified instead of a
password:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
OPENSTACK.apikey: 901d3f579h23c8v73q9
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# For HP
my\-openstack\-hp\-config:
identity_url:
\(aqhttps://region\-a.geo\-1.identity.hpcloudsvc.com:35357/v2.0/\(aq
compute_name: Compute
compute_region: \(aqaz\-1.region\-a.geo\-1\(aq
tenant: myuser\-tenant1
user: myuser
ssh_key_name: mykey
ssh_key_file: \(aq/etc/salt/hpcloud/mykey.pem\(aq
password: mypass
provider: openstack
# For Rackspace
my\-openstack\-rackspace\-config:
identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/tokens\(aq
compute_name: cloudServersOpenStack
protocol: ipv4
compute_region: DFW
protocol: ipv4
user: myuser
tenant: 5555555
password: mypass
provider: openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have an API key for your provider, it may be specified instead of a
password:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-hp\-config:
apikey: 901d3f579h23c8v73q9
my\-openstack\-rackspace\-config:
apikey: 901d3f579h23c8v73q9
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have
\fBprovider: my\-openstack\-hp\-config\fP or \fBprovider:
my\-openstack\-rackspace\-config\fP instead of \fBprovider: openstack\fP on a profile
configuration.
.sp
You will certainly need to configure the \fBuser\fP, \fBtenant\fP and either
\fBpassword\fP or \fBapikey\fP\&.
.sp
If your OpenStack instances only have private IP addresses and a CIDR range of
private addresses are not reachable from the salt\-master, you may set your
preference to have Salt ignore it. Using the old could configurations syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
OPENSTACK.ignore_cidr: 192.168.0.0/16
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using the new syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
ignore_cidr: 192.168.0.0/16
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For in\-house OpenStack Essex installation, libcloud needs the service_type :
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
identity_url: \(aqhttp://control.openstack.example.org:5000/v2.0/\(aq
compute_name : Compute Service
service_type : compute
.ft P
.fi
.UNINDENT
.UNINDENT
.SS DigitalOcean
.sp
Using Salt for DigitalOcean requires a client_key and an api_key. These can be
found in the DigitalOcean web interface, in the "My Settings" section, under
the API Access tab.
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
DIGITAL_OCEAN.client_key: wFGEwgregeqw3435gDger
DIGITAL_OCEAN.api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-digitalocean\-config:
provider: digital_ocean
client_key: wFGEwgregeqw3435gDger
api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
location: New York 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have
\fBprovider: my\-digitalocean\-config\fP instead of \fBprovider: digital_ocean\fP on a
profile configuration.
.SS Parallels
.sp
Using Salt with Parallels requires a user, password and URL. These can be
obtained from your cloud provider.
.INDENT 0.0
.IP \(bu 2
Using the old format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
PARALLELS.user: myuser
PARALLELS.password: xyzzy
PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-parallels\-config:
user: myuser
password: xyzzy
url: https://api.cloud.xmission.com:4465/paci/v1.0/
provider: parallels
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: With the new providers configuration syntax you would have
\fBprovider: my\-parallels\-config\fP instead of \fBprovider: parallels\fP on a
profile configuration.
.SS Proxmox
.sp
Using Salt with Proxmox requires a user, password and URL. These can be
obtained from your cloud provider. Both PAM and PVE users can be used.
.INDENT 0.0
.IP \(bu 2
Using the new configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-proxmox\-config:
provider: proxmox
user: saltcloud@pve
password: xyzzy
url: your.proxmox.host
.ft P
.fi
.UNINDENT
.UNINDENT
.SS lxc
.sp
The lxc driver is a new, experimental driver for installing Salt on
newly provisioned (via saltcloud) lxc containers. It will in turn use saltify to install
salt an rattach the lxc container as a new lxc minion.
As soon as we can, we manage baremetal operation over SSH.
You can also destroy those containers via this driver.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
devhost10\-lxc:
target: devhost10
provider: lxc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And in the map file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
devhost10\-lxc:
provider: devhost10\-lxc
from_container: ubuntu
backing: lvm
sudo: True
size: 3g
ip: 10.0.3.9
minion:
master: 10.5.0.1
master_port: 4506
lxc_conf:
\- lxc.utsname: superlxc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Saltify
.sp
The Saltify driver is a new, experimental driver for installing Salt on
existing machines (virtual or bare metal). Because it does not use an actual
cloud provider, it needs no configuration in the main cloud config file.
However, it does still require a profile to be set up, and is most useful when
used inside a map file. The key parameters to be set are \fBssh_host\fP,
\fBssh_username\fP and either \fBssh_keyfile\fP or \fBssh_password\fP\&. These may all
be set in either the profile or the map. An example configuration might use the
following in cloud.profiles:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make_salty:
provider: saltify
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And in the map file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make_salty:
\- myinstance:
ssh_host: 54.262.11.38
ssh_username: ubuntu
ssh_keyfile: \(aq/etc/salt/mysshkey.pem\(aq
sudo: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Extending Profiles and Cloud Providers Configuration
.sp
As of 0.8.7, the option to extend both the profiles and cloud providers
configuration and avoid duplication was added. The extends feature works on the
current profiles configuration, but, regarding the cloud providers
configuration, \fBonly\fP works in the new syntax and respective configuration
files, i.e. \fB/etc/salt/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/*.conf\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Extending cloud profiles and providers is not recursive. For example, a
profile that is extended by a second profile is possible, but the second
profile cannot be extended by a third profile.
.sp
Also, if a profile (or provider) is extending another profile and each
contains a list of values, the lists from the extending profile will
override the list from the original profile. The lists are not merged
together.
.UNINDENT
.UNINDENT
.SS Extending Profiles
.sp
Some example usage on how to use \fBextends\fP with profiles. Consider
\fB/etc/salt/salt/cloud.profiles\fP containing:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
development\-instances:
provider: my\-ec2\-config
size: Micro Instance
ssh_username: ec2_user
securitygroup:
\- default
deploy: False
Amazon\-Linux\-AMI\-2012.09\-64bit:
image: ami\-54cf5c3d
extends: development\-instances
Fedora\-17:
image: ami\-08d97e61
extends: development\-instances
CentOS\-5:
provider: my\-aws\-config
image: ami\-09b61d60
extends: development\-instances
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above configuration, once parsed would generate the following profiles
data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[{\(aqdeploy\(aq: False,
\(aqimage\(aq: \(aqami\-08d97e61\(aq,
\(aqprofile\(aq: \(aqFedora\-17\(aq,
\(aqprovider\(aq: \(aqmy\-ec2\-config\(aq,
\(aqsecuritygroup\(aq: [\(aqdefault\(aq],
\(aqsize\(aq: \(aqMicro Instance\(aq,
\(aqssh_username\(aq: \(aqec2_user\(aq},
{\(aqdeploy\(aq: False,
\(aqimage\(aq: \(aqami\-09b61d60\(aq,
\(aqprofile\(aq: \(aqCentOS\-5\(aq,
\(aqprovider\(aq: \(aqmy\-aws\-config\(aq,
\(aqsecuritygroup\(aq: [\(aqdefault\(aq],
\(aqsize\(aq: \(aqMicro Instance\(aq,
\(aqssh_username\(aq: \(aqec2_user\(aq},
{\(aqdeploy\(aq: False,
\(aqimage\(aq: \(aqami\-54cf5c3d\(aq,
\(aqprofile\(aq: \(aqAmazon\-Linux\-AMI\-2012.09\-64bit\(aq,
\(aqprovider\(aq: \(aqmy\-ec2\-config\(aq,
\(aqsecuritygroup\(aq: [\(aqdefault\(aq],
\(aqsize\(aq: \(aqMicro Instance\(aq,
\(aqssh_username\(aq: \(aqec2_user\(aq},
{\(aqdeploy\(aq: False,
\(aqprofile\(aq: \(aqdevelopment\-instances\(aq,
\(aqprovider\(aq: \(aqmy\-ec2\-config\(aq,
\(aqsecuritygroup\(aq: [\(aqdefault\(aq],
\(aqsize\(aq: \(aqMicro Instance\(aq,
\(aqssh_username\(aq: \(aqec2_user\(aq}]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Pretty cool right?
.SS Extending Providers
.sp
Some example usage on how to use \fBextends\fP within the cloud providers
configuration. Consider \fB/etc/salt/salt/cloud.providers\fP containing:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-develop\-envs:
\- id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
keyname: test
securitygroup: quick\-start
private_key: /root/test.pem
location: ap\-southeast\-1
availability_zone: ap\-southeast\-1b
provider: aws
\- user: myuser@mycorp.com
password: mypass
ssh_key_name: mykey
ssh_key_file: \(aq/etc/salt/ibm/mykey.pem\(aq
location: Raleigh
provider: ibmsce
my\-productions\-envs:
\- extends: my\-develop\-envs:ibmsce
user: my\-production\-user@mycorp.com
location: us\-east\-1
availability_zone: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above configuration, once parsed would generate the following providers
data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqproviders\(aq: {
\(aqmy\-develop\-envs\(aq: [
{\(aqavailability_zone\(aq: \(aqap\-southeast\-1b\(aq,
\(aqid\(aq: \(aqHJGRYCILJLKJYG\(aq,
\(aqkey\(aq: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq,
\(aqkeyname\(aq: \(aqtest\(aq,
\(aqlocation\(aq: \(aqap\-southeast\-1\(aq,
\(aqprivate_key\(aq: \(aq/root/test.pem\(aq,
\(aqprovider\(aq: \(aqaws\(aq,
\(aqsecuritygroup\(aq: \(aqquick\-start\(aq
},
{\(aqlocation\(aq: \(aqRaleigh\(aq,
\(aqpassword\(aq: \(aqmypass\(aq,
\(aqprovider\(aq: \(aqibmsce\(aq,
\(aqssh_key_file\(aq: \(aq/etc/salt/ibm/mykey.pem\(aq,
\(aqssh_key_name\(aq: \(aqmykey\(aq,
\(aquser\(aq: \(aqmyuser@mycorp.com\(aq
}
],
\(aqmy\-productions\-envs\(aq: [
{\(aqavailability_zone\(aq: \(aqus\-east\-1\(aq,
\(aqlocation\(aq: \(aqus\-east\-1\(aq,
\(aqpassword\(aq: \(aqmypass\(aq,
\(aqprovider\(aq: \(aqibmsce\(aq,
\(aqssh_key_file\(aq: \(aq/etc/salt/ibm/mykey.pem\(aq,
\(aqssh_key_name\(aq: \(aqmykey\(aq,
\(aquser\(aq: \(aqmy\-production\-user@mycorp.com\(aq
}
]
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Windows Configuration
.SS Spinning up Windows Minions
.sp
It is possible to use Salt Cloud to spin up Windows instances, and then install
Salt on them. This functionality is available on all cloud providers that are
supported by Salt Cloud. However, it may not necessarily be available on all
Windows images.
.SS Requirements
.sp
Salt Cloud makes use of \fIsmbclient\fP and \fIwinexe\fP to set up the Windows Salt
Minion installer. \fIsmbclient\fP may be part of either the \fIsamba\fP package, or its
own \fIsmbclient\fP package, depending on the distribution. \fIwinexe\fP is less
commonly available in distribution\-specific repositories. However, it is
currently being built for various distributions in 3rd party channels:
.INDENT 0.0
.IP \(bu 2
\fI\%RPMs at pbone.net\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%OpenSuse Build Service\fP
.UNINDENT
.sp
Additionally, a copy of the Salt Minion Windows installer must be present on
the system on which Salt Cloud is running. This installer may be downloaded
from saltstack.com:
.INDENT 0.0
.IP \(bu 2
\fI\%SaltStack Download Area\fP
.UNINDENT
.SS Firewall Settings
.sp
Because Salt Cloud makes use of \fIsmbclient\fP and \fIwinexe\fP, port 445 must be open
on the target image. This port is not generally open by default on a standard
Windows distribution, and care must be taken to use an image in which this port
is open, or the Windows firewall is disabled.
.SS Configuration
.sp
Configuration is set as usual, with some extra configuration settings. The
location of the Windows installer on the machine that Salt Cloud is running on
must be specified. This may be done in any of the regular configuration files
(main, providers, profiles, maps). For example:
.sp
Setting the installer in \fB/etc/salt/cloud.providers\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-softlayer:
provider: softlayer
user: MYUSER1138
apikey: \(aqe3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9\(aq
minion:
master: saltmaster.example.com
win_installer: /root/Salt\-Minion\-0.17.0\-AMD64\-Setup.exe
win_username: Administrator
win_password: letmein
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The default Windows user is \fIAdministrator\fP, and the default Windows password
is blank.
.SS Cloud Provider Specifics
.SS Getting Started With Aliyun ECS
.sp
The Aliyun ECS (Elastic Computer Service) is one of the most popular public
cloud providers in China. This cloud provider can be used to manage aliyun
instance using salt\-cloud.
.sp
\fI\%http://www.aliyun.com/\fP
.SS Dependencies
.sp
This driver requires the Python \fBrequests\fP library to be installed.
.SS Configuration
.sp
Using Salt for Aliyun ECS requires aliyun access key id and key secret.
These can be found in the aliyun web interface, in the "User Center" section,
under "My Service" tab.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
my\-aliyun\-config:
# aliyun Access Key ID
id: wDGEwGregedg3435gDgxd
# aliyun Access Key Secret
key: GDd45t43RDBTrkkkg43934t34qT43t4dgegerGEgg
location: cn\-qingdao
provider: aliyun
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Profiles
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the
\fB/etc/salt/cloud.profiles.d/\fP directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
aliyun_centos:
provider: my\-aliyun\-config
size: ecs.t1.small
location: cn\-qingdao
securitygroup: G1989096784427999
image: centos6u3_64_20G_aliaegis_20130816.vhd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-sizes my\-aliyun\-config
my\-aliyun\-config:
\-\-\-\-\-\-\-\-\-\-
aliyun:
\-\-\-\-\-\-\-\-\-\-
ecs.c1.large:
\-\-\-\-\-\-\-\-\-\-
CpuCoreCount:
8
InstanceTypeId:
ecs.c1.large
MemorySize:
16.0
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images my\-aliyun\-config
my\-aliyun\-config:
\-\-\-\-\-\-\-\-\-\-
aliyun:
\-\-\-\-\-\-\-\-\-\-
centos5u8_64_20G_aliaegis_20131231.vhd:
\-\-\-\-\-\-\-\-\-\-
Architecture:
x86_64
Description:
ImageId:
centos5u8_64_20G_aliaegis_20131231.vhd
ImageName:
CentOS 5.8 64位
ImageOwnerAlias:
system
ImageVersion:
1.0
OSName:
CentOS 5.8 64位
Platform:
CENTOS5
Size:
20
Visibility:
public
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Locations can be obtained using the \fB\-\-list\-locations\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-aliyun\-config:
\-\-\-\-\-\-\-\-\-\-
aliyun:
\-\-\-\-\-\-\-\-\-\-
cn\-beijing:
\-\-\-\-\-\-\-\-\-\-
LocalName:
北京
RegionId:
cn\-beijing
cn\-hangzhou:
\-\-\-\-\-\-\-\-\-\-
LocalName:
杭州
RegionId:
cn\-hangzhou
cn\-hongkong:
\-\-\-\-\-\-\-\-\-\-
LocalName:
香港
RegionId:
cn\-hongkong
cn\-qingdao:
\-\-\-\-\-\-\-\-\-\-
LocalName:
青岛
RegionId:
cn\-qingdao
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Security Group can be obtained using the \fB\-f list_securitygroup\fP option
for the \fBsalt\-cloud\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-location=cn\-qingdao \-f list_securitygroup my\-aliyun\-config
my\-aliyun\-config:
\-\-\-\-\-\-\-\-\-\-
aliyun:
\-\-\-\-\-\-\-\-\-\-
G1989096784427999:
\-\-\-\-\-\-\-\-\-\-
Description:
G1989096784427999
SecurityGroupId:
G1989096784427999
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Aliyun ECS REST API documentation is available from \fI\%Aliyun ECS API\fP\&.
.UNINDENT
.UNINDENT
.SS Getting Started With Azure
.sp
New in version 2014.1.0.
.sp
Azure is a cloud service by Microsoft providing virtual machines, SQL services,
media services, and more. This document describes how to use Salt Cloud to
create a virtual machine on Azure, with Salt installed.
.sp
More information about Azure is located at \fI\%http://www.windowsazure.com/\fP\&.
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
The \fI\%Azure\fP Python SDK.
.IP \(bu 2
A Microsoft Azure account
.IP \(bu 2
OpenSSL (to generate the certificates)
.IP \(bu 2
\fI\%Salt\fP
.UNINDENT
.SS Configuration
.sp
Set up the provider config at \fB/etc/salt/cloud.providers.d/azure.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud.providers.d/azure.conf
my\-azure\-config:
provider: azure
subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617
certificate_path: /etc/salt/azure.pem
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com
provider: azure
# Optional
management_host: management.core.windows.net
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The certificate used must be generated by the user. OpenSSL can be used to
create the management certificates. Two certificates are needed: a .cer file,
which is uploaded to Azure, and a .pem file, which is stored locally.
.sp
To create the .pem file, execute the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openssl req \-x509 \-nodes \-days 365 \-newkey rsa:1024 \-keyout /etc/salt/azure.pem \-out /etc/salt/azure.pem
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To create the .cer file, execute the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openssl x509 \-inform pem \-in /etc/salt/azure.pem \-outform der \-out /etc/salt/azure.cer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After creating these files, the .cer file will need to be uploaded to
Azure via the "Upload a Management Certificate" action of the "Management Certificates"
tab within the "Settings" section of the management portal.
.sp
Optionally, a \fBmanagement_host\fP may be configured, if necessary for the region.
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
azure\-ubuntu:
provider: my\-azure\-config
image: \(aqb39f27a8b8c64d52b05eac6a62ebad85__Ubuntu\-12_04_3\-LTS\-amd64\-server\-20131003\-en\-us\-30GB\(aq
size: Small
location: \(aqEast US\(aq
ssh_username: azureuser
ssh_password: verybadpass
slot: production
media_link: \(aqhttp://portalvhdabcdefghijklmn.blob.core.windows.net/vhds\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These options are described in more detail below. Once configured, the profile
can be realized with a salt command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p azure\-ubuntu newinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create an salt minion instance named \fBnewinstance\fP in Azure. If
the command was executed on the salt\-master, its Salt key will automatically
be signed on the master.
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt newinstance test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Profile Options
.sp
The following options are currently available for Azure.
.SS provider
.sp
The name of the provider as configured in
\fI/etc/salt/cloud.providers.d/azure.conf\fP\&.
.SS image
.sp
The name of the image to use to create a VM. Available images can be viewed
using the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-images my\-azure\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.SS size
.sp
The name of the size to use to create a VM. Available sizes can be viewed using
the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-sizes my\-azure\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.SS location
.sp
The name of the location to create a VM in. Available locations can be viewed
using the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-locations my\-azure\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.SS ssh_username
.sp
The user to use to log into the newly\-created VM to install Salt.
.SS ssh_password
.sp
The password to use to log into the newly\-created VM to install Salt.
.SS slot
.sp
The environment to which the hosted service is deployed. Valid values are
\fIstaging\fP or \fIproduction\fP\&. When set to \fIproduction\fP, the resulting URL of the
new VM will be \fI<vm_name>.cloudapp.net\fP\&. When set to \fIstaging\fP, the resulting
URL will contain a generated hash instead.
.SS media_link
.sp
This is the URL of the container that will store the disk that this VM uses.
Currently, this container must already exist. If a VM has previously been
created in the associated account, a container should already exist. In the web
interface, go into the Storage area and click one of the available storage
selections. Click the Containers link, and then copy the URL from the container
that will be used. It generally looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Show Instance
.sp
This action is a thin wrapper around \fB\-\-full\-query\fP, which displays details on
a single instance only. In an environment with several machines, this will save
a user from having to sort through all instance data, just to examine a single
instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_instance myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With DigitalOcean
.sp
DigitalOcean is a public cloud provider that specializes in Linux instances.
.SS Configuration
.sp
Using Salt for DigitalOcean requires a client_key, an api_key, an ssh_key_file,
and an ssh_key_name. The client_key and api_key can be found in the Digital
Ocean web interface, in the "My Settings" section, under the API Access tab.
The ssh_key_name can be found under the "SSH Keys" section.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
my\-digitalocean\-config:
provider: digital_ocean
client_key: wFGEwgregeqw3435gDger
api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
ssh_key_file: /path/to/ssh/key/file
ssh_key_name: my\-key\-name
location: New York 1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Profiles
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the
\fB/etc/salt/cloud.profiles.d/\fP directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
digitalocean\-ubuntu:
provider: my\-digitalocean\-config
image: Ubuntu 14.04 x32
size: 512MB
location: New York 1
private_networking: True
backups_enabled: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-sizes my\-digitalocean\-config
my\-digitalocean\-config:
\-\-\-\-\-\-\-\-\-\-
digital_ocean:
\-\-\-\-\-\-\-\-\-\-
512MB:
\-\-\-\-\-\-\-\-\-\-
cost_per_hour:
0.00744
cost_per_month:
5.0
cpu:
1
disk:
20
id:
66
memory:
512
name:
512MB
slug:
None
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images my\-digitalocean\-config
my\-digitalocean\-config:
\-\-\-\-\-\-\-\-\-\-
digital_ocean:
\-\-\-\-\-\-\-\-\-\-
Arch Linux 2013.05 x64:
\-\-\-\-\-\-\-\-\-\-
distribution:
Arch Linux
id:
350424
name:
Arch Linux 2013.05 x64
public:
True
slug:
None
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
DigitalOcean\(aqs concept of \fBApplications\fP is nothing more than a
pre\-configured instance (same as a normal Droplet). You will find examples
such \fBDocker 0.7 Ubuntu 13.04 x64\fP and \fBWordpress on Ubuntu 12.10\fP
when using the \fB\-\-list\-images\fP option. These names can be used just like
the rest of the standard instances when specifying an image in the cloud
profile configuration.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Additional documentation is available from \fI\%DigitalOcean\fP\&.
.UNINDENT
.UNINDENT
.SS Getting Started With AWS EC2
.sp
Amazon EC2 is a very widely used public cloud platform and one of the core
platforms Salt Cloud has been built to support.
.sp
Previously, the suggested provider for AWS EC2 was the \fBaws\fP provider. This
has been deprecated in favor of the \fBec2\fP provider. Configuration using the
old \fBaws\fP provider will still function, but that driver is no longer in
active development.
.SS Dependencies
.sp
This driver requires the Python \fBrequests\fP library to be installed.
.SS Configuration
.sp
The following example illustrates some of the options that can be set. These
parameters are discussed in more detail below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
my\-ec2\-southeast\-public\-ips:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com
# Set up grains information, which will be common for all nodes
# using this provider
grains:
node_type: broker
release: 1.0.1
# Specify whether to use public or private IP for deploy script.
#
# Valid options are:
# private_ips \- The salt\-master is also hosted with EC2
# public_ips \- The salt\-master is hosted outside of EC2
#
ssh_interface: public_ips
# Set the EC2 access credentials (see below)
#
id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
# Make sure this key is owned by root with permissions 0400.
#
private_key: /etc/salt/my_test_key.pem
keyname: my_test_key
securitygroup: default
# Optionally configure default region
# Use salt\-cloud \-\-list\-locations <provider> to obtain valid regions
#
location: ap\-southeast\-1
availability_zone: ap\-southeast\-1b
# Configure which user to use to run the deploy script. This setting is
# dependent upon the AMI that is used to deploy. It is usually safer to
# configure this individually in a profile, than globally. Typical users
# are:
#
# Amazon Linux \-> ec2\-user
# RHEL \-> ec2\-user
# CentOS \-> ec2\-user
# Ubuntu \-> ubuntu
#
ssh_username: ec2\-user
# Optionally add an IAM profile
iam_profile: \(aqarn:aws:iam::123456789012:instance\-profile/ExampleInstanceProfile\(aq
provider: ec2
my\-ec2\-southeast\-private\-ips:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com
# Specify whether to use public or private IP for deploy script.
#
# Valid options are:
# private_ips \- The salt\-master is also hosted with EC2
# public_ips \- The salt\-master is hosted outside of EC2
#
ssh_interface: private_ips
# Set the EC2 access credentials (see below)
#
id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
# Make sure this key is owned by root with permissions 0400.
#
private_key: /etc/salt/my_test_key.pem
keyname: my_test_key
securitygroup: default
# Optionally configure default region
#
location: ap\-southeast\-1
availability_zone: ap\-southeast\-1b
# Configure which user to use to run the deploy script. This setting is
# dependent upon the AMI that is used to deploy. It is usually safer to
# configure this individually in a profile, than globally. Typical users
# are:
#
# Amazon Linux \-> ec2\-user
# RHEL \-> ec2\-user
# CentOS \-> ec2\-user
# Ubuntu \-> ubuntu
#
ssh_username: ec2\-user
# Optionally add an IAM profile
iam_profile: \(aqmy other profile name\(aq
provider: ec2
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Access Credentials
.sp
The \fBid\fP and \fBkey\fP settings may be found in the Security Credentials area
of the AWS Account page:
.sp
\fI\%https://portal.aws.amazon.com/gp/aws/securityCredentials\fP
.sp
Both are located in the Access Credentials area of the page, under the Access
Keys tab. The \fBid\fP setting is labeled Access Key ID, and the \fBkey\fP setting
is labeled Secret Access Key.
.SS Key Pairs
.sp
In order to create an instance with Salt installed and configured, a key pair
will need to be created. This can be done in the EC2 Management Console, in the
Key Pairs area. These key pairs are unique to a specific region. Keys in the
us\-east\-1 region can be configured at:
.sp
\fI\%https://console.aws.amazon.com/ec2/home?region=us\-east\-1#s=KeyPairs\fP
.sp
Keys in the us\-west\-1 region can be configured at
.sp
\fI\%https://console.aws.amazon.com/ec2/home?region=us\-west\-1#s=KeyPairs\fP
.sp
\&...and so on. When creating a key pair, the browser will prompt to download a
pem file. This file must be placed in a directory accessible by Salt Cloud,
with permissions set to either 0400 or 0600.
.SS Security Groups
.sp
An instance on EC2 needs to belong to a security group. Like key pairs, these
are unique to a specific region. These are also configured in the EC2
Management Console. Security groups for the us\-east\-1 region can be configured
at:
.sp
\fI\%https://console.aws.amazon.com/ec2/home?region=us\-east\-1#s=SecurityGroups\fP
.sp
\&...and so on.
.sp
A security group defines firewall rules which an instance will adhere to. If
the salt\-master is configured outside of EC2, the security group must open the
SSH port (usually port 22) in order for Salt Cloud to install Salt.
.SS IAM Profile
.sp
Amazon EC2 instances support the concept of an \fI\%instance profile\fP, which
is a logical container for the IAM role. At the time that you launch an EC2
instance, you can associate the instance with an instance profile, which in
turn corresponds to the IAM role. Any software that runs on the EC2 instance
is able to access AWS using the permissions associated with the IAM role.
.sp
Scaffolding the profile is a 2\-step configuration process:
.INDENT 0.0
.IP 1. 3
Configure an IAM Role from the \fI\%IAM Management Console\fP\&.
.IP 2. 3
Attach this role to a new profile. It can be done with the \fI\%AWS CLI\fP:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
> aws iam create\-instance\-profile \-\-instance\-profile\-name PROFILE_NAME
> aws iam add\-role\-to\-instance\-profile \-\-instance\-profile\-name PROFILE_NAME \-\-role\-name ROLE_NAME
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Once the profile is created, you can use the \fBPROFILE_NAME\fP to configure
your cloud profiles.
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base_ec2_private:
provider: my\-ec2\-southeast\-private\-ips
image: ami\-e565ba8c
size: Micro Instance
ssh_username: ec2\-user
base_ec2_public:
provider: my\-ec2\-southeast\-public\-ips
image: ami\-e565ba8c
size: Micro Instance
ssh_username: ec2\-user
base_ec2_db:
provider: my\-ec2\-southeast\-public\-ips
image: ami\-e565ba8c
size: m1.xlarge
ssh_username: ec2\-user
volumes:
\- { size: 10, device: /dev/sdf }
\- { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
\- { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
# optionally add tags to profile:
tag: {\(aqEnvironment\(aq: \(aqproduction\(aq, \(aqRole\(aq: \(aqdatabase\(aq}
# force grains to sync after install
sync_after_install: grains
base_ec2_vpc:
provider: my\-ec2\-southeast\-public\-ips
image: ami\-a73264ce
size: m1.xlarge
ssh_username: ec2\-user
script: /etc/salt/cloud.deploy.d/user_data.sh
network_interfaces:
\- DeviceIndex: 0
PrivateIpAddresses:
\- Primary: True
#auto assign public ip (not EIP)
AssociatePublicIpAddress: True
SubnetId: subnet\-813d4bbf
SecurityGroupId:
\- sg\-750af413
volumes:
\- { size: 10, device: /dev/sdf }
\- { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
\- { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
del_root_vol_on_destroy: True
del_all_vol_on_destroy: True
tag: {\(aqEnvironment\(aq: \(aqproduction\(aq, \(aqRole\(aq: \(aqdatabase\(aq}
sync_after_install: grains
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The profile can now be realized with a salt command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-p base_ec2 ami.example.com
# salt\-cloud \-p base_ec2_public ami.example.com
# salt\-cloud \-p base_ec2_private ami.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create an instance named \fBami.example.com\fP in EC2. The minion that
is installed on this instance will have an \fBid\fP of \fBami.example.com\fP\&. If
the command was executed on the salt\-master, its Salt key will automatically be
signed on the master.
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aqami.example.com\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Required Settings
.sp
The following settings are always required for EC2:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Set the EC2 login data
my\-ec2\-config:
id: HJGRYCILJLKJYG
key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq
keyname: test
securitygroup: quick\-start
private_key: /root/test.pem
provider: ec2
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Optional Settings
.sp
EC2 allows a location to be set for servers to be deployed in. Availability
zones exist inside regions, and may be added to increase specificity.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
# Optionally configure default region
location: ap\-southeast\-1
availability_zone: ap\-southeast\-1b
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
EC2 instances can have a public or private IP, or both. When an instance is
deployed, Salt Cloud needs to log into it via SSH to run the deploy script.
By default, the public IP will be used for this. If the salt\-cloud command is
run from another EC2 instance, the private IP should be used.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
# Specify whether to use public or private IP for deploy script
# private_ips or public_ips
ssh_interface: public_ips
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Many EC2 instances do not allow remote access to the root user by default.
Instead, another user must be used to run the deploy script using sudo. Some
common usernames include ec2\-user (for Amazon Linux), ubuntu (for Ubuntu
instances), admin (official Debian) and bitnami (for images provided by
Bitnami).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
# Configure which user to use to run the deploy script
ssh_username: ec2\-user
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple usernames can be provided, in which case Salt Cloud will attempt to
guess the correct username. This is mostly useful in the main configuration
file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
ssh_username:
\- ec2\-user
\- ubuntu
\- admin
\- bitnami
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple security groups can also be specified in the same fashion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
securitygroup:
\- default
\- extra
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Your instances may optionally make use of EC2 Spot Instances. The
following example will request that spot instances be used and your
maximum bid will be $0.10. Keep in mind that different spot prices
may be needed based on the current value of the various EC2 instance
sizes. You can check current and past spot instance pricing via the
EC2 API or AWS Console.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
spot_config:
spot_price: 0.10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default, the spot instance type is set to \(aqone\-time\(aq, meaning it will
be launched and, if it\(aqs ever terminated for whatever reason, it will not
be recreated. If you would like your spot instances to be relaunched after
a termination (by your or AWS), set the \fBtype\fP to \(aqpersistent\(aq.
.sp
NOTE: Spot instances are a great way to save a bit of money, but you do
run the risk of losing your spot instances if the current price for the
instance size goes above your maximum bid.
.sp
The following parameters may be set in the cloud configuration file to
control various aspects of the spot instance launching:
.INDENT 0.0
.IP \(bu 2
\fBwait_for_spot_timeout\fP: seconds to wait before giving up on spot instance
launch (default=600)
.IP \(bu 2
\fBwait_for_spot_interval\fP: seconds to wait in between polling requests to
determine if a spot instance is available (default=30)
.IP \(bu 2
\fBwait_for_spot_interval_multiplier\fP: a multiplier to add to the interval in
between requests, which is useful if AWS is throttling your requests
(default=1)
.IP \(bu 2
\fBwait_for_spot_max_failures\fP: maximum number of failures before giving up
on launching your spot instance (default=10)
.UNINDENT
.sp
If you find that you\(aqre being throttled by AWS while polling for spot
instances, you can set the following in your core cloud configuration
file that will double the polling interval after each request to AWS.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wait_for_spot_interval: 1
wait_for_spot_interval_multiplier: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See the \fI\%AWS Spot Instances\fP documentation for more information.
.sp
Block device mappings enable you to specify additional EBS volumes or instance
store volumes when the instance is launched. This setting is also available on
each cloud profile. Note that the number of instance stores varies by instance
type. If more mappings are provided than are supported by the instance type,
mappings will be created in the order provided and additional mappings will be
ignored. Consult the \fI\%AWS documentation\fP for a listing of the available
instance stores, device names, and mount points.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
block_device_mappings:
\- DeviceName: /dev/sdb
VirtualName: ephemeral0
\- DeviceName: /dev/sdc
VirtualName: ephemeral1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also use block device mappings to change the size of the root device at the
provisioning time. For example, assuming the root device is \(aq/dev/sda\(aq, you can set
its size to 100G by using the following configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
block_device_mappings:
\- DeviceName: /dev/sda
Ebs.VolumeSize: 100
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Existing EBS volumes may also be attached (not created) to your instances or
you can create new EBS volumes based on EBS snapshots. To simply attach an
existing volume use the \fBvolume_id\fP parameter.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
device: /dev/xvdj
mount_point: /mnt/my_ebs
volume_id: vol\-12345abcd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or, to create a volume from an EBS snapshot, use the \fBsnapshot\fP parameter.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
device: /dev/xvdj
mount_point: /mnt/my_ebs
snapshot: snap\-abcd12345
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that \fBvolume_id\fP will take precedence over the \fBsnapshot\fP parameter.
.sp
Tags can be set once an instance has been launched.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
tag:
tag0: value
tag1: value
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Modify EC2 Tags
.sp
One of the features of EC2 is the ability to tag resources. In fact, under the
hood, the names given to EC2 instances by salt\-cloud are actually just stored
as a tag called Name. Salt Cloud has the ability to manage these tags:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a get_tags mymachine
salt\-cloud \-a set_tags mymachine tag1=somestuff tag2=\(aqOther stuff\(aq
salt\-cloud \-a del_tags mymachine tag1,tag2,tag3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is possible to manage tags on any resource in EC2 with a Resource ID, not
just instances:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f get_tags my_ec2 resource_id=af5467ba
salt\-cloud \-f set_tags my_ec2 resource_id=af5467ba tag1=somestuff
salt\-cloud \-f del_tags my_ec2 resource_id=af5467ba tag1,tag2,tag3
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Rename EC2 Instances
.sp
As mentioned above, EC2 instances are named via a tag. However, renaming an
instance by renaming its tag will cause the salt keys to mismatch. A rename
function exists which renames both the instance, and the salt keys.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a rename mymachine newname=yourmachine
.ft P
.fi
.UNINDENT
.UNINDENT
.SS EC2 Termination Protection
.sp
EC2 allows the user to enable and disable termination protection on a specific
instance. An instance with this protection enabled cannot be destroyed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a enable_term_protect mymachine
salt\-cloud \-a disable_term_protect mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Rename on Destroy
.sp
When instances on EC2 are destroyed, there will be a lag between the time that
the action is sent, and the time that Amazon cleans up the instance. During
this time, the instance still retails a Name tag, which will cause a collision
if the creation of an instance with the same name is attempted before the
cleanup occurs. In order to avoid such collisions, Salt Cloud can be configured
to rename instances when they are destroyed. The new name will look something
like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myinstance\-DEL20f5b8ad4eb64ed88f2c428df80a1a0c
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In order to enable this, add rename_on_destroy line to the main
configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
rename_on_destroy: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Listing Images
.sp
Normally, images can be queried on a cloud provider by passing the
\fB\-\-list\-images\fP argument to Salt Cloud. This still holds true for EC2:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-images my\-ec2\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, the full list of images on EC2 is extremely large, and querying all of
the available images may cause Salt Cloud to behave as if frozen. Therefore,
the default behavior of this option may be modified, by adding an \fBowner\fP
argument to the provider configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
owner: aws\-marketplace
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The possible values for this setting are \fBamazon\fP, \fBaws\-marketplace\fP,
\fBself\fP, \fB<AWS account ID>\fP or \fBall\fP\&. The default setting is \fBamazon\fP\&.
Take note that \fBall\fP and \fBaws\-marketplace\fP may cause Salt Cloud to appear
as if it is freezing, as it tries to handle the large amount of data.
.sp
It is also possible to perform this query using different settings without
modifying the configuration files. To do this, call the \fBavail_images\fP
function directly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f avail_images my\-ec2\-config owner=aws\-marketplace
.ft P
.fi
.UNINDENT
.UNINDENT
.SS EC2 Images
.sp
The following are lists of available AMI images, generally sorted by OS. These
lists are on 3rd\-party websites, are not managed by Salt Stack in any way. They
are provided here as a reference for those who are interested, and contain no
warranty (express or implied) from anyone affiliated with Salt Stack. Most of
them have never been used, much less tested, by the Salt Stack team.
.INDENT 0.0
.IP \(bu 2
\fI\%Arch Linux\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%FreeBSD\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%Fedora\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%CentOS\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%Ubuntu\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%Debian\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%OmniOS\fP
.UNINDENT
.INDENT 0.0
.IP \(bu 2
\fI\%All Images on Amazon\fP
.UNINDENT
.SS show_image
.sp
This is a function that describes an AMI on EC2. This will give insight as to
the defaults that will be applied to an instance using a particular AMI.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-f show_image ec2 image=ami\-fd20ad94
.ft P
.fi
.UNINDENT
.UNINDENT
.SS show_instance
.sp
This action is a thin wrapper around \fB\-\-full\-query\fP, which displays details on a
single instance only. In an environment with several machines, this will save a
user from having to sort through all instance data, just to examine a single
instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-a show_instance myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.SS ebs_optimized
.sp
This argument enables switching of the EbsOptimized setting which default
to \(aqfalse\(aq. Indicates whether the instance is optimized for EBS I/O. This
optimization provides dedicated throughput to Amazon EBS and an optimized
configuration stack to provide optimal Amazon EBS I/O performance. This
optimization isn\(aqt available with all instance types. Additional usage
charges apply when using an EBS\-optimized instance.
.sp
This setting can be added to the profile or map file for an instance.
.sp
If set to True, this setting will enable an instance to be EbsOptimized
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ebs_optimized: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This can also be set as a cloud provider setting in the EC2 cloud
configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
ebs_optimized: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS del_root_vol_on_destroy
.sp
This argument overrides the default DeleteOnTermination setting in the AMI for
the EBS root volumes for an instance. Many AMIs contain \(aqfalse\(aq as a default,
resulting in orphaned volumes in the EC2 account, which may unknowingly be
charged to the account. This setting can be added to the profile or map file
for an instance.
.sp
If set, this setting will apply to the root EBS volume
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
del_root_vol_on_destroy: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This can also be set as a cloud provider setting in the EC2 cloud
configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
del_root_vol_on_destroy: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS del_all_vols_on_destroy
.sp
This argument overrides the default DeleteOnTermination setting in the AMI for
the not\-root EBS volumes for an instance. Many AMIs contain \(aqfalse\(aq as a
default, resulting in orphaned volumes in the EC2 account, which may
unknowingly be charged to the account. This setting can be added to the profile
or map file for an instance.
.sp
If set, this setting will apply to any (non\-root) volumes that were created
by salt\-cloud using the \(aqvolumes\(aq setting.
.sp
The volumes will not be deleted under the following conditions
* If a volume is detached before terminating the instance
* If a volume is created without this setting and attached to the instance
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
del_all_vols_on_destroy: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This can also be set as a cloud provider setting in the EC2 cloud
configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
del_all_vols_on_destroy: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The setting for this may be changed on all volumes of an existing instance
using one of the following commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a delvol_on_destroy myinstance
salt\-cloud \-a keepvol_on_destroy myinstance
salt\-cloud \-a show_delvol_on_destroy myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The setting for this may be changed on a volume on an existing instance
using one of the following commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a delvol_on_destroy myinstance device=/dev/sda1
salt\-cloud \-a delvol_on_destroy myinstance volume_id=vol\-1a2b3c4d
salt\-cloud \-a keepvol_on_destroy myinstance device=/dev/sda1
salt\-cloud \-a keepvol_on_destroy myinstance volume_id=vol\-1a2b3c4d
salt\-cloud \-a show_delvol_on_destroy myinstance device=/dev/sda1
salt\-cloud \-a show_delvol_on_destroy myinstance volume_id=vol\-1a2b3c4d
.ft P
.fi
.UNINDENT
.UNINDENT
.SS EC2 Termination Protection
.sp
EC2 allows the user to enable and disable termination protection on a specific
instance. An instance with this protection enabled cannot be destroyed. The EC2
driver adds a show_term_protect action to the regular EC2 functionality.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_term_protect mymachine
salt\-cloud \-a enable_term_protect mymachine
salt\-cloud \-a disable_term_protect mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Alternate Endpoint
.sp
Normally, EC2 endpoints are build using the region and the service_url. The
resulting endpoint would follow this pattern:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ec2.<region>.<service_url>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This results in an endpoint that looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ec2.us\-east\-1.amazonaws.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There are other projects that support an EC2 compatibility layer, which this
scheme does not account for. This can be overridden by specifying the endpoint
directly in the main cloud configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
endpoint: myendpoint.example.com:1138/services/Cloud
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Volume Management
.sp
The EC2 driver has several functions and actions for management of EBS volumes.
.SS Creating Volumes
.sp
A volume may be created, independent of an instance. A zone must be specified.
A size or a snapshot may be specified (in GiB). If neither is given, a default
size of 10 GiB will be used. If a snapshot is given, the size of the snapshot
will be used.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_volume ec2 zone=us\-east\-1b
salt\-cloud \-f create_volume ec2 zone=us\-east\-1b size=10
salt\-cloud \-f create_volume ec2 zone=us\-east\-1b snapshot=snap12345678
salt\-cloud \-f create_volume ec2 size=10 type=standard
salt\-cloud \-f create_volume ec2 size=10 type=io1 iops=1000
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Attaching Volumes
.sp
Unattached volumes may be attached to an instance. The following values are
required; name or instance_id, volume_id and device.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a attach_volume myinstance volume_id=vol\-12345 device=/dev/sdb1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Show a Volume
.sp
The details about an existing volume may be retrieved.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_volume myinstance volume_id=vol\-12345
salt\-cloud \-f show_volume ec2 volume_id=vol\-12345
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Detaching Volumes
.sp
An existing volume may be detached from an instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a detach_volume myinstance volume_id=vol\-12345
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Deleting Volumes
.sp
A volume that is not attached to an instance may be deleted.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_volume ec2 volume_id=vol\-12345
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Managing Key Pairs
.sp
The EC2 driver has the ability to manage key pairs.
.SS Creating a Key Pair
.sp
A key pair is required in order to create an instance. When creating a key pair
with this function, the return data will contain a copy of the private key.
This private key is not stored by Amazon, will not be obtainable past this
point, and should be stored immediately.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_keypair ec2 keyname=mykeypair
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Show a Key Pair
.sp
This function will show the details related to a key pair, not including the
private key itself (which is not stored by Amazon).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_keypair ec2 keyname=mykeypair
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Delete a Key Pair
.sp
This function removes the key pair from Amazon.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_keypair ec2 keyname=mykeypair
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Launching instances into a VPC
.SS Simple launching into a VPC
.sp
In the amazon web interface, identify the id of the subnet into which your
image should be created. Then, edit your cloud.profiles file like so:\-
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
profile\-id:
provider: provider\-name
subnetid: subnet\-XXXXXXXX
image: ami\-XXXXXXXX
size: m1.medium
ssh_username: ubuntu
securitygroupid:
\- sg\-XXXXXXXX
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Specifying interface properties
.sp
Launching into a VPC allows you to specify more complex configurations for
the network interfaces of your virtual machines, for example:\-
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
profile\-id:
provider: provider\-name
image: ami\-XXXXXXXX
size: m1.medium
ssh_username: ubuntu
# Do not include either \(aqsubnetid\(aq or \(aqsecuritygroupid\(aq here if you are
# going to manually specify interface configuration
#
network_interfaces:
\- DeviceIndex: 0
SubnetId: subnet\-XXXXXXXX
SecurityGroupId:
\- sg\-XXXXXXXX
# Uncomment this to associate an existing Elastic IP Address with
# this network interface:
#
# associate_eip: eni\-XXXXXXXX
# You can allocate more than one IP address to an interface. Use the
# \(aqip addr list\(aq command to see them.
#
# SecondaryPrivateIpAddressCount: 2
# Uncomment this to allocate a new Elastic IP Address to this
# interface (will be associated with the primary private ip address
# of the interface
#
# allocate_new_eip: True
# Uncomment this instead to allocate a new Elastic IP Address to
# both the primary private ip address and each of the secondary ones
#
allocate_new_eips: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that it is an error to assign a \(aqsubnetid\(aq or \(aqsecuritygroupid\(aq to a
profile where the interfaces are manually configured like this. These are both
really properties of each network interface, not of the machine itself.
.SS Getting Started With GoGrid
.sp
GoGrid is a public cloud provider supporting Linux and Windows.
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
Libcloud >= 0.13.2
.UNINDENT
.SS Configuration
.sp
To use Salt Cloud with GoGrid log into the GoGrid web interface and create an
API key. Do this by clicking on "My Account" and then going to the API Keys
tab.
.sp
The \fBapikey\fP and the \fBsharedsecret\fP configuration parameters need to be set
in the configuration file to enable interfacing with GoGrid:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
my\-gogrid\-config:
provider: gogrid
apikey: asdff7896asdh789
sharedsecret: saltybacon
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Profiles
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the
\fB/etc/salt/cloud.profiles.d/\fP directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gogrid_512:
provider: my\-gogrid\-config
size: 512MB
image: CentOS 6.2 (64\-bit) w/ None
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-sizes my\-gogrid\-config
my\-gogrid\-config:
\-\-\-\-\-\-\-\-\-\-
gogrid:
\-\-\-\-\-\-\-\-\-\-
512MB:
\-\-\-\-\-\-\-\-\-\-
bandwidth:
None
disk:
30
driver:
get_uuid:
id:
512MB
name:
512MB
price:
0.095
ram:
512
uuid:
bde1e4d7c3a643536e42a35142c7caac34b060e9
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images my\-gogrid\-config
my\-gogrid\-config:
\-\-\-\-\-\-\-\-\-\-
gogrid:
\-\-\-\-\-\-\-\-\-\-
CentOS 6.4 (64\-bit) w/ None:
\-\-\-\-\-\-\-\-\-\-
driver:
extra:
\-\-\-\-\-\-\-\-\-\-
get_uuid:
id:
18094
name:
CentOS 6.4 (64\-bit) w/ None
uuid:
bfd4055389919e01aa6261828a96cf54c8dcc2c4
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With Google Compute Engine
.sp
Google Compute Engine (GCE) is Google\-infrastructure as a service that lets you
run your large\-scale computing workloads on virtual machines. This document
covers how to use Salt Cloud to provision and manage your virtual machines
hosted within Google\(aqs infrastructure.
.sp
You can find out more about GCE and other Google Cloud Platform services
at \fI\%https://cloud.google.com\fP\&.
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
Libcloud >= 0.14.0\-beta3
.IP \(bu 2
PyCrypto >= 2.1.
.IP \(bu 2
A Google Cloud Platform account with Compute Engine enabled
.IP \(bu 2
A registered Service Account for authorization
.IP \(bu 2
Oh, and obviously you\(aqll need \fI\%salt\fP
.UNINDENT
.SS Google Compute Engine Setup
.INDENT 0.0
.IP 1. 3
Sign up for Google Cloud Platform
.sp
Go to \fI\%https://cloud.google.com\fP and use your Google account to sign up for
Google Cloud Platform and complete the guided instructions.
.IP 2. 3
Create a Project
.sp
Next, go to the console at \fI\%https://cloud.google.com/console\fP and create a
new Project. Make sure to select your new Project if you are not
automatically directed to the Project.
.sp
Projects are a way of grouping together related users, services, and
billing. You may opt to create multiple Projects and the remaining
instructions will need to be completed for each Project if you wish to
use GCE and Salt Cloud to manage your virtual machines.
.IP 3. 3
Enable the Google Compute Engine service
.sp
In your Project, either just click \fICompute Engine\fP to the left, or go to
the \fIAPIs & auth\fP section and \fIAPIs\fP link and enable the Google Compute
Engine service.
.IP 4. 3
Create a Service Account
.sp
To set up authorization, navigate to \fIAPIs & auth\fP section and then the
\fICredentials\fP link and click the \fICREATE NEW CLIENT ID\fP button. Select
\fIService Account\fP and click the \fICreate Client ID\fP button. This will
automatically download a \fB\&.json\fP file, which should be ignored. Look for
a new \fIService Account\fP section in the page and record the generated email
address for the matching key/fingerprint. The email address will be used
in the \fBservice_account_email_address\fP of the \fB/etc/salt/cloud\fP file.
.IP 5. 3
Key Format
.sp
In the new \fIService Account\fP section, click \fIGenerate new P12 key\fP, which
will automatically download a \fB\&.p12\fP private key file. The \fB\&.p12\fP
private key needs to be converted to a format compatible with libcloud.
This new Google\-generated private key was encrypted using \fInotasecret\fP as
a passphrase. Use the following command and record the location of the
converted private key and record the location for use in the
\fBservice_account_private_key\fP of the \fB/etc/salt/cloud\fP file:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
openssl pkcs12 \-in ORIG.p12 \-passin pass:notasecret \e
\-nodes \-nocerts | openssl rsa \-out NEW.pem
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Configuration
.sp
Set up the cloud config at \fB/etc/salt/cloud\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud
providers:
gce\-config:
# Set up the Project name and Service Account authorization
#
project: "your\-project\-id"
service_account_email_address: "123\-a5gt@developer.gserviceaccount.com"
service_account_private_key: "/path/to/your/NEW.pem"
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com
# Set up grains information, which will be common for all nodes
# using this provider
grains:
node_type: broker
release: 1.0.1
provider: gce
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The value provided for \fBproject\fP must not contain underscores or spaces and
is labeled as "Project ID" on the Google Developers Console.
.UNINDENT
.UNINDENT
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
all_settings:
image: centos\-6
size: n1\-standard\-1
location: europe\-west1\-b
network: default
tags: \(aq["one", "two", "three"]\(aq
metadata: \(aq{"one": "1", "2": "two"}\(aq
use_persistent_disk: True
delete_boot_pd: False
deploy: True
make_master: False
provider: gce\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The profile can be realized now with a salt command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p all_settings gce\-instance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create an salt minion instance named \fBgce\-instance\fP in GCE. If
the command was executed on the salt\-master, its Salt key will automatically
be signed on the master.
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqami.example.com\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS GCE Specific Settings
.sp
Consult the sample profile below for more information about GCE specific
settings. Some of them are mandatory and are properly labeled below but
typically also include a hard\-coded default.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
all_settings:
# Image is used to define what Operating System image should be used
# to for the instance. Examples are Debian 7 (wheezy) and CentOS 6.
#
# MANDATORY
#
image: centos\-6
# A \(aqsize\(aq, in GCE terms, refers to the instance\(aqs \(aqmachine type\(aq. See
# the on\-line documentation for a complete list of GCE machine types.
#
# MANDATORY
#
size: n1\-standard\-1
# A \(aqlocation\(aq, in GCE terms, refers to the instance\(aqs \(aqzone\(aq. GCE
# has the notion of both Regions (e.g. us\-central1, europe\-west1, etc)
# and Zones (e.g. us\-central1\-a, us\-central1\-b, etc).
#
# MANDATORY
#
location: europe\-west1\-b
# Use this setting to define the network resource for the instance.
# All GCE projects contain a network named \(aqdefault\(aq but it\(aqs possible
# to use this setting to create instances belonging to a different
# network resource.
#
network: default
# GCE supports instance/network tags and this setting allows you to
# set custom tags. It should be a list of strings and must be
# parse\-able by the python ast.literal_eval() function to convert it
# to a python list.
#
tags: \(aq["one", "two", "three"]\(aq
# GCE supports instance metadata and this setting allows you to
# set custom metadata. It should be a hash of key/value strings and
# parse\-able by the python ast.literal_eval() function to convert it
# to a python dictionary.
#
metadata: \(aq{"one": "1", "2": "two"}\(aq
# Use this setting to ensure that when new instances are created,
# they will use a persistent disk to preserve data between instance
# terminations and re\-creations.
#
use_persistent_disk: True
# In the event that you wish the boot persistent disk to be permanently
# deleted when you destroy an instance, set delete_boot_pd to True.
#
delete_boot_pd: False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
GCE instances do not allow remote access to the root user by default.
Instead, another user must be used to run the deploy script using sudo.
Append something like this to \fB/etc/salt/cloud.profiles\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
all_settings:
...
# SSH to GCE instances as gceuser
ssh_username: gceuser
# Use the local private SSH key file located here
ssh_keyfile: /etc/cloud/google_compute_engine
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have not already used this SSH key to login to instances in this
GCE project you will also need to add the public key to your projects
metadata at \fI\%https://cloud.google.com/console\fP\&. You could also add it via
the metadata setting too:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
all_settings:
...
metadata: \(aq{"one": "1", "2": "two",
"sshKeys": "gceuser:ssh\-rsa <Your SSH Public Key> gceuser@host"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Single instance details
.sp
This action is a thin wrapper around \fB\-\-full\-query\fP, which displays details on a
single instance only. In an environment with several machines, this will save a
user from having to sort through all instance data, just to examine a single
instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_instance myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Destroy, persistent disks, and metadata
.sp
As noted in the provider configuration, it\(aqs possible to force the boot
persistent disk to be deleted when you destroy the instance. The way that
this has been implemented is to use the instance metadata to record the
cloud profile used when creating the instance. When \fBdestroy\fP is called,
if the instance contains a \fBsalt\-cloud\-profile\fP key, it\(aqs value is used
to reference the matching profile to determine if \fBdelete_boot_pd\fP is
set to \fBTrue\fP\&.
.sp
Be aware that any GCE instances created with salt cloud will contain this
custom \fBsalt\-cloud\-profile\fP metadata entry.
.SS List various resources
.sp
It\(aqs also possible to list several GCE resources similar to what can be done
with other providers. The following commands can be used to list GCE zones
(locations), machine types (sizes), and images.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-locations gce
salt\-cloud \-\-list\-sizes gce
salt\-cloud \-\-list\-images gce
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Persistent Disk
.sp
The Compute Engine provider provides functions via salt\-cloud to manage your
Persistent Disks. You can create and destroy disks as well as attach and
detach them from running instances.
.SS Create
.sp
When creating a disk, you can create an empty disk and specify its size (in
GB), or specify either an \(aqimage\(aq or \(aqsnapshot\(aq.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_disk gce disk_name=pd location=us\-central1\-b size=200
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Delete
.sp
Deleting a disk only requires the name of the disk to delete
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_disk gce disk_name=old\-backup
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Attach
.sp
Attaching a disk to an existing instance is really an \(aqaction\(aq and requires
both an instance name and disk name. It\(aqs possible to use this ation to
create bootable persistent disks if necessary. Compute Engine also supports
attaching a persistent disk in READ_ONLY mode to multiple instances at the
same time (but then cannot be attached in READ_WRITE to any instance).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a attach_disk myinstance disk_name=pd mode=READ_WRITE boot=yes
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Detach
.sp
Detaching a disk is also an action against an instance and only requires
the name of the disk. Note that this does \fInot\fP safely sync and umount the
disk from the instance. To ensure no data loss, you must first make sure the
disk is unmounted from the instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a detach_disk myinstance disk_name=pd
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Show disk
.sp
It\(aqs also possible to look up the details for an existing disk with either
a function or an action.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_disk myinstance disk_name=pd
salt\-cloud \-f show_disk gce disk_name=pd
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Create snapshot
.sp
You can take a snapshot of an existing disk\(aqs content. The snapshot can then
in turn be used to create other persistent disks. Note that to prevent data
corruption, it is strongly suggested that you unmount the disk prior to
taking a snapshot. You must name the snapshot and provide the name of the
disk.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_snapshot gce name=backup\-20140226 disk_name=pd
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Delete snapshot
.sp
You can delete a snapshot when it\(aqs no longer needed by specifying the name
of the snapshot.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_snapshot gce name=backup\-20140226
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Show snapshot
.sp
Use this function to look up information about the snapshot.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_snapshot gce name=backup\-20140226
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Networking
.sp
Compute Engine supports multiple private networks per project. Instances
within a private network can easily communicate with each other by an
internal DNS service that resolves instance names. Instances within a private
network can also communicate with either directly without needing special
routing or firewall rules even if they span different regions/zones.
.sp
Networks also support custom firewall rules. By default, traffic between
instances on the same private network is open to all ports and protocols.
Inbound SSH traffic (port 22) is also allowed but all other inbound traffic
is blocked.
.SS Create network
.sp
New networks require a name and CIDR range. New instances can be created
and added to this network by setting the network name during create. It is
not possible to add/remove existing instances to a network.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_network gce name=mynet cidr=10.10.10.0/24
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Destroy network
.sp
Destroy a network by specifying the name. Make sure that there are no
instances associated with the network prior to deleting it or you\(aqll have
a bad day.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_network gce name=mynet
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Show network
.sp
Specify the network name to view information about the network.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_network gce name=mynet
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Create firewall
.sp
You\(aqll need to create custom firewall rules if you want to allow other traffic
than what is described above. For instance, if you run a web service on
your instances, you\(aqll need to explicitly allow HTTP and/or SSL traffic.
The firewall rule must have a name and it will use the \(aqdefault\(aq network
unless otherwise specified with a \(aqnetwork\(aq attribute. Firewalls also support
instance tags for source/destination
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_fwrule gce name=web allow=tcp:80,tcp:443,icmp
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Delete firewall
.sp
Deleting a firewall rule will prevent any previously allowed traffic for the
named firewall rule.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_fwrule gce name=web
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Show firewall
.sp
Use this function to review an existing firewall rule\(aqs information.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_fwrule gce name=web
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Load Balancer
.sp
Compute Engine possess a load\-balancer feature for splitting traffic across
multiple instances. Please reference the
\fI\%documentation\fP
for a more complete discription.
.sp
The load\-balancer functionality is slightly different than that described
in Google\(aqs documentation. The concept of \fITargetPool\fP and \fIForwardingRule\fP
are consolidated in salt\-cloud/libcloud. HTTP Health Checks are optional.
.SS HTTP Health Check
.sp
HTTP Health Checks can be used as a means to toggle load\-balancing across
instance members, or to detect if an HTTP site is functioning. A common
use\-case is to set up a health check URL and if you want to toggle traffic
on/off to an instance, you can temporarily have it return a non\-200 response.
A non\-200 response to the load\-balancer\(aqs health check will keep the LB from
sending any new traffic to the "down" instance. Once the instance\(aqs
health check URL beings returning 200\-responses, the LB will again start to
send traffic to it. Review Compute Engine\(aqs documentation for allowable
parameters. You can use the following salt\-cloud functions to manage your
HTTP health checks.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_hc gce name=myhc path=/ port=80
salt\-cloud \-f delete_hc gce name=myhc
salt\-cloud \-f show_hc gce name=myhc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Load\-balancer
.sp
When creating a new load\-balancer, it requires a name, region, port range,
and list of members. There are other optional parameters for protocol,
and list of health checks. Deleting or showing details about the LB only
requires the name.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_lb gce name=lb region=... ports=80 members=w1,w2,w3
salt\-cloud \-f delete_lb gce name=lb
salt\-cloud \-f show_lb gce name=lb
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Attach and Detach LB
.sp
It is possible to attach or detach an instance from an existing load\-balancer.
Both the instance and load\-balancer must exist before using these functions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f attach_lb gce name=lb member=w4
salt\-cloud \-f detach_lb gce name=lb member=oops
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With HP Cloud
.sp
HP Cloud is a major public cloud platform and uses the libcloud
\fIopenstack\fP driver. The current version of OpenStack that HP Cloud
uses is Havana. When an instance is booted, it must have a
floating IP added to it in order to connect to it and further below
you will see an example that adds context to this statement.
.SS Set up a cloud provider configuration file
.sp
To use the \fIopenstack\fP driver for HP Cloud, set up the cloud
provider configuration file as in the example shown below:
.sp
\fB/etc/salt/cloud.providers.d/hpcloud.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hpcloud\-config:
# Set the location of the salt\-master
#
minion:
master: saltmaster.example.com
# Configure HP Cloud using the OpenStack plugin
#
identity_url: https://region\-b.geo\-1.identity.hpcloudsvc.com:35357/v2.0/tokens
compute_name: Compute
protocol: ipv4
# Set the compute region:
#
compute_region: region\-b.geo\-1
# Configure HP Cloud authentication credentials
#
user: myname
tenant: myname\-project1
password: xxxxxxxxx
# keys to allow connection to the instance launched
#
ssh_key_name: yourkey
ssh_key_file: /path/to/key/yourkey.priv
provider: openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The subsequent example that follows is using the openstack driver.
.SS Compute Region
.sp
Originally, HP Cloud, in its OpenStack Essex version (1.0), had 3
availability zones in one region, US West (region\-a.geo\-1), which
each behaved each as a region.
.sp
This has since changed, and the current OpenStack Havana version of
HP Cloud (1.1) now has simplified this and now has two regions to choose from:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
region\-a.geo\-1 \-> US West
region\-b.geo\-1 \-> US East
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Authentication
.sp
The \fBuser\fP is the same user as is used to log into the HP Cloud management
UI. The \fBtenant\fP can be found in the upper left under "Project/Region/Scope".
It is often named the same as \fBuser\fP albeit with a \fB\-project1\fP appended.
The \fBpassword\fP is of course what you created your account with. The management
UI also has other information such as being able to select US East or US West.
.SS Set up a cloud profile config file
.sp
The profile shown below is a know working profile for an Ubuntu instance. The
profile configuration file is stored in the following location:
.sp
\fB/etc/salt/cloud.profiles.d/hp_ae1_ubuntu.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hp_ae1_ubuntu:
provider: hp_ae1
image: 9302692b\-b787\-4b52\-a3a6\-daebb79cb498
ignore_cidr: 10.0.0.1/24
networks:
\- floating: Ext\-Net
size: standard.small
ssh_key_file: /root/keys/test.key
ssh_key_name: test
ssh_username: ubuntu
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Some important things about the example above:
.INDENT 0.0
.IP \(bu 2
The \fBimage\fP parameter can use either the image name or image ID which you can obtain by running in the example below (this case US East):
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images hp_ae1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
The parameter \fBignore_cidr\fP specifies a range of addresses to ignore when trying to connect to the instance. In this case, it\(aqs the range of IP addresses used for an private IP of the instance.
.IP \(bu 2
The parameter \fBnetworks\fP is very important to include. In previous versions of Salt Cloud, this is what made it possible for salt\-cloud to be able to attach a floating IP to the instance in order to connect to the instance and set up the minion. The current version of salt\-cloud doesn\(aqt require it, though having it is of no harm either. Newer versions of salt\-cloud will use this, and without it, will attempt to find a list of floating IP addresses to use regardless.
.IP \(bu 2
The \fBssh_key_file\fP and \fBssh_key_name\fP are the keys that will make it possible to connect to the instance to set up the minion
.IP \(bu 2
The \fBssh_username\fP parameter, in this case, being that the image used will be ubuntu, will make it possible to not only log in but install the minion
.UNINDENT
.SS Launch an instance
.sp
To instantiate a machine based on this profile (example):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-p hp_ae1_ubuntu ubuntu_instance_1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After several minutes, this will create an instance named ubuntu_instance_1
running in HP Cloud in the US East region and will set up the minion and then
return information about the instance once completed.
.SS Manage the instance
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt ubuntu_instance_1 ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS SSH to the instance
.sp
Additionally, the instance can be accessed via SSH using the floating IP assigned to it
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# ssh ubuntu@<floating ip>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Using a private IP
.sp
Alternatively, in the cloud profile, using the private IP to log into the instance to set up the minion is another option, particularly if salt\-cloud is running within the cloud on an instance that is on the same network with all the other instances (minions)
.sp
The example below is a modified version of the previous example. Note the use of \fBssh_interface\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hp_ae1_ubuntu:
provider: hp_ae1
image: 9302692b\-b787\-4b52\-a3a6\-daebb79cb498
size: standard.small
ssh_key_file: /root/keys/test.key
ssh_key_name: test
ssh_username: ubuntu
ssh_interface: private_ips
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this setup, salt\-cloud will use the private IP address to ssh into the instance and set up the salt\-minion
.SS Getting Started With Joyent
.sp
Joyent is a public cloud provider supporting SmartOS, Linux, FreeBSD and
Windows.
.SS Dependencies
.sp
This driver requires the Python \fBrequests\fP library to be installed.
.SS Configuration
.sp
The Joyent cloud requires three configuration parameters. The user name and
password that are used to log into the Joyent system, and the location of the
private ssh key associated with the Joyent account. The ssh key is needed to
send the provisioning commands up to the freshly created virtual machine.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
my\-joyent\-config:
provider: joyent
user: fred
password: saltybacon
private_key: /root/joyent.pem
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Profiles
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the
\fB/etc/salt/cloud.profiles.d/\fP directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
joyent_512
provider: my\-joyent\-config
size: Extra Small 512 MB
image: Arch Linux 2013.06
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-sizes my\-joyent\-config
my\-joyent\-config:
\-\-\-\-\-\-\-\-\-\-
joyent:
\-\-\-\-\-\-\-\-\-\-
Extra Small 512 MB:
\-\-\-\-\-\-\-\-\-\-
default:
false
disk:
15360
id:
Extra Small 512 MB
memory:
512
name:
Extra Small 512 MB
swap:
1024
vcpus:
1
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images my\-joyent\-config
my\-joyent\-config:
\-\-\-\-\-\-\-\-\-\-
joyent:
\-\-\-\-\-\-\-\-\-\-
base:
\-\-\-\-\-\-\-\-\-\-
description:
A 32\-bit SmartOS image with just essential packages
installed. Ideal for users who are comfortable with setting
up their own environment and tools.
disabled:
False
files:
\-\-\-\-\-\-\-\-\-\-
\- compression:
bzip2
\- sha1:
40cdc6457c237cf6306103c74b5f45f5bf2d9bbe
\- size:
82492182
name:
base
os:
smartos
owner:
352971aa\-31ba\-496c\-9ade\-a379feaecd52
public:
True
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With LXC
.sp
The LXC module is designed to install Salt in an LXC container on a controlled
and possibly remote minion.
.sp
In other words, Salt will connect to a minion, then from that minion:
.INDENT 0.0
.IP \(bu 2
Provision and configure a container for networking access
.IP \(bu 2
Use \fIsaltify\fP to deploy salt and re\-attach to master
.UNINDENT
.SS Limitations
.INDENT 0.0
.IP \(bu 2
You can only act on one minion and one provider at a time.
.IP \(bu 2
Listing images must be targeted to a particular LXC provider (nothing will be
outputted with \fBall\fP)
.UNINDENT
.SS Operation
.sp
Salt\(aqs LXC support does not use lxc.init. This enables it to tie minions
to a master in a more generic fashion (if any masters are defined)
and allows other custom association code.
.sp
Order of operation:
.INDENT 0.0
.IP \(bu 2
Create the LXC container using \fBthe LXC execution module\fP on the desired minion (clone or template)
.IP \(bu 2
Change LXC config options (if any need to be changed)
.IP \(bu 2
Start container
.IP \(bu 2
Change base passwords if any
.IP \(bu 2
Change base DNS configuration if necessary
.IP \(bu 2
Wait for LXC container to be up and ready for ssh
.IP \(bu 2
Test SSH connection and bailout in error
.IP \(bu 2
Via SSH (with the help of saltify), upload deploy script and seeds,
then re\-attach the minion.
.UNINDENT
.SS Provider configuration
.sp
Here is a simple provider configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example goes in /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
devhost10\-lxc:
target: devhost10
provider: lxc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Profile configuration
.sp
Here are the options to configure your containers:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(ga\(gatarget\(ga\(ga
Host minion id to install the lxc Container into
\(ga\(gaprofile\(ga\(ga
Name of the profile containing the LXC configuration
Container creation/clone options:
Create a container by cloning:
\(ga\(gafrom_container\(ga\(ga
Name of an original container using clone
\(ga\(gasnapshot\(ga\(ga
Do we use snapshots on cloned filesystems
Create a container from scratch using an LXC template:
image
template to use
backing
Backing store type (None, lvm, brtfs)
lvname
LVM logical volume name, if any
fstype
Type of filesystem
size
Size of the containera (for brtfs, or lvm)
vgname
LVM Volume Group name, if any
users
Names of the users to be pre\-created inside the container
ssh_username
Username of the SSH systems administrator inside the container
sudo
Do we use sudo
ssh_gateway
if the minion is not in your \(aqtopmaster\(aq network, use
that gateway to connect to the lxc container.
This may be the public ip of the hosting minion
ssh_gateway_key
When using gateway, the ssh key of the gateway user (passed to saltify)
ssh_gateway_port
When using gateway, the ssh port of the gateway (passed to saltify)
ssh_gateway_user
When using gateway, user to login as via SSH (passed to saltify)
password
password for root and sysadmin (see "users" parameter above)
mac
mac address to assign to the container\(aqs network interface
ip
IP address to assign to the container\(aqs network interface
netmask
netmask for the network interface\(aqs IP
bridge
bridge under which the container\(aqs network interface will be enslaved
dnsservers
List of DNS servers to use\-\-this is optional. If present, DNS
servers will be restricted to that list if used
lxc_conf_unset
Configuration variables to unset in this container\(aqs LXC configuration
lxc_conf
LXC configuration variables to add in this container\(aqs LXC configuration
minion
minion configuration (see :doc:\(gaMinion Configuration in Salt Cloud </topics/cloud/config>\(ga)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example would go in /etc/salt/cloud.profile or any file in the
# /etc/salt/cloud.profile.d/ directory.
devhost10\-lxc:
provider: devhost10\-lxc
from_container: ubuntu
backing: lvm
sudo: True
size: 3g
ip: 10.0.3.9
minion:
master: 10.5.0.1
master_port: 4506
lxc_conf:
\- lxc.utsname: superlxc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Driver Support
.INDENT 0.0
.IP \(bu 2
Container creation
.IP \(bu 2
Image listing (LXC templates)
.IP \(bu 2
Running container informations (IP addresses, etc.)
.UNINDENT
.SS Getting Started With Linode
.sp
Linode is a public cloud provider with a focus on Linux instances.
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
Libcloud >= 0.13.2
.UNINDENT
.SS Configuration
.sp
Linode requires a single API key, but the default root password for new
instances also needs to be set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: This example is for /etc/salt/cloud.providers or any file in the
# /etc/salt/cloud.providers.d/ directory.
my\-linode\-config:
apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf
password: F00barbaz
provider: linode
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The password needs to be 8 characters and contain lowercase, uppercase and
numbers.
.SS Profiles
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the
\fB/etc/salt/cloud.profiles.d/\fP directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
linode_1024:
provider: my\-linode\-config
size: Linode 1024
image: Arch Linux 2013.06
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-sizes my\-linode\-config
my\-linode\-config:
\-\-\-\-\-\-\-\-\-\-
linode:
\-\-\-\-\-\-\-\-\-\-
Linode 1024:
\-\-\-\-\-\-\-\-\-\-
bandwidth:
2000
disk:
49152
driver:
get_uuid:
id:
1
name:
Linode 1024
price:
20.0
ram:
1024
uuid:
03e18728ce4629e2ac07c9cbb48afffb8cb499c4
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images my\-linode\-config
my\-linode\-config:
\-\-\-\-\-\-\-\-\-\-
linode:
\-\-\-\-\-\-\-\-\-\-
Arch Linux 2013.06:
\-\-\-\-\-\-\-\-\-\-
driver:
extra:
\-\-\-\-\-\-\-\-\-\-
64bit:
1
pvops:
1
get_uuid:
id:
112
name:
Arch Linux 2013.06
uuid:
8457f92eaffc92b7666b6734a96ad7abe1a8a6dd
\&...SNIP...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With OpenStack
.sp
OpenStack is one the most popular cloud projects. It\(aqs an open source project
to build public and/or private clouds. You can use Salt Cloud to launch
OpenStack instances.
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
Libcloud >= 0.13.2
.UNINDENT
.SS Configuration
.INDENT 0.0
.IP \(bu 2
Using the new format, set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/openstack.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
# Set the location of the salt\-master
#
minion:
master: saltmaster.example.com
# Configure the OpenStack driver
#
identity_url: http://identity.youopenstack.com/v2.0/tokens
compute_name: nova
protocol: ipv4
compute_region: RegionOne
# Configure Openstack authentication credentials
#
user: myname
password: 123456
# tenant is the project name
tenant: myproject
provider: openstack
# skip SSL certificate validation (default false)
insecure: false
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Using nova client to get information from OpenStack
.sp
One of the best ways to get information about OpenStack is using the novaclient
python package (available in pypi as python\-novaclient). The client
configuration is a set of environment variables that you can get from the
Dashboard. Log in and then go to Project \-> Access & security \-> API Access and
download the "OpenStack RC file". Then:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source /path/to/your/rcfile
nova credentials
nova endpoints
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the \fBnova endpoints\fP output you can see the information about
\fBcompute_region\fP and \fBcompute_name\fP\&.
.SS Compute Region
.sp
It depends on the OpenStack cluster that you are using. Please, have a look at
the previous sections.
.SS Authentication
.sp
The \fBuser\fP and \fBpassword\fP is the same user as is used to log into the
OpenStack Dashboard.
.SS Profiles
.sp
Here is an example of a profile:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openstack_512:
provider: my\-openstack\-config
size: m1.tiny
image: cirros\-0.3.1\-x86_64\-uec
ssh_key_file: /tmp/test.pem
ssh_key_name: test
ssh_interface: private_ips
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following list explains some of the important properties.
.INDENT 0.0
.TP
.B size
can be one of the options listed in the output of \fBnova flavor\-list\fP\&.
.TP
.B image
can be one of the options listed in the output of \fBnova image\-list\fP\&.
.TP
.B ssh_key_file
The SSH private key that the salt\-cloud uses to SSH into the VM after its
first booted in order to execute a command or script. This private key\(aqs
\fIpublic key\fP must be the openstack public key inserted into the
authorized_key\(aqs file of the VM\(aqs root user account.
.TP
.B ssh_key_name
The name of the openstack SSH public key that is inserted into the
authorized_keys file of the VM\(aqs root user account. Prior to using this
public key, you must use openstack commands or the horizon web UI to load
that key into the tenant\(aqs account. Note that this openstack tenant must be
the one you defined in the cloud provider.
.TP
.B ssh_interface
This option allows you to create a VM without a public IP. If this option
is omitted and the VM does not have a public IP, then the salt\-cloud waits
for a certain period of time and then destroys the VM.
.UNINDENT
.sp
For more information concerning cloud profiles, see \fBhere\fP\&.
.SS change_password
.sp
If no ssh_key_file is provided, and the server already exists, change_password
will use the api to change the root password of the server so that it can be
bootstrapped.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
change_password: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS userdata_file
.sp
Use \fIuserdata_file\fP to specify the userdata file to upload for use with
cloud\-init if available.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
userdata_file: /etc/salt/cloud\-init/packages.yml
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With Parallels
.sp
Parallels Cloud Server is a product by Parallels that delivers a cloud hosting
solution. The PARALLELS module for Salt Cloud enables you to manage instances
hosted by a provider using PCS. Further information can be found at:
.sp
\fI\%http://www.parallels.com/products/pcs/\fP
.INDENT 0.0
.IP \(bu 2
Using the old format, set up the cloud configuration at \fB/etc/salt/cloud\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com
# Set the PARALLELS access credentials (see below)
#
PARALLELS.user: myuser
PARALLELS.password: badpass
# Set the access URL for your PARALLELS provider
#
PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new format, set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/parallels.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-parallels\-config:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com
# Set the PARALLELS access credentials (see below)
#
user: myuser
password: badpass
# Set the access URL for your PARALLELS provider
#
url: https://api.cloud.xmission.com:4465/paci/v1.0/
provider: parallels
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Access Credentials
.sp
The \fBuser\fP, \fBpassword\fP and \fBurl\fP will be provided to you by your cloud
provider. These are all required in order for the PARALLELS driver to work.
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or
\fB/etc/salt/cloud.profiles.d/parallels.conf\fP:
.INDENT 0.0
.IP \(bu 2
Using the old cloud configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parallels\-ubuntu:
provider: parallels
image: ubuntu\-12.04\-x86_64
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new cloud configuration format and the cloud configuration example
from above:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parallels\-ubuntu:
provider: my\-parallels\-config
image: ubuntu\-12.04\-x86_64
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The profile can be realized now with a salt command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-p parallels\-ubuntu myubuntu
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create an instance named \fBmyubuntu\fP on the cloud provider. The
minion that is installed on this instance will have an \fBid\fP of \fBmyubuntu\fP\&.
If the command was executed on the salt\-master, its Salt key will automatically
be signed on the master.
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt myubuntu test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Required Settings
.sp
The following settings are always required for PARALLELS:
.INDENT 0.0
.IP \(bu 2
Using the old cloud configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
PARALLELS.user: myuser
PARALLELS.password: badpass
PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
Using the new cloud configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-parallels\-config:
user: myuser
password: badpass
url: https://api.cloud.xmission.com:4465/paci/v1.0/
provider: parallels
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Optional Settings
.sp
Unlike other cloud providers in Salt Cloud, Parallels does not utilize a
\fBsize\fP setting. This is because Parallels allows the end\-user to specify a
more detailed configuration for their instances, than is allowed by many other
cloud providers. The following options are available to be used in a profile,
with their default settings listed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Description of the instance. Defaults to the instance name.
desc: <instance_name>
# How many CPU cores, and how fast they are (in MHz)
cpu_number: 1
cpu_power: 1000
# How many megabytes of RAM
ram: 256
# Bandwidth available, in kbps
bandwidth: 100
# How many public IPs will be assigned to this instance
ip_num: 1
# Size of the instance disk (in GiB)
disk_size: 10
# Username and password
ssh_username: root
password: <value from PARALLELS.password>
# The name of the image, from \(ga\(gasalt\-cloud \-\-list\-images parallels\(ga\(ga
image: ubuntu\-12.04\-x86_64
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With Proxmox
.sp
Proxmox Virtual Environment is a complete server virtualization management solution,
based on KVM virtualization and OpenVZ containers.
Further information can be found at:
.sp
\fI\%http://www.proxmox.org/\fP
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
IPy >= 0.81
.IP \(bu 2
requests >= 2.2.1
.UNINDENT
.sp
Please note:
This module allows you to create both OpenVZ and KVM but installing Salt on it will only be
done when the VM is an OpenVZ container rather than a KVM virtual machine.
.INDENT 0.0
.IP \(bu 2
Set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/proxmox.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-proxmox\-config:
# Set up the location of the salt master
#
minion:
master: saltmaster.example.com
# Set the PROXMOX access credentials (see below)
#
user: myuser@pve
password: badpass
# Set the access URL for your PROXMOX provider
#
url: your.proxmox.host
provider: proxmox
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Access Credentials
.sp
The \fBuser\fP, \fBpassword\fP and \fBurl\fP will be provided to you by your cloud
provider. These are all required in order for the PROXMOX driver to work.
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or
\fB/etc/salt/cloud.profiles.d/proxmox.conf\fP:
.INDENT 0.0
.IP \(bu 2
Configure a profile to be used:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proxmox\-ubuntu:
provider: proxmox
image: local:vztmpl/ubuntu\-12.04\-standard_12.04\-1_amd64.tar.gz
technology: openvz
host: myvmhost
ip_address: 192.168.100.155
password: topsecret
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The profile can be realized now with a salt command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-p proxmox\-ubuntu myubuntu
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create an instance named \fBmyubuntu\fP on the cloud provider. The
minion that is installed on this instance will have a \fBhostname\fP of \fBmyubuntu\fP\&.
If the command was executed on the salt\-master, its Salt key will automatically
be signed on the master.
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt myubuntu test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Required Settings
.sp
The following settings are always required for PROXMOX:
.INDENT 0.0
.IP \(bu 2
Using the new cloud configuration format:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-proxmox\-config:
provider: proxmox
user: saltcloud@pve
password: xyzzy
url: your.proxmox.host
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Optional Settings
.sp
Unlike other cloud providers in Salt Cloud, Proxmox does not utilize a
\fBsize\fP setting. This is because Proxmox allows the end\-user to specify a
more detailed configuration for their instances, than is allowed by many other
cloud providers. The following options are available to be used in a profile,
with their default settings listed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Description of the instance.
desc: <instance_name>
# How many CPU cores, and how fast they are (in MHz)
cpus: 1
cpuunits: 1000
# How many megabytes of RAM
memory: 256
# How much swap space in MB
swap: 256
# Whether to auto boot the vm after the host reboots
onboot: 1
# Size of the instance disk (in GiB)
disk: 10
# Host to create this vm on
host: myvmhost
# Nameservers. Defaults to host
nameserver: 8.8.8.8 8.8.4.4
# Username and password
ssh_username: root
password: <value from PROXMOX.password>
# The name of the image, from \(ga\(gasalt\-cloud \-\-list\-images proxmox\(ga\(ga
image: local:vztmpl/ubuntu\-12.04\-standard_12.04\-1_amd64.tar.gz
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With Rackspace
.sp
Rackspace is a major public cloud platform which may be configured using either
the \fIrackspace\fP or the \fIopenstack\fP driver, depending on your needs.
.sp
Please note that the \fIrackspace\fP driver is only intended for 1st gen instances,
aka, "the old cloud" at Rackspace. It is required for 1st gen instances, but
will \fInot\fP work with OpenStack\-based instances. Unless you explicitly have a
reason to use it, it is highly recommended that you use the \fIopenstack\fP driver
instead.
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
Libcloud >= 0.13.2
.UNINDENT
.SS Configuration
.INDENT 0.0
.TP
.B To use the \fIopenstack\fP driver (recommended), set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/rackspace.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-rackspace\-config:
# Set the location of the salt\-master
#
minion:
master: saltmaster.example.com
# Configure Rackspace using the OpenStack plugin
#
identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/tokens\(aq
compute_name: cloudServersOpenStack
protocol: ipv4
# Set the compute region:
#
compute_region: DFW
# Configure Rackspace authentication credentials
#
user: myname
tenant: 123456
apikey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
provider: openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B To use the \fIrackspace\fP driver, set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/rackspace.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-rackspace\-config:
provider: rackspace
# The Rackspace login user
user: fred
# The Rackspace user\(aqs apikey
apikey: 901d3f579h23c8v73q9
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The settings that follow are for using Rackspace with the \fIopenstack\fP driver,
and will not work with the \fIrackspace\fP driver.
.SS Compute Region
.sp
Rackspace currently has six compute regions which may be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
DFW \-> Dallas/Forth Worth
ORD \-> Chicago
SYD \-> Sydney
LON \-> London
IAD \-> Northern Virginia
HKG \-> Hong Kong
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note: Currently the LON region is only available with a UK account, and UK accounts cannot access other regions
.SS Authentication
.sp
The \fBuser\fP is the same user as is used to log into the Rackspace Control
Panel. The \fBtenant\fP and \fBapikey\fP can be found in the API Keys area of the
Control Panel. The \fBapikey\fP will be labeled as API Key (and may need to be
generated), and \fBtenant\fP will be labeled as Cloud Account Number.
.sp
An initial profile can be configured in \fB/etc/salt/cloud.profiles\fP or
\fB/etc/salt/cloud.profiles.d/rackspace.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openstack_512:
provider: my\-rackspace\-config
size: 512 MB Standard
image: Ubuntu 12.04 LTS (Precise Pangolin)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To instantiate a machine based on this profile:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-p openstack_512 myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create a virtual machine at Rackspace with the name \fBmyinstance\fP\&.
This operation may take several minutes to complete, depending on the current
load at the Rackspace data center.
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt myinstance test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS RackConnect Environments
.sp
Rackspace offers a hybrid hosting configuration option called RackConnect that
allows you to use a physical firewall appliance with your cloud servers. When
this service is in use the public_ip assigned by nova will be replaced by a NAT
ip on the firewall. For salt\-cloud to work properly it must use the newly
assigned "access ip" instead of the Nova assigned public ip. You can enable that
capability by adding this to your profiles:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openstack_512:
provider: my\-openstack\-config
size: 512 MB Standard
image: Ubuntu 12.04 LTS (Precise Pangolin)
rackconnect: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Managed Cloud Environments
.sp
Rackspace offers a managed service level of hosting. As part of the managed
service level you have the ability to choose from base of lamp installations on
cloud server images. The post build process for both the base and the lamp
installations used Chef to install things such as the cloud monitoring agent and
the cloud backup agent. It also takes care of installing the lamp stack if
selected. In order to prevent the post installation process from stomping over
the bootstrapping you can add the below to your profiles.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openstack_512:
provider: my\-rackspace\-config
size: 512 MB Standard
image: Ubuntu 12.04 LTS (Precise Pangolin)
managedcloud: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS First and Next Generation Images
.sp
Rackspace provides two sets of virtual machine images, \fIfirst\fP and \fInext\fP
generation. As of \fB0.8.9\fP salt\-cloud will default to using the \fInext\fP
generation images. To force the use of first generation images, on the profile
configuration please add:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
FreeBSD\-9.0\-512:
provider: my\-rackspace\-config
size: 512 MB Standard
image: FreeBSD 9.0
force_first_gen: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting Started With SoftLayer
.sp
SoftLayer is a public cloud provider, and baremetal hardware hosting provider.
.SS Dependencies
.sp
The SoftLayer driver for Salt Cloud requires the softlayer package, which is
available at PyPI:
.sp
\fI\%https://pypi.python.org/pypi/SoftLayer\fP
.sp
This package can be installed using \fIpip\fP or \fIeasy_install\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# pip install softlayer
# easy_install softlayer
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configuration
.sp
Set up the cloud config at \fB/etc/salt/cloud.providers\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note: These examples are for /etc/salt/cloud.providers
my\-softlayer:
# Set up the location of the salt master
minion:
master: saltmaster.example.com
# Set the SoftLayer access credentials (see below)
user: MYUSER1138
apikey: \(aqe3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9\(aq
provider: softlayer
my\-softlayer\-hw:
# Set up the location of the salt master
minion:
master: saltmaster.example.com
# Set the SoftLayer access credentials (see below)
user: MYUSER1138
apikey: \(aqe3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9\(aq
provider: softlayer_hw
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Access Credentials
.sp
The \fIuser\fP setting is the same user as is used to log into the SoftLayer
Administration area. The \fIapikey\fP setting is found inside the Admin area after
logging in:
.INDENT 0.0
.IP \(bu 2
Hover over the \fIAdministrative\fP menu item.
.IP \(bu 2
Click the \fIAPI Access\fP link.
.IP \(bu 2
The \fIapikey\fP is located next to the \fIuser\fP setting.
.UNINDENT
.SS Profiles
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base_softlayer_ubuntu:
provider: my\-softlayer
image: UBUNTU_LATEST
cpu_number: 1
ram: 1024
disk_size: 100
local_disk: True
hourly_billing: True
domain: example.com
location: sjc01
# Optional
max_net_speed: 1000
private_vlan: 396
private_network: True
private_ssh: True
# May be used _instead_of_ image
global_identifier: 320d8be5\-46c0\-dead\-cafe\-13e3c51
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Most of the above items are required; optional items are specified below.
.SS image
.sp
Images to build an instance can be found using the \fI\-\-list\-images\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images my\-softlayer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The setting used will be labeled as \fItemplate\fP\&.
.SS cpu_number
.sp
This is the number of CPU cores that will be used for this instance. This
number may be dependent upon the image that is used. For instance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (1 \- 4 Core):
\-\-\-\-\-\-\-\-\-\-
name:
Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (1 \- 4 Core)
template:
REDHAT_6_64
Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (5 \- 100 Core):
\-\-\-\-\-\-\-\-\-\-
name:
Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (5 \- 100 Core)
template:
REDHAT_6_64
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the template (meaning, the \fIimage\fP option) for both of these is the
same, but the names suggests how many CPU cores are supported.
.SS ram
.sp
This is the amount of memory, in megabytes, that will be allocated to this
instance.
.SS disk_size
.sp
The amount of disk space that will be allocated to this image, in megabytes.
.SS local_disk
.sp
When true the disks for the computing instance will be provisioned on the host
which it runs, otherwise SAN disks will be provisioned.
.SS hourly_billing
.sp
When true the computing instance will be billed on hourly usage, otherwise it
will be billed on a monthly basis.
.SS domain
.sp
The domain name that will be used in the FQDN (Fully Qualified Domain Name) for
this instance. The \fIdomain\fP setting will be used in conjunction with the
instance name to form the FQDN.
.SS location
.sp
Images to build an instance can be found using the \fI\-\-list\-locations\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-location my\-softlayer
.ft P
.fi
.UNINDENT
.UNINDENT
.SS max_net_speed
.sp
Specifies the connection speed for the instance\(aqs network components. This
setting is optional. By default, this is set to 10.
.SS public_vlan
.sp
If it is necessary for an instance to be created within a specific frontend
VLAN, the ID for that VLAN can be specified in either the provider or profile
configuration.
.sp
This ID can be queried using the \fIlist_vlans\fP function, as described below. This
setting is optional.
.SS private_vlan
.sp
If it is necessary for an instance to be created within a specific backend VLAN,
the ID for that VLAN can be specified in either the provider or profile
configuration.
.sp
This ID can be queried using the \fIlist_vlans\fP function, as described below. This
setting is optional.
.SS private_network
.sp
If a server is to only be used internally, meaning it does not have a public
VLAN associated with it, this value would be set to True. This setting is
optional. The default is False.
.SS private_ssh
.sp
Whether to run the deploy script on the server using the public IP address
or the private IP address. If set to True, Salt Cloud will attempt to SSH into
the new server using the private IP address. The default is False. This
settiong is optional.
.SS global_identifier
.sp
When creating an instance using a custom template, this option is set to the
corresponding value obtained using the \fIlist_custom_images\fP function. This
option will not be used if an \fIimage\fP is set, and if an \fIimage\fP is not set, it
is required.
.sp
The profile can be realized now with a salt command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-p base_softlayer_ubuntu myserver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using the above configuration, this will create \fImyserver.example.com\fP\&.
.sp
Once the instance has been created with salt\-minion installed, connectivity to
it can be verified with Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aqmyserver.example.com\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cloud Profiles
.sp
Set up an initial profile at \fB/etc/salt/cloud.profiles\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base_softlayer_hw_centos:
provider: my\-softlayer\-hw
# CentOS 6.0 \- Minimal Install (64 bit)
image: 13963
# 2 x 2.0 GHz Core Bare Metal Instance \- 2 GB Ram
size: 1921
# 250GB SATA II
hdd: 19
# San Jose 01
location: 168642
domain: example.com
# Optional
vlan: 396
port_speed: 273
banwidth: 248
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Most of the above items are required; optional items are specified below.
.SS image
.sp
Images to build an instance can be found using the \fI\-\-list\-images\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images my\-softlayer\-hw
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A list of \fIid\(gas and names will be provided. The \(ganame\fP will describe the
operating system and architecture. The \fIid\fP will be the setting to be used in
the profile.
.SS size
.sp
Sizes to build an instance can be found using the \fI\-\-list\-sizes\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-sizes my\-softlayer\-hw
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A list of \fIid\(gas and names will be provided. The \(ganame\fP will describe the speed
and quantity of CPU cores, and the amount of memory that the hardware will
contain. The \fIid\fP will be the setting to be used in the profile.
.SS hdd
.sp
There are currently two sizes of hard disk drive (HDD) that are available for
hardware instances on SoftLayer:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
19: 250GB SATA II
1267: 500GB SATA II
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIhdd\fP setting in the profile will be either 19 or 1267. Other sizes may be
added in the future.
.SS location
.sp
Locations to build an instance can be found using the \fI\-\-list\-images\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-locations my\-softlayer\-hw
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A list of IDs and names will be provided. The \fIlocation\fP will describe the
location in human terms. The \fIid\fP will be the setting to be used in the profile.
.SS domain
.sp
The domain name that will be used in the FQDN (Fully Qualified Domain Name) for
this instance. The \fIdomain\fP setting will be used in conjunction with the
instance name to form the FQDN.
.SS vlan
.sp
If it is necessary for an instance to be created within a specific VLAN, the ID
for that VLAN can be specified in either the provider or profile configuration.
.sp
This ID can be queried using the \fIlist_vlans\fP function, as described below.
.SS port_speed
.sp
Specifies the speed for the instance\(aqs network port. This setting refers to an
ID within the SoftLayer API, which sets the port speed. This setting is
optional. The default is 273, or, 100 Mbps Public & Private Networks. The
following settings are available:
.INDENT 0.0
.IP \(bu 2
273: 100 Mbps Public & Private Networks
.IP \(bu 2
274: 1 Gbps Public & Private Networks
.IP \(bu 2
21509: 10 Mbps Dual Public & Private Networks (up to 20 Mbps)
.IP \(bu 2
21513: 100 Mbps Dual Public & Private Networks (up to 200 Mbps)
.IP \(bu 2
2314: 1 Gbps Dual Public & Private Networks (up to 2 Gbps)
.IP \(bu 2
272: 10 Mbps Public & Private Networks
.UNINDENT
.SS bandwidth
.sp
Specifies the network bandwidth available for the instance. This setting refers
to an ID within the SoftLayer API, which sets the bandwidth. This setting is
optional. The default is 248, or, 5000 GB Bandwidth. The following settings are
available:
.INDENT 0.0
.IP \(bu 2
248: 5000 GB Bandwidth
.IP \(bu 2
129: 6000 GB Bandwidth
.IP \(bu 2
130: 8000 GB Bandwidth
.IP \(bu 2
131: 10000 GB Bandwidth
.IP \(bu 2
36: Unlimited Bandwidth (10 Mbps Uplink)
.IP \(bu 2
125: Unlimited Bandwidth (100 Mbps Uplink)
.UNINDENT
.SS Actions
.sp
The following actions are currently supported by the SoftLayer Salt Cloud
driver.
.SS show_instance
.sp
This action is a thin wrapper around \fI\-\-full\-query\fP, which displays details on a
single instance only. In an environment with several machines, this will save a
user from having to sort through all instance data, just to examine a single
instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-a show_instance myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Functions
.sp
The following functions are currently supported by the SoftLayer Salt Cloud
driver.
.SS list_vlans
.sp
This function lists all VLANs associated with the account, and all known data
from the SoftLayer API concerning those VLANs.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-f list_vlans my\-softlayer
$ salt\-cloud \-f list_vlans my\-softlayer\-hw
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIid\fP returned in this list is necessary for the \fIvlan\fP option when creating
an instance.
.SS list_custom_images
.sp
This function lists any custom templates associated with the account, that can
be used to create a new instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-cloud \-f list_custom_images my\-softlayer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIglobalIdentifier\fP returned in this list is necessary for the
\fIglobal_identifier\fP option when creating an image using a custom template.
.SS Optional Products for SoftLayer HW
.sp
The softlayer_hw provider supports the ability to add optional products, which
are supported by SoftLayer\(aqs API. These products each have an ID associated with
them, that can be passed into Salt Cloud with the \fIoptional_products\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
softlayer_hw_test:
provider: my\-softlayer\-hw
# CentOS 6.0 \- Minimal Install (64 bit)
image: 13963
# 2 x 2.0 GHz Core Bare Metal Instance \- 2 GB Ram
size: 1921
# 250GB SATA II
hdd: 19
# San Jose 01
location: 168642
domain: example.com
optional_products:
# MySQL for Linux
\- id: 28
# Business Continuance Insurance
\- id: 104
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These values can be manually obtained by looking at the source of an order page
on the SoftLayer web interface. For convenience, many of these values are listed
here:
.SS Public Secondary IP Addresses
.INDENT 0.0
.IP \(bu 2
22: 4 Public IP Addresses
.IP \(bu 2
23: 8 Public IP Addresses
.UNINDENT
.SS Primary IPv6 Addresses
.INDENT 0.0
.IP \(bu 2
17129: 1 IPv6 Address
.UNINDENT
.SS Public Static IPv6 Addresses
.INDENT 0.0
.IP \(bu 2
1481: /64 Block Static Public IPv6 Addresses
.UNINDENT
.SS OS\-Specific Addon
.INDENT 0.0
.IP \(bu 2
17139: XenServer Advanced for XenServer 6.x
.IP \(bu 2
17141: XenServer Enterprise for XenServer 6.x
.IP \(bu 2
2334: XenServer Advanced for XenServer 5.6
.IP \(bu 2
2335: XenServer Enterprise for XenServer 5.6
.IP \(bu 2
13915: Microsoft WebMatrix
.IP \(bu 2
21276: VMware vCenter 5.1 Standard
.UNINDENT
.SS Control Panel Software
.INDENT 0.0
.IP \(bu 2
121: cPanel/WHM with Fantastico and RVskin
.IP \(bu 2
20778: Parallels Plesk Panel 11 (Linux) 100 Domain w/ Power Pack
.IP \(bu 2
20786: Parallels Plesk Panel 11 (Windows) 100 Domain w/ Power Pack
.IP \(bu 2
20787: Parallels Plesk Panel 11 (Linux) Unlimited Domain w/ Power Pack
.IP \(bu 2
20792: Parallels Plesk Panel 11 (Windows) Unlimited Domain w/ Power Pack
.IP \(bu 2
2340: Parallels Plesk Panel 10 (Linux) 100 Domain w/ Power Pack
.IP \(bu 2
2339: Parallels Plesk Panel 10 (Linux) Unlimited Domain w/ Power Pack
.IP \(bu 2
13704: Parallels Plesk Panel 10 (Windows) Unlimited Domain w/ Power Pack
.UNINDENT
.SS Database Software
.INDENT 0.0
.IP \(bu 2
29: MySQL 5.0 for Windows
.IP \(bu 2
28: MySQL for Linux
.IP \(bu 2
21501: Riak 1.x
.IP \(bu 2
20893: MongoDB
.IP \(bu 2
30: Microsoft SQL Server 2005 Express
.IP \(bu 2
92: Microsoft SQL Server 2005 Workgroup
.IP \(bu 2
90: Microsoft SQL Server 2005 Standard
.IP \(bu 2
94: Microsoft SQL Server 2005 Enterprise
.IP \(bu 2
1330: Microsoft SQL Server 2008 Express
.IP \(bu 2
1340: Microsoft SQL Server 2008 Web
.IP \(bu 2
1337: Microsoft SQL Server 2008 Workgroup
.IP \(bu 2
1334: Microsoft SQL Server 2008 Standard
.IP \(bu 2
1331: Microsoft SQL Server 2008 Enterprise
.IP \(bu 2
2179: Microsoft SQL Server 2008 Express R2
.IP \(bu 2
2173: Microsoft SQL Server 2008 Web R2
.IP \(bu 2
2183: Microsoft SQL Server 2008 Workgroup R2
.IP \(bu 2
2180: Microsoft SQL Server 2008 Standard R2
.IP \(bu 2
2176: Microsoft SQL Server 2008 Enterprise R2
.UNINDENT
.SS Anti\-Virus & Spyware Protection
.INDENT 0.0
.IP \(bu 2
594: McAfee VirusScan Anti\-Virus \- Windows
.IP \(bu 2
414: McAfee Total Protection \- Windows
.UNINDENT
.SS Insurance
.INDENT 0.0
.IP \(bu 2
104: Business Continuance Insurance
.UNINDENT
.SS Monitoring
.INDENT 0.0
.IP \(bu 2
55: Host Ping
.IP \(bu 2
56: Host Ping and TCP Service Monitoring
.UNINDENT
.SS Notification
.INDENT 0.0
.IP \(bu 2
57: Email and Ticket
.UNINDENT
.SS Advanced Monitoring
.INDENT 0.0
.IP \(bu 2
2302: Monitoring Package \- Basic
.IP \(bu 2
2303: Monitoring Package \- Advanced
.IP \(bu 2
2304: Monitoring Package \- Premium Application
.UNINDENT
.SS Response
.INDENT 0.0
.IP \(bu 2
58: Automated Notification
.IP \(bu 2
59: Automated Reboot from Monitoring
.IP \(bu 2
60: 24x7x365 NOC Monitoring, Notification, and Response
.UNINDENT
.SS Intrusion Detection & Protection
.INDENT 0.0
.IP \(bu 2
413: McAfee Host Intrusion Protection w/Reporting
.UNINDENT
.SS Hardware & Software Firewalls
.INDENT 0.0
.IP \(bu 2
411: APF Software Firewall for Linux
.IP \(bu 2
894: Microsoft Windows Firewall
.IP \(bu 2
410: 10Mbps Hardware Firewall
.IP \(bu 2
409: 100Mbps Hardware Firewall
.IP \(bu 2
408: 1000Mbps Hardware Firewall
.UNINDENT
.SS Getting Started with VEXXHOST
.sp
\fI\%VEXXHOST\fP is an cloud computing provider which provides
\fI\%Canadian cloud computing\fP services
which are based in Monteral and uses the libcloud OpenStack driver. VEXXHOST
currently runs the Havana release of OpenStack. When provisioning new
instances, they automatically get a public IP and private IP address.
Therefore, you do not need to assign a floating IP to access your instance
once it\(aqs booted.
.SS Cloud Provider Configuration
.sp
To use the \fIopenstack\fP driver for the VEXXHOST public cloud, you will need to
set up the cloud provider configuration file as in the example below:
.sp
\fB/etc/salt/cloud.providers.d/vexxhost.conf\fP:
In order to use the VEXXHOST public cloud, you will need to setup a cloud
provider configuration file as in the example below which uses the OpenStack
driver.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vexxhost:
# Set the location of the salt\-master
#
minion:
master: saltmaster.example.com
# Configure VEXXHOST using the OpenStack plugin
#
identity_url: http://auth.api.thenebulacloud.com:5000/v2.0/tokens
compute_name: nova
# Set the compute region:
#
compute_region: na\-yul\-nhs1
# Configure VEXXHOST authentication credentials
#
user: your\-tenant\-id
password: your\-api\-key
tenant: your\-tenant\-name
# keys to allow connection to the instance launched
#
ssh_key_name: yourkey
ssh_key_file: /path/to/key/yourkey.priv
provider: openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Authentication
.sp
All of the authentication fields that you need can be found by logging into
your VEXXHOST customer center. Once you\(aqve logged in, you will need to click
on "CloudConsole" and then click on "API Credentials".
.SS Cloud Profile Configuration
.sp
In order to get the correct image UUID and the instance type to use in the
cloud profile, you can run the following command respectively:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-\-list\-images=vexxhost\-config
# salt\-cloud \-\-list\-sizes=vexxhost\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once you have that, you can go ahead and create a new cloud profile. This
profile will build an Ubuntu 12.04 LTS \fInb.2G\fP instance.
.sp
\fB/etc/salt/cloud.profiles.d/vh_ubuntu1204_2G.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vh_ubuntu1204_2G:
provider: vexxhost
image: 4051139f\-750d\-4d72\-8ef0\-074f2ccc7e5a
size: nb.2G
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Provision an instance
.sp
To create an instance based on the sample profile that we created above, you
can run the following \fIsalt\-cloud\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-p vh_ubuntu1204_2G vh_instance1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Typically, instances are provisioned in under 30 seconds on the VEXXHOST public
cloud. After the instance provisions, it will be set up a minion and then
return all the instance information once it\(aqs complete.
.sp
Once the instance has been setup, you can test connectivity to it by running
the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt vh_instance1 test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can now continue to provision new instances and they will all automatically
be set up as minions of the master you\(aqve defined in the configuration file.
.SS Miscellaneous Options
.SS Miscellaneous Salt Cloud Options
.sp
This page describes various miscellaneous options available in Salt Cloud
.SS Deploy Script Arguments
.sp
Custom deploy scripts are unlikely to need custom arguments to be passed to
them, but salt\-bootstrap has been extended quite a bit, and this may be
necessary. script_args can be specified in either the profile or the map file,
to pass arguments to the deploy script:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ec2\-amazon:
provider: ec2
image: ami\-1624987f
size: Micro Instance
ssh_username: ec2\-user
script: bootstrap\-salt
script_args: \-c /tmp/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This has also been tested to work with pipes, if needed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
script_args: | head
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Sync After Install
.sp
Salt allows users to create custom modules, grains and states which can be
synchronised to minions to extend Salt with further functionality.
.sp
This option will inform Salt Cloud to synchronise your custom modules, grains,
states or all these to the minion just after it has been created. For this to
happen, the following line needs to be added to the main cloud
configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sync_after_install: all
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The available options for this setting are:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
modules
grains
states
all
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setting up New Salt Masters
.sp
It has become increasingly common for users to set up multi\-hierarchal
infrastructures using Salt Cloud. This sometimes involves setting up an
instance to be a master in addition to a minion. With that in mind, you can
now lay down master configuration on a machine by specifying master options
in the profile or map file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make_master: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will cause Salt Cloud to generate master keys for the instance, and tell
salt\-bootstrap to install the salt\-master package, in addition to the
salt\-minion package.
.sp
The default master configuration is usually appropriate for most users, and
will not be changed unless specific master configuration has been added to the
profile or map:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master:
user: root
interface: 0.0.0.0
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Delete SSH Keys
.sp
When Salt Cloud deploys an instance, the SSH pub key for the instance is added
to the known_hosts file for the user that ran the salt\-cloud command. When an
instance is deployed, a cloud provider generally recycles the IP address for
the instance. When Salt Cloud attempts to deploy an instance using a recycled
IP address that has previously been accessed from the same machine, the old key
in the known_hosts file will cause a conflict.
.sp
In order to mitigate this issue, Salt Cloud can be configured to remove old
keys from the known_hosts file when destroying the node. In order to do this,
the following line needs to be added to the main cloud configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
delete_sshkeys: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Keeping /tmp/ Files
.sp
When Salt Cloud deploys an instance, it uploads temporary files to /tmp/ for
salt\-bootstrap to put in place. After the script has run, they are deleted. To
keep these files around (mostly for debugging purposes), the \-\-keep\-tmp option
can be added:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p myprofile mymachine \-\-keep\-tmp
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For those wondering why /tmp/ was used instead of /root/, this had to be done
for images which require the use of sudo, and therefore do not allow remote
root logins, even for file transfers (which makes /root/ unavailable).
.SS Hide Output From Minion Install
.sp
By default Salt Cloud will stream the output from the minion deploy script
directly to STDOUT. Although this can been very useful, in certain cases you
may wish to switch this off. The following config option is there to enable or
disable this output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
display_ssh_output: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Connection Timeout
.sp
There are several stages when deploying Salt where Salt Cloud needs to wait for
something to happen. The VM getting it\(aqs IP address, the VM\(aqs SSH port is
available, etc.
.sp
If you find that the Salt Cloud defaults are not enough and your deployment
fails because Salt Cloud did not wait log enough, there are some settings you
can tweak.
.INDENT 0.0
.INDENT 3.5
.IP "Note"
.sp
All values should be provided in seconds
.UNINDENT
.UNINDENT
.sp
You can tweak these settings globally, per cloud provider, or event per profile
definition.
.SS wait_for_ip_timeout
.sp
The amount of time Salt Cloud should wait for a VM to start and get an IP back
from the cloud provider. Default: 5 minutes.
.SS wait_for_ip_interval
.sp
The amount of time Salt Cloud should sleep while querying for the VM\(aqs IP.
Default: 5 seconds.
.SS ssh_connect_timeout
.sp
The amount of time Salt Cloud should wait for a successful SSH connection to
the VM. Default: 5 minutes.
.SS wait_for_passwd_timeout
.sp
The amount of time until an ssh connection can be established via password or
ssh key. Default 15 seconds.
.SS wait_for_passwd_maxtries
.sp
The number of attempts to connect to the VM until we abandon.
Default 15 attempts
.SS wait_for_fun_timeout
.sp
Some cloud drivers check for an available IP or a successful SSH connection
using a function, namely, SoftLayer and SoftLayer\-HW. So, the amount of time
Salt Cloud should retry such functions before failing. Default: 5 minutes.
.SS wait_for_spot_timeout
.sp
The amount of time Salt Cloud should wait before an EC2 Spot instance is
available. This setting is only available for the EC2 cloud driver.
.SS Salt Cloud Cache
.sp
Salt Cloud can maintain a cache of node data, for supported providers. The
following options manage this functionality.
.SS update_cachedir
.sp
On supported cloud providers, whether or not to maintain a cache of nodes
returned from a \-\-full\-query. The data will be stored in \fBjson\fP format under
\fB<SALT_CACHEDIR>/cloud/active/<DRIVER>/<PROVIDER>/<NODE_NAME>.json\fP\&. This
setting can be True or False.
.SS diff_cache_events
.sp
When the cloud cachedir is being managed, if differences are encountered
between the data that is returned live from the cloud provider and the data in
the cache, fire events which describe the changes. This setting can be True or
False.
.sp
Some of these events will contain data which describe a node. Because some of
the fields returned may contain sensitive data, the \fBcache_event_strip_fields\fP
configuration option exists to strip those fields from the event return.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cache_event_strip_fields:
\- password
\- priv_key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following are events that can be fired based on this data.
.SS salt/cloud/minionid/cache_node_new
.sp
A new node was found on the cloud provider which was not listed in the cloud
cachedir. A dict describing the new node will be contained in the event.
.SS salt/cloud/minionid/cache_node_missing
.sp
A node that was previously listed in the cloud cachedir is no longer available
on the cloud provider.
.SS salt/cloud/minionid/cache_node_diff
.sp
One or more pieces of data in the cloud cachedir has changed on the cloud
provider. A dict containing both the old and the new data will be contained in
the event.
.SS SSH Known Hosts
.sp
Normally when bootstrapping a VM, salt\-cloud will ignore the SSH host key. This
is because it does not know what the host key is before starting (because it
doesn\(aqt exist yet). If strict host key checking is turned on without the key
in the \fBknown_hosts\fP file, then the host will never be available, and cannot
be bootstrapped.
.sp
If a provider is able to determine the host key before trying to bootstrap it,
that provider\(aqs driver can add it to the \fBknown_hosts\fP file, and then turn on
strict host key checking. This can be set up in the main cloud configuration
file (normally \fB/etc/salt/cloud\fP) or in the provider\-specific configuration
file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
known_hosts_file: /path/to/.ssh/known_hosts
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this is not set, it will default to \fB/dev/null\fP, and strict host key
checking will be turned off.
.sp
It is highly recommended that this option is \fInot\fP set, unless the user has
verified that the provider supports this functionality, and that the image
being used is capable of providing the necessary information. At this time,
only the EC2 driver supports this functionality.
.SS Troubleshooting Steps
.SS Troubleshooting Salt Cloud
.sp
This page describes various steps for troubleshooting problems that may arise
while using Salt Cloud.
.SS Virtual Machines Are Created, But Do Not Respond
.sp
Are TCP ports 4505 and 4506 open on the master? This is easy to overlook on new
masters. Information on how to open firewall ports on various platforms can be
found \fBhere\fP\&.
.SS Generic Troubleshooting Steps
.sp
This section describes a set of instructions that are useful to a large number
of situations, and are likely to solve most issues that arise.
.INDENT 0.0
.INDENT 3.5
.IP "Version Compatibility"
.sp
One of the most common issues that Salt Cloud users run into is import
errors. These are often caused by version compatibility issues with Salt.
.sp
Salt 0.16.x works with Salt Cloud 0.8.9 or greater.
.sp
Salt 0.17.x requires Salt Cloud 0.8.11.
.sp
Releases after 0.17.x (0.18 or greater) should not encounter issues as Salt
Cloud has been merged into Salt itself.
.UNINDENT
.UNINDENT
.SS Debug Mode
.sp
Frequently, running Salt Cloud in debug mode will reveal information about a
deployment which would otherwise not be obvious:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p myprofile myinstance \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Keep in mind that a number of messages will appear that look at first like
errors, but are in fact intended to give developers factual information to
assist in debugging. A number of messages that appear will be for cloud
providers that you do not have configured; in these cases, the message usually
is intended to confirm that they are not configured.
.SS Salt Bootstrap
.sp
By default, Salt Cloud uses the Salt Bootstrap script to provision instances:
.sp
This script is packaged with Salt Cloud, but may be updated without updating
the Salt package:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-u
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The Bootstrap Log
.sp
If the default deploy script was used, there should be a file in the \fB/tmp/\fP
directory called \fBbootstrap\-salt.log\fP\&. This file contains the full output from
the deployment, including any errors that may have occurred.
.SS Keeping Temp Files
.sp
Salt Cloud uploads minion\-specific files to instances once they are available
via SSH, and then executes a deploy script to put them into the correct place
and install Salt. The \fB\-\-keep\-tmp\fP option will instruct Salt Cloud not to
remove those files when finished with them, so that the user may inspect them
for problems:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p myprofile myinstance \-\-keep\-tmp
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default, Salt Cloud will create a directory on the target instance called
\fB/tmp/.saltcloud/\fP\&. This directory should be owned by the user that is to
execute the deploy script, and should have permissions of \fB0700\fP\&.
.sp
Most cloud providers are configured to use \fBroot\fP as the default initial user
for deployment, and as such, this directory and all files in it should be owned
by the \fBroot\fP user.
.sp
The \fB/tmp/.saltcloud/\fP directory should the following files:
.INDENT 0.0
.IP \(bu 2
A \fBdeploy.sh\fP script. This script should have permissions of \fB0755\fP\&.
.IP \(bu 2
A \fB\&.pem\fP and \fB\&.pub\fP key named after the minion. The \fB\&.pem\fP file should
have permissions of \fB0600\fP\&. Ensure that the \fB\&.pem\fP and \fB\&.pub\fP files have
been properly copied to the \fB/etc/salt/pki/minion/\fP directory.
.IP \(bu 2
A file called \fBminion\fP\&. This file should have been copied to the
\fB/etc/salt/\fP directory.
.IP \(bu 2
Optionally, a file called \fBgrains\fP\&. This file, if present, should have been
copied to the \fB/etc/salt/\fP directory.
.UNINDENT
.SS Unprivileged Primary Users
.sp
Some providers, most notably EC2, are configured with a different primary user.
Some common examples are \fBec2\-user\fP, \fBubuntu\fP, \fBfedora\fP and \fBbitnami\fP\&.
In these cases, the \fB/tmp/.saltcloud/\fP directory and all files in it should
be owned by this user.
.sp
Some providers, such as EC2, are configured to not require these users to
provide a password when using the \fBsudo\fP command. Because it is more secure
to require \fBsudo\fP users to provide a password, other providers are configured
that way.
.sp
If this instance is required to provide a password, it needs to be configured
in Salt Cloud. A password for sudo to use may be added to either the provider
configuration or the profile configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo_password: mypassword
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fB/tmp/\fP is Mounted as \fBnoexec\fP
.sp
It is more secure to mount the \fB/tmp/\fP directory with a \fBnoexec\fP option.
This is uncommon on most cloud providers, but very common in private
environments. To see if the \fB/tmp/\fP directory is mounted this way, run the
following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mount | grep tmp
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The if the output of this command includes a line that looks like this, then
the \fB/tmp/\fP directory is mounted as \fBnoexec\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tmpfs on /tmp type tmpfs (rw,noexec)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this is the case, then the \fBdeploy_command\fP will need to be changed
in order to run the deploy script through the \fBsh\fP command, rather than trying
to execute it directly. This may be specified in either the provider or the
profile config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
deploy_command: sh /tmp/.saltcloud/deploy.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that by default, Salt Cloud will place its files in a directory
called \fB/tmp/.saltcloud/\fP\&. This may be also be changed in the provider or
profile configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tmp_dir: /tmp/.saltcloud/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this directory is changed, then the \fBdeploy_command\fP need to be changed
in order to reflect the \fBtmp_dir\fP configuration.
.SS Executing the Deploy Script Manually
.sp
If all of the files needed for deployment were successfully uploaded to the
correct locations, and contain the correct permissions and ownerships, the
deploy script may be executed manually in order to check for other issues:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd /tmp/.saltcloud/
\&./deploy.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Extending Salt Cloud
.SS Writing Cloud Provider Modules
.sp
Salt Cloud runs on a module system similar to the main Salt project. The
modules inside saltcloud exist in the \fBsalt/cloud/clouds\fP directory of the
salt source.
.sp
There are two basic types of cloud modules. If a cloud provider is supported by
libcloud, then using it is the fastest route to getting a module written. The
Apache Libcloud project is located at:
.sp
\fI\%http://libcloud.apache.org/\fP
.sp
Not every cloud provider is supported by libcloud. Additionally, not every
feature in a supported cloud provider is necessary supported by libcloud. In
either of these cases, a module can be created which does not rely on libcloud.
.SS All Modules
.sp
The following functions are required by all modules, whether or not they are
based on libcloud.
.SS The __virtual__() Function
.sp
This function determines whether or not to make this cloud module available
upon execution. Most often, it uses \fBget_configured_provider()\fP to determine
if the necessary configuration has been set up. It may also check for necessary
imports, to decide whether to load the module. In most cases, it will return a
\fBTrue\fP or \fBFalse\fP value. If the name of the driver used does not match the
filename, then that name should be returned instead of \fBTrue\fP\&. An example of
this may be seen in the Azure module:
.sp
\fI\%https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/msazure.py\fP
.SS The get_configured_provider() Function
.sp
This function uses \fBconfig.is_provider_configured()\fP to determine wither
all required information for this driver has been configured. The last value
in the list of required settings should be followed by a comma.
.SS Libcloud Based Modules
.sp
Writing a cloud module based on libcloud has two major advantages. First of all,
much of the work has already been done by the libcloud project. Second, most of
the functions necessary to Salt have already been added to the Salt Cloud
project.
.SS The create() Function
.sp
The most important function that does need to be manually written is the
\fBcreate()\fP function. This is what is used to request a virtual machine to be
created by the cloud provider, wait for it to become available, and then
(optionally) log in and install Salt on it.
.sp
A good example to follow for writing a cloud provider module based on libcloud
is the module provided for Linode:
.sp
\fI\%https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/linode.py\fP
.sp
The basic flow of a \fBcreate()\fP function is as follows:
.INDENT 0.0
.IP \(bu 2
Send a request to the cloud provider to create a virtual machine.
.IP \(bu 2
Wait for the virtual machine to become available.
.IP \(bu 2
Generate kwargs to be used to deploy Salt.
.IP \(bu 2
Log into the virtual machine and deploy Salt.
.IP \(bu 2
Return a data structure that describes the newly\-created virtual machine.
.UNINDENT
.sp
At various points throughout this function, events may be fired on the Salt
event bus. Four of these events, which are described below, are required. Other
events may be added by the user, where appropriate.
.sp
When the \fBcreate()\fP function is called, it is passed a data structure called
\fBvm_\fP\&. This dict contains a composite of information describing the virtual
machine to be created. A dict called \fB__opts__\fP is also provided by Salt,
which contains the options used to run Salt Cloud, as well as a set of
configuration and environment variables.
.sp
The first thing the \fBcreate()\fP function must do is fire an event stating that
it has started the create process. This event is tagged
\fBsalt/cloud/<vm name>/creating\fP\&. The payload contains the names of the VM,
profile and provider.
.sp
A set of kwargs is then usually created, to describe the parameters required
by the cloud provider to request the virtual machine.
.sp
An event is then fired to state that a virtual machine is about to be requested.
It is tagged as \fBsalt/cloud/<vm name>/requesting\fP\&. The payload contains most
or all of the parameters that will be sent to the cloud provider. Any private
information (such as passwords) should not be sent in the event.
.sp
After a request is made, a set of deploy kwargs will be generated. These will
be used to install Salt on the target machine. Windows options are supported
at this point, and should be generated, even if the cloud provider does not
currently support Windows. This will save time in the future if the provider
does eventually decide to support Windows.
.sp
An event is then fired to state that the deploy process is about to begin. This
event is tagged \fBsalt/cloud/<vm name>/deploying\fP\&. The payload for the event
will contain a set of deploy kwargs, useful for debugging purposed. Any private
data, including passwords and keys (including public keys) should be stripped
from the deploy kwargs before the event is fired.
.sp
If any Windows options have been passed in, the
\fBsalt.utils.cloud.deploy_windows()\fP function will be called. Otherwise, it
will be assumed that the target is a Linux or Unix machine, and the
\fBsalt.utils.cloud.deploy_script()\fP will be called.
.sp
Both of these functions will wait for the target machine to become available,
then the necessary port to log in, then a successful login that can be used to
install Salt. Minion configuration and keys will then be uploaded to a temporary
directory on the target by the appropriate function. On a Windows target, the
Windows Minion Installer will be run in silent mode. On a Linux/Unix target, a
deploy script (bootstrap\-salt.sh, by default) will be run, which will
auto\-detect the operating system, and install Salt using its native package
manager. These do not need to be handled by the developer in the cloud module.
.sp
After the appropriate deploy function completes, a final event is fired
which describes the virtual machine that has just been created. This event is
tagged \fBsalt/cloud/<vm name>/created\fP\&. The payload contains the names of the
VM, profile and provider.
.sp
Finally, a dict (queried from the provider) which describes the new virtual
machine is returned to the user. Because this data is not fired on the event
bus it can, and should, return any passwords that were returned by the cloud
provider. In some cases (for example, Rackspace), this is the only time that
the password can be queried by the user; post\-creation queries may not contain
password information (depending upon the provider).
.SS The libcloudfuncs Functions
.sp
A number of other functions are required for all cloud providers. However, with
libcloud\-based modules, these are all provided for free by the libcloudfuncs
library. The following two lines set up the imports:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from salt.cloud.libcloudfuncs import * # pylint: disable=W0614,W0401
from salt.utils import namespaced_function
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And then a series of declarations will make the necessary functions available
within the cloud module.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
get_size = namespaced_function(get_size, globals())
get_image = namespaced_function(get_image, globals())
avail_locations = namespaced_function(avail_locations, globals())
avail_images = namespaced_function(avail_images, globals())
avail_sizes = namespaced_function(avail_sizes, globals())
script = namespaced_function(script, globals())
destroy = namespaced_function(destroy, globals())
list_nodes = namespaced_function(list_nodes, globals())
list_nodes_full = namespaced_function(list_nodes_full, globals())
list_nodes_select = namespaced_function(list_nodes_select, globals())
show_instance = namespaced_function(show_instance, globals())
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If necessary, these functions may be replaced by removing the appropriate
declaration line, and then adding the function as normal.
.sp
These functions are required for all cloud modules, and are described in detail
in the next section.
.SS Non\-Libcloud Based Modules
.sp
In some cases, using libcloud is not an option. This may be because libcloud has
not yet included the necessary driver itself, or it may be that the driver that
is included with libcloud does not contain all of the necessary features
required by the developer. When this is the case, some or all of the functions
in \fBlibcloudfuncs\fP may be replaced. If they are all replaced, the libcloud
imports should be absent from the Salt Cloud module.
.sp
A good example of a non\-libcloud provider is the DigitalOcean module:
.sp
\fI\%https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/digital_ocean.py\fP
.SS The \fBcreate()\fP Function
.sp
The \fBcreate()\fP function must be created as described in the libcloud\-based
module documentation.
.SS The get_size() Function
.sp
This function is only necessary for libcloud\-based modules, and does not need
to exist otherwise.
.SS The get_image() Function
.sp
This function is only necessary for libcloud\-based modules, and does not need
to exist otherwise.
.SS The avail_locations() Function
.sp
This function returns a list of locations available, if the cloud provider uses
multiple data centers. It is not necessary if the cloud provider only uses one
data center. It is normally called using the \fB\-\-list\-locations\fP option.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-locations my\-cloud\-provider
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The avail_images() Function
.sp
This function returns a list of images available for this cloud provider. There
are not currently any known cloud providers that do not provide this
functionality, though they may refer to images by a different name (for example,
"templates"). It is normally called using the \fB\-\-list\-images\fP option.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-images my\-cloud\-provider
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The avail_sizes() Function
.sp
This function returns a list of sizes available for this cloud provider.
Generally, this refers to a combination of RAM, CPU and/or disk space. This
functionality may not be present on some cloud providers. For example, the
Parallels module breaks down RAM, CPU and disk space into separate options,
whereas in other providers, these options are baked into the image. It is
normally called using the \fB\-\-list\-sizes\fP option.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-sizes my\-cloud\-provider
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The script() Function
.sp
This function builds the deploy script to be used on the remote machine. It is
likely to be moved into the \fBsalt.utils.cloud\fP library in the near future, as
it is very generic and can usually be copied wholesale from another module. An
excellent example is in the Azure driver.
.SS The destroy() Function
.sp
This function irreversibly destroys a virtual machine on the cloud provider.
Before doing so, it should fire an event on the Salt event bus. The tag for this
event is \fBsalt/cloud/<vm name>/destroying\fP\&. Once the virtual machine has been
destroyed, another event is fired. The tag for that event is
\fBsalt/cloud/<vm name>/destroyed\fP\&.
.sp
This function is normally called with the \fB\-d\fP options:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-d myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The list_nodes() Function
.sp
This function returns a list of nodes available on this cloud provider, using
the following fields:
.INDENT 0.0
.IP \(bu 2
id (str)
.IP \(bu 2
image (str)
.IP \(bu 2
size (str)
.IP \(bu 2
state (str)
.IP \(bu 2
private_ips (list)
.IP \(bu 2
public_ips (list)
.UNINDENT
.sp
No other fields should be returned in this function, and all of these fields
should be returned, even if empty. The private_ips and public_ips fields should
always be of a list type, even if empty, and the other fields should always be
of a str type. This function is normally called with the \fB\-Q\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-Q
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The list_nodes_full() Function
.sp
All information available about all nodes should be returned in this function.
The fields in the list_nodes() function should also be returned, even if they
would not normally be provided by the cloud provider. This is because some
functions both within Salt and 3rd party will break if an expected field is not
present. This function is normally called with the \fB\-F\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-F
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The list_nodes_select() Function
.sp
This function returns only the fields specified in the \fBquery.selection\fP
option in \fB/etc/salt/cloud\fP\&. Because this function is so generic, all of the
heavy lifting has been moved into the \fBsalt.utils.cloud\fP library.
.sp
A function to call \fBlist_nodes_select()\fP still needs to be present. In
general, the following code can be used as\-is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def list_nodes_select(call=None):
\(aq\(aq\(aq
Return a list of the VMs that are on the provider, with select fields
\(aq\(aq\(aq
return salt.utils.cloud.list_nodes_select(
list_nodes_full(\(aqfunction\(aq), __opts__[\(aqquery.selection\(aq], call,
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, depending on the cloud provider, additional variables may be required.
For instance, some modules use a \fBconn\fP object, or may need to pass other
options into \fBlist_nodes_full()\fP\&. In this case, be sure to update the function
appropriately:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def list_nodes_select(conn=None, call=None):
\(aq\(aq\(aq
Return a list of the VMs that are on the provider, with select fields
\(aq\(aq\(aq
if not conn:
conn = get_conn() # pylint: disable=E0602
return salt.utils.cloud.list_nodes_select(
list_nodes_full(conn, \(aqfunction\(aq),
__opts__[\(aqquery.selection\(aq],
call,
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function is normally called with the \fB\-S\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-S
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The show_instance() Function
.sp
This function is used to display all of the information about a single node
that is available from the cloud provider. The simplest way to provide this is
usually to call \fBlist_nodes_full()\fP, and return just the data for the
requested node. It is normally called as an action:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_instance myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Actions and Functions
.sp
Extra functionality may be added to a cloud provider in the form of an
\fB\-\-action\fP or a \fB\-\-function\fP\&. Actions are performed against a cloud
instance/virtual machine, and functions are performed against a cloud provider.
.SS Actions
.sp
Actions are calls that are performed against a specific instance or virtual
machine. The \fBshow_instance\fP action should be available in all cloud modules.
Actions are normally called with the \fB\-a\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_instance myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Actions must accept a \fBname\fP as a first argument, may optionally support any
number of kwargs as appropriate, and must accept an argument of \fBcall\fP, with
a default of \fBNone\fP\&.
.sp
Before performing any other work, an action should normally verify that it has
been called correctly. It may then perform the desired feature, and return
useful information to the user. A basic action looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def show_instance(name, call=None):
\(aq\(aq\(aq
Show the details from EC2 concerning an AMI
\(aq\(aq\(aq
if call != \(aqaction\(aq:
raise SaltCloudSystemExit(
\(aqThe show_instance action must be called with \-a or \-\-action.\(aq
)
return _get_node(name)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that generic kwargs, if used, are passed through to actions as
\fBkwargs\fP and not \fB**kwargs\fP\&. An example of this is seen in the Functions
section.
.SS Functions
.sp
Functions are called that are performed against a specific cloud provider. An
optional function that is often useful is \fBshow_image\fP, which describes an
image in detail. Functions are normally called with the \fB\-f\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_image my\-cloud\-provider image=\(aqUbuntu 13.10 64\-bit\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A function may accept any number of kwargs as appropriate, and must accept an
argument of \fBcall\fP with a default of \fBNone\fP\&.
.sp
Before performing any other work, a function should normally verify that it has
been called correctly. It may then perform the desired feature, and return
useful information to the user. A basic function looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def show_image(kwargs, call=None):
\(aq\(aq\(aq
Show the details from EC2 concerning an AMI
\(aq\(aq\(aq
if call != \(aqfunction\(aq:
raise SaltCloudSystemExit(
\(aqThe show_image action must be called with \-f or \-\-function.\(aq
)
params = {\(aqImageId.1\(aq: kwargs[\(aqimage\(aq],
\(aqAction\(aq: \(aqDescribeImages\(aq}
result = query(params)
log.info(result)
return result
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Take note that generic kwargs are passed through to functions as \fBkwargs\fP and
not \fB**kwargs\fP\&.
.SS OS Support for Cloud VMs
.sp
Salt Cloud works primarily by executing a script on the virtual machines as
soon as they become available. The script that is executed is referenced in the
cloud profile as the \fBscript\fP\&. In older versions, this was the \fBos\fP
argument. This was changed in 0.8.2.
.sp
A number of legacy scripts exist in the deploy directory in the saltcloud
source tree. The preferred method is currently to use the salt\-bootstrap
script. A stable version is included with each release tarball starting with
0.8.4. The most updated version can be found at:
.sp
\fI\%https://github.com/saltstack/salt\-bootstrap\fP
.sp
If you do not specify a script argument, this script will be used at the
default.
.sp
If the Salt Bootstrap script does not meet your needs, you may write your own.
The script should be written in bash and is a Jinja template. Deploy scripts
need to execute a number of functions to do a complete salt setup. These
functions include:
.INDENT 0.0
.IP 1. 3
Install the salt minion. If this can be done via system packages this method
is HIGHLY preferred.
.IP 2. 3
Add the salt minion keys before the minion is started for the first time.
The minion keys are available as strings that can be copied into place in
the Jinja template under the dict named "vm".
.IP 3. 3
Start the salt\-minion daemon and enable it at startup time.
.IP 4. 3
Set up the minion configuration file from the "minion" data available in
the Jinja template.
.UNINDENT
.sp
A good, well commented, example of this process is the Fedora deployment
script:
.sp
\fI\%https://github.com/saltstack/salt\-cloud/blob/master/saltcloud/deploy/Fedora.sh\fP
.sp
A number of legacy deploy scripts are included with the release tarball. None
of them are as functional or complete as Salt Bootstrap, and are still included
for academic purposes.
.SS Other Generic Deploy Scripts
.sp
If you want to be assured of always using the latest Salt Bootstrap script,
there are a few generic templates available in the deploy directory of your
saltcloud source tree:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl\-bootstrap
curl\-bootstrap\-git
python\-bootstrap
wget\-bootstrap
wget\-bootstrap\-git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These are example scripts which were designed to be customized, adapted, and
refit to meet your needs. One important use of them is to pass options to
the salt\-bootstrap script, such as updating to specific git tags.
.SS Post\-Deploy Commands
.sp
Once a minion has been deployed, it has the option to run a salt command.
Normally, this would be the state.highstate command, which would finish
provisioning the VM. Another common option is state.sls, or for just testing,
test.ping. This is configured in the main cloud config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
start_action: state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is currently considered to be experimental functionality, and may not work
well with all providers. If you experience problems with Salt Cloud hanging
after Salt is deployed, consider using Startup States instead:
.sp
\fI\%http://docs.saltstack.com/ref/states/startup.html\fP
.SS Skipping the Deploy Script
.sp
For whatever reason, you may want to skip the deploy script altogether. This
results in a VM being spun up much faster, with absolutely no configuration.
This can be set from the command line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-no\-deploy \-p micro_aws my_instance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or it can be set from the main cloud config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
deploy: False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or it can be set from the provider\(aqs configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
RACKSPACE.user: example_user
RACKSPACE.apikey: 123984bjjas87034
RACKSPACE.deploy: False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or even on the VM\(aqs profile settings:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ubuntu_aws:
provider: aws
image: ami\-7e2da54e
size: Micro Instance
deploy: False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The default for deploy is True.
.sp
In the profile, you may also set the script option to \fBNone\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
script: None
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is the slowest option, since it still uploads the None deploy script and
executes it.
.SS Updating Salt Bootstrap
.sp
Salt Bootstrap can be updated automatically with salt\-cloud:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-u
salt\-cloud \-\-update\-bootstrap
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Bear in mind that this updates to the latest (unstable) version, so use with
caution.
.SS Keeping /tmp/ Files
.sp
When Salt Cloud deploys an instance, it uploads temporary files to /tmp/ for
salt\-bootstrap to put in place. After the script has run, they are deleted. To
keep these files around (mostly for debugging purposes), the \-\-keep\-tmp option
can be added:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p myprofile mymachine \-\-keep\-tmp
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For those wondering why /tmp/ was used instead of /root/, this had to be done
for images which require the use of sudo, and therefore do not allow remote
root logins, even for file transfers (which makes /root/ unavailable).
.SS Deploy Script Arguments
.sp
Custom deploy scripts are unlikely to need custom arguments to be passed to
them, but salt\-bootstrap has been extended quite a bit, and this may be
necessary. script_args can be specified in either the profile or the map file,
to pass arguments to the deploy script:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
aws\-amazon:
provider: aws
image: ami\-1624987f
size: Micro Instance
ssh_username: ec2\-user
script: bootstrap\-salt
script_args: \-c /tmp/
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This has also been tested to work with pipes, if needed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
script_args: | head
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Using Salt Cloud from Salt
.SS Using the Salt Modules for Cloud
.sp
In addition to the \fBsalt\-cloud\fP command, Salt Cloud can be called from Salt,
in a variety of different ways. Most users will be interested in either the
execution module or the state module, but it is also possible to call Salt Cloud
as a runner.
.sp
Because the actual work will be performed on a remote minion, the normal Salt
Cloud configuration must exist on any target minion that needs to execute a Salt
Cloud command. Because Salt Cloud now supports breaking out configuration into
individual files, the configuration is easily managed using Salt\(aqs own
\fBfile.managed\fP state function. For example, the following directories allow
this configuration to be managed easily:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/cloud.providers.d/
/etc/salt/cloud.profiles.d/
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Minion Keys
.sp
Keep in mind that when creating minions, Salt Cloud will create public and
private minion keys, upload them to the minion, and place the public key on the
machine that created the minion. It will \fInot\fP attempt to place any public
minion keys on the master, unless the minion which was used to create the
instance is also the Salt Master. This is because granting arbitrary minions
access to modify keys on the master is a serious security risk, and must be
avoided.
.SS Execution Module
.sp
The \fBcloud\fP module is available to use from the command line. At the moment,
almost every standard Salt Cloud feature is available to use. The following
commands are available:
.SS list_images
.sp
This command is designed to show images that are available to be used to create
an instance using Salt Cloud. In general they are used in the creation of
profiles, but may also be used to create an instance directly (see below).
Listing images requires a provider to be configured, and specified:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.list_images my\-cloud\-provider
.ft P
.fi
.UNINDENT
.UNINDENT
.SS list_sizes
.sp
This command is designed to show sizes that are available to be used to create
an instance using Salt Cloud. In general they are used in the creation of
profiles, but may also be used to create an instance directly (see below). This
command is not available for all cloud providers; see the provider\-specific
documentation for details. Listing sizes requires a provider to be configured,
and specified:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.list_sizes my\-cloud\-provider
.ft P
.fi
.UNINDENT
.UNINDENT
.SS list_locations
.sp
This command is designed to show locations that are available to be used to
create an instance using Salt Cloud. In general they are used in the creation of
profiles, but may also be used to create an instance directly (see below). This
command is not available for all cloud providers; see the provider\-specific
documentation for details. Listing locations requires a provider to be
configured, and specified:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.list_locations my\-cloud\-provider
.ft P
.fi
.UNINDENT
.UNINDENT
.SS query
.sp
This command is used to query all configured cloud providers, and display all
instances associated with those accounts. By default, it will run a standard
query, returning the following fields:
.INDENT 0.0
.TP
.B \fBid\fP
The name or ID of the instance, as used by the cloud provider.
.TP
.B \fBimage\fP
The disk image that was used to create this instance.
.TP
.B \fBprivate_ips\fP
Any public IP addresses currently assigned to this instance.
.TP
.B \fBpublic_ips\fP
Any private IP addresses currently assigned to this instance.
.TP
.B \fBsize\fP
The size of the instance; can refer to RAM, CPU(s), disk space, etc.,
depending on the cloud provider.
.TP
.B \fBstate\fP
The running state of the instance; for example, \fBrunning\fP, \fBstopped\fP,
\fBpending\fP, etc. This state is dependent upon the provider.
.UNINDENT
.sp
This command may also be used to perform a full query or a select query, as
described below. The following usages are available:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.query
salt myminion cloud.query list_nodes
salt myminion cloud.query list_nodes_full
.ft P
.fi
.UNINDENT
.UNINDENT
.SS full_query
.sp
This command behaves like the \fBquery\fP command, but lists all information
concerning each instance as provided by the cloud provider, in addition to the
fields returned by the \fBquery\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.full_query
.ft P
.fi
.UNINDENT
.UNINDENT
.SS select_query
.sp
This command behaves like the \fBquery\fP command, but only returned select
fields as defined in the \fB/etc/salt/cloud\fP configuration file. A sample
configuration for this section of the file might look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
query.selection:
\- id
\- key_name
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This configuration would only return the \fBid\fP and \fBkey_name\fP fields, for
those cloud providers that support those two fields. This would be called using
the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.select_query
.ft P
.fi
.UNINDENT
.UNINDENT
.SS profile
.sp
This command is used to create an instance using a profile that is configured
on the target minion. Please note that the profile must be configured before
this command can be used with it.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.profile ec2\-centos64\-x64 my\-new\-instance
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that the execution module does \fInot\fP run in parallel mode. Using
multiple minions to create instances can effectively perform parallel instance
creation.
.SS create
.sp
This command is similar to the \fBprofile\fP command, in that it is used to create
a new instance. However, it does not require a profile to be pre\-configured.
Instead, all of the options that are normally configured in a profile are passed
directly to Salt Cloud to create the instance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.create my\-ec2\-config my\-new\-instance \e
image=ami\-1624987f size=\(aqMicro Instance\(aq ssh_username=ec2\-user \e
securitygroup=default delvol_on_destroy=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that the execution module does \fInot\fP run in parallel mode. Using
multiple minions to create instances can effectively perform parallel instance
creation.
.SS destroy
.sp
This command is used to destroy an instance or instances. This command will
search all configured providers and remove any instance(s) which matches the
name(s) passed in here. The results of this command are \fInon\-reversable\fP and
should be used with caution.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.destroy myinstance
salt myminion cloud.destroy myinstance1,myinstance2
.ft P
.fi
.UNINDENT
.UNINDENT
.SS action
.sp
This command implements both the \fBaction\fP and the \fBfunction\fP commands
used in the standard \fBsalt\-cloud\fP command. If one of the standard \fBaction\fP
commands is used, an instance name must be provided. If one of the standard
\fBfunction\fP commands is used, a provider configuration must be named.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion cloud.action start instance=myinstance
salt myminion cloud.action show_image provider=my\-ec2\-config \e
image=ami\-1624987f
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The actions available are largely dependent upon the module for the specific
cloud provider. The following actions are available for all cloud providers:
.INDENT 0.0
.TP
.B \fBlist_nodes\fP
This is a direct call to the \fBquery\fP function as described above, but is
only performed against a single cloud provider. A provider configuration
must be included.
.TP
.B \fBlist_nodes_select\fP
This is a direct call to the \fBfull_query\fP function as described above, but
is only performed against a single cloud provider. A provider configuration
must be included.
.TP
.B \fBlist_nodes_select\fP
This is a direct call to the \fBselect_query\fP function as described above,
but is only performed against a single cloud provider. A provider
configuration must be included.
.TP
.B \fBshow_instance\fP
This is a thin wrapper around \fBlist_nodes\fP, which returns the full
information about a single instance. An instance name must be provided.
.UNINDENT
.SS State Module
.sp
A subset of the execution module is available through the \fBcloud\fP state
module. Not all functions are currently included, because there is currently
insufficient code for them to perform statefully. For example, a command to
create an instance may be issued with a series of options, but those options
cannot currently be statefully managed. Additional states to manage these
options will be released at a later time.
.SS cloud.present
.sp
This state will ensure that an instance is present inside a particular cloud
provider. Any option that is normally specified in the \fBcloud.create\fP
execution module and function may be declared here, but only the actual
presence of the instance will be managed statefully.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-instance\-name:
cloud.present:
\- provider: my\-ec2\-config
\- image: ami\-1624987f
\- size: \(aqMicro Instance\(aq
\- ssh_username: ec2\-user
\- securitygroup: default
\- delvol_on_destroy: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS cloud.profile
.sp
This state will ensure that an instance is present inside a particular cloud
provider. This function calls the \fBcloud.profile\fP execution module and
function, but as with \fBcloud.present\fP, only the actual presence of the
instance will be managed statefully.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-instance\-name:
cloud.profile:
\- profile: ec2\-centos64\-x64
.ft P
.fi
.UNINDENT
.UNINDENT
.SS cloud.absent
.sp
This state will ensure that an instance (identified by name) does not exist in
any of the cloud providers configured on the target minion. Please note that
this state is \fInon\-reversable\fP and may be considered especially destructive when
issued as a cloud state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-instance\-name:
cloud.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Runner Module
.sp
The \fBcloud\fP runner module is executed on the master, and performs actions
using the configuration and Salt modules on the master itself. This means that
any public minion keys will also be properly accepted by the master.
.sp
Using the functions in the runner module is no different than using those in
the execution module, outside of the behavior described in the above paragraph.
The following functions are available inside the runner:
.INDENT 0.0
.IP \(bu 2
list_images
.IP \(bu 2
list_sizes
.IP \(bu 2
list_locations
.IP \(bu 2
query
.IP \(bu 2
full_query
.IP \(bu 2
select_query
.IP \(bu 2
profile
.IP \(bu 2
destroy
.IP \(bu 2
action
.UNINDENT
.sp
Outside of the standard usage of \fBsalt\-run\fP itself, commands are executed as
usual:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cloud.profile ec2\-centos64\-x86_64 my\-instance\-name
.ft P
.fi
.UNINDENT
.UNINDENT
.SS CloudClient
.sp
The execution, state and runner modules ultimately all use the CloudClient
library that ships with Salt. To use the CloudClient library locally (either on
the master or a minion), create a client object and issue a command against it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.cloud
import pprint
client = salt.cloud.CloudClient(\(aq/etc/salt/cloud\(aq)
nodes = client.query()
pprint.pprint(nodes)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Feature Comparison
.SS Feature Matrix
.sp
A number of features are available in most cloud providers, but not all are
available everywhere. This may be because the feature isn\(aqt supported by the
cloud provider itself, or it may only be that the feature has not yet been
added to Salt Cloud. In a handful of cases, it is because the feature does not
make sense for a particular cloud provider (Saltify, for instance).
.sp
This matrix shows which features are available in which cloud providers, as far
as Salt Cloud is concerned. This is not a comprehensive list of all features
available in all cloud providers, and should not be used to make business
decisions concerning choosing a cloud provider. In most cases, adding support
for a feature to Salt Cloud requires only a little effort.
.SS Legacy Drivers
.sp
Both AWS and Rackspace are listed as "Legacy". This is because those drivers
have been replaced by other drivers, which are generally the preferred method
for working with those providers.
.sp
The EC2 driver should be used instead of the AWS driver, when possible. The
OpenStack driver should be used instead of the Rackspace driver, unless the user
is dealing with instances in "the old cloud" in Rackspace.
.SS Note for Developers
.sp
When adding new features to a particular cloud provider, please make sure to
add the feature to this table. Additionally, if you notice a feature that is not
properly listed here, pull requests to fix them is appreciated.
.SS Standard Features
.sp
These are features that are available for almost every provider.
.TS
center;
|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|.
_
T{
T} T{
AWS
(Legacy)
T} T{
CloudStack
T} T{
Digital
Ocean
T} T{
EC2
T} T{
GoGrid
T} T{
JoyEnt
T} T{
Linode
T} T{
OpenStack
T} T{
Parallels
T} T{
Rackspace
(Legacy)
T} T{
Saltify
T} T{
Softlayer
T} T{
Softlayer
Hardware
T} T{
Aliyun
T}
_
T{
Query
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
Full Query
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
Selective Query
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
List Sizes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
List Images
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
List Locations
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
create
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
destroy
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
Yes
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
.TE
.SS Actions
.sp
These are features that are performed on a specific instance, and require an
instance name to be passed in. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-a attach_volume ami.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.TS
center;
|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|.
_
T{
Actions
T} T{
AWS
(Legacy)
T} T{
CloudStack
T} T{
Digital
Ocean
T} T{
EC2
T} T{
GoGrid
T} T{
JoyEnt
T} T{
Linode
T} T{
OpenStack
T} T{
Parallels
T} T{
Rackspace
(Legacy)
T} T{
Saltify
T} T{
Softlayer
T} T{
Softlayer
Hardware
T} T{
Aliyun
T}
_
T{
attach_volume
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
create_attach_volumes
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
del_tags
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
delvol_on_destroy
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
detach_volume
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
disable_term_protect
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
enable_term_protect
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_tags
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
keepvol_on_destroy
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
list_keypairs
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
rename
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
set_tags
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
show_delvol_on_destroy
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
show_instance
T} T{
T} T{
T} T{
Yes
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
Yes
T} T{
Yes
T}
_
T{
show_term_protect
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
start
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
stop
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
take_action
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
.TE
.SS Functions
.sp
These are features that are performed against a specific cloud provider, and
require the name of the provider to be passed in. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-cloud \-f list_images my_digitalocean
.ft P
.fi
.UNINDENT
.UNINDENT
.TS
center;
|l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|.
_
T{
Functions
T} T{
AWS
(Legacy)
T} T{
CloudStack
T} T{
Digital
Ocean
T} T{
EC2
T} T{
GoGrid
T} T{
JoyEnt
T} T{
Linode
T} T{
OpenStack
T} T{
Parallels
T} T{
Rackspace
(Legacy)
T} T{
Saltify
T} T{
Softlayer
T} T{
Softlayer
Hardware
T} T{
Aliyun
T}
_
T{
block_device_mappings
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
create_keypair
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
create_volume
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
delete_key
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
delete_keypair
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
delete_volume
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_image
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
get_ip
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_key
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_keyid
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_keypair
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_networkid
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_node
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_password
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_size
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
get_spot_config
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
get_subnetid
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
iam_profile
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
import_key
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
key_list
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
keyname
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
list_availability_zones
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
list_custom_images
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T}
_
T{
list_keys
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
list_vlans
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
Yes
T} T{
T}
_
T{
rackconnect
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
reboot
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
reformat_node
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
securitygroup
T} T{
Yes
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
securitygroupid
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
show_image
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
T{
show_key
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
show_keypair
T} T{
T} T{
T} T{
Yes
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T}
_
T{
show_volume
T} T{
T} T{
T} T{
T} T{
Yes
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
T} T{
Yes
T}
_
.TE
.SH NETAPI MODULES
.SS Writing netapi modules
.sp
\fBnetapi\fP modules, put simply, bind a port and start a service.
They are purposefully open\-ended and can be used to present a variety of
external interfaces to Salt, and even present multiple interfaces at once.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIThe full list of netapi modules\fP
.UNINDENT
.UNINDENT
.SS Configuration
.sp
All \fBnetapi\fP configuration is done in the \fISalt master
config\fP and takes a form similar to the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rest_cherrypy:
port: 8000
debug: True
ssl_crt: /etc/pki/tls/certs/localhost.crt
ssl_key: /etc/pki/tls/certs/localhost.key
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The \fB__virtual__\fP function
.sp
Like all module types in Salt, \fBnetapi\fP modules go through
Salt\(aqs loader interface to determine if they should be loaded into memory and
then executed.
.sp
The \fB__virtual__\fP function in the module makes this determination and should
return \fBFalse\fP or a string that will serve as the name of the module. If the
module raises an \fBImportError\fP or any other errors, it will not be loaded.
.SS The \fBstart\fP function
.sp
The \fBstart()\fP function will be called for each \fBnetapi\fP
module that is loaded. This function should contain the server loop that
actually starts the service. This is started in a multiprocess.
.SS Inline documentation
.sp
As with the rest of Salt, it is a best\-practice to include liberal inline
documentation in the form of a module docstring and docstrings on any classes,
methods, and functions in your \fBnetapi\fP module.
.SS Loader “magic” methods
.sp
The loader makes the \fB__opts__\fP data structure available to any function in
a \fBnetapi\fP module.
.SS Introduction to netapi modules
.sp
netapi modules provide API\-centric access to Salt. Usually externally\-facing
services such as REST or WebSockets, XMPP, XMLRPC, etc.
.sp
In general netapi modules bind to a port and start a service. They are
purposefully open\-ended. A single module can be configured to run as well as
multiple modules simultaneously.
.sp
netapi modules are enabled by adding configuration to your Salt Master config
file and then starting the \fBsalt\-api\fP daemon. Check the docs for each
module to see external requirements and configuration settings.
.sp
Communication with Salt and Salt satellite projects is done using Salt\(aqs own
\fIPython API\fP\&. A list of available client interfaces is below.
.INDENT 0.0
.INDENT 3.5
.IP "salt\-api"
.sp
Prior to Salt\(aqs 2014.7.0 release, netapi modules lived in the separate sister
projected \fBsalt\-api\fP\&. That project has been merged into the main Salt
project.
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIThe full list of netapi modules\fP
.UNINDENT
.UNINDENT
.SS Client interfaces
.sp
Salt\(aqs client interfaces expose executing functions by crafting a dictionary of
values that are mapped to function arguments. This allows calling functions
simply by creating a data structure. (And this is exactly how much of Salt\(aqs
own internals work!)
.INDENT 0.0
.TP
.B class salt.netapi.NetapiClient(opts)
Provide a uniform method of accessing the various client interfaces in Salt
in the form of low\-data data structures. For example:
.sp
.nf
.ft C
>>> client = NetapiClient(__opts__)
>>> lowstate = {\(aqclient\(aq: \(aqlocal\(aq, \(aqtgt\(aq: \(aq*\(aq, \(aqfun\(aq: \(aqtest.ping\(aq, \(aqarg\(aq: \(aq\(aq}
>>> client.run(lowstate)
.ft P
.fi
.INDENT 7.0
.TP
.B local(*args, **kwargs)
Run \fIexecution modules\fP synchronously
.sp
See \fBsalt.client.LocalClient.cmd()\fP for all available
parameters.
.sp
Sends a command from the master to the targeted minions. This is the
same interface that Salt\(aqs own CLI uses. Note the \fBarg\fP and \fBkwarg\fP
parameters are sent down to the minion(s) and the given function,
\fBfun\fP, is called with those parameters.
.INDENT 7.0
.TP
.B Returns
Returns the result from the execution module
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B local_async(*args, **kwargs)
Run \fIexecution modules\fP asynchronously
.sp
Wraps \fBsalt.client.LocalClient.run_job()\fP\&.
.INDENT 7.0
.TP
.B Returns
job ID
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B local_batch(*args, **kwargs)
Run \fIexecution modules\fP against batches of minions
.sp
New in version 0.8.4.
.sp
Wraps \fBsalt.client.LocalClient.cmd_batch()\fP
.INDENT 7.0
.TP
.B Returns
Returns the result from the exeuction module for each batch of
returns
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B runner(fun, timeout=None, **kwargs)
Run \fIrunner modules <all\-salt.runners>\fP synchronously
.sp
Wraps \fBsalt.runner.RunnerClient.cmd_sync()\fP\&.
.sp
Note that runner functions must be called using keyword arguments.
Positional arguments are not supported.
.INDENT 7.0
.TP
.B Returns
Returns the result from the runner module
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B wheel(fun, **kwargs)
Run \fIwheel modules\fP synchronously
.sp
Wraps \fBsalt.wheel.WheelClient.master_call()\fP\&.
.sp
Note that wheel functions must be called using keyword arguments.
Positional arguments are not supported.
.INDENT 7.0
.TP
.B Returns
Returns the result from the wheel module
.UNINDENT
.UNINDENT
.UNINDENT
.SH SALT VIRT
.sp
The Salt Virt cloud controller capability was initial added to Salt in version
0.14.0 as an alpha technology.
.sp
The initial Salt Virt system supports core cloud operations:
.INDENT 0.0
.IP \(bu 2
Virtual machine deployment
.IP \(bu 2
Inspection of deployed VMs
.IP \(bu 2
Virtual machine migration
.IP \(bu 2
Network profiling
.IP \(bu 2
Automatic VM integration with all aspects of Salt
.IP \(bu 2
Image Pre\-seeding
.UNINDENT
.sp
Many features are currently under development to enhance the capabilities of
the Salt Virt systems.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
It is noteworthy that Salt was originally developed with the intent of
using the Salt communication system as the backbone to a cloud controller.
This means that the Salt Virt system is not an afterthought, simply a
system that took the back seat to other development. The original attempt
to develop the cloud control aspects of Salt was a project called butter.
This project never took off, but was functional and proves the early
viability of Salt to be a cloud controller.
.UNINDENT
.UNINDENT
.SS Salt Virt Tutorial
.sp
A tutorial about how to get Salt Virt up and running has been added to the
tutorial section:
.sp
\fBCloud Controller Tutorial\fP
.SS The Salt Virt Runner
.sp
The point of interaction with the cloud controller is the \fBvirt\fP
runner. The \fBvirt\fP runner comes with routines to execute specific
virtual machine routines.
.sp
Reference documentation for the virt runner is available with the runner
module documentation:
.sp
\fBVirt Runner Reference\fP
.SS Based on Live State Data
.sp
The Salt Virt system is based on using Salt to query live data about
hypervisors and then using the data gathered to make decisions about cloud
operations. This means that no external resources are required to run Salt
Virt, and that the information gathered about the cloud is live and accurate.
.SS Deploy from Network or Disk
.SS Virtual Machine Disk Profiles
.sp
Salt Virt allows for the disks created for deployed virtual machines
to be finely configured. The configuration is a simple data structure which is
read from the \fBconfig.option\fP function, meaning that the configuration can be
stored in the minion config file, the master config file, or the minion\(aqs
pillar.
.sp
This configuration option is called \fBvirt.disk\fP\&. The default \fBvirt.disk\fP
data structure looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virt.disk:
default:
\- system:
size: 8192
format: qcow2
model: virtio
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The format and model does not need to be defined, Salt will
default to the optimal format used by the underlying hypervisor,
in the case of kvm this it is \fBqcow2\fP and
\fBvirtio\fP\&.
.UNINDENT
.UNINDENT
.sp
This configuration sets up a disk profile called default. The default
profile creates a single system disk on the virtual machine.
.SS Define More Profiles
.sp
Many environments will require more complex disk profiles and may require
more than one profile, this can be easily accomplished:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virt.disk:
default:
\- system:
size: 8192
database:
\- system:
size: 8192
\- data:
size: 30720
web:
\- system:
size: 1024
\- logs:
size: 5120
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This configuration allows for one of three profiles to be selected,
allowing virtual machines to be created with different storage needs
of the deployed vm.
.SS Virtual Machine Network Profiles
.sp
Salt Virt allows for the network devices created for deployed virtual machines
to be finely configured. The configuration is a simple data structure which is
read from the \fBconfig.option\fP function, meaning that the configuration can be
stored in the minion config file, the master config file, or the minion\(aqs
pillar.
.sp
This configuration option is called \fBvirt.nic\fP\&. By default the \fBvirt.nic\fP
option is empty but defaults to a data structure which looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virt.nic:
default:
eth0:
bridge: br0
model: virtio
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The model does not need to be defined, Salt will default to the optimal
model used by the underlying hypervisor, in the case of kvm this model
is \fBvirtio\fP
.UNINDENT
.UNINDENT
.sp
This configuration sets up a network profile called default. The default
profile creates a single Ethernet device on the virtual machine that is bridged
to the hypervisor\(aqs \fBbr0\fP interface. This default setup does not
require setting up the \fBvirt.nic\fP configuration, and is the reason why a
default install only requires setting up the \fBbr0\fP bridge device on the
hypervisor.
.SS Define More Profiles
.sp
Many environments will require more complex network profiles and may require
more than one profile, this can be easily accomplished:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virt.nic:
dual:
eth0:
bridge: service_br
eth1:
bridge: storage_br
single:
eth0:
bridge: service_br
triple:
eth0:
bridge: service_br
eth1:
bridge: storage_br
eth2:
bridge: dmz_br
all:
eth0:
bridge: service_br
eth1:
bridge: storage_br
eth2:
bridge: dmz_br
eth3:
bridge: database_br
dmz:
eth0:
bridge: service_br
eth1:
bridge: dmz_br
database:
eth0:
bridge: service_br
eth1:
bridge: database_br
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This configuration allows for one of six profiles to be selected, allowing
virtual machines to be created which attach to different network depending
on the needs of the deployed vm.
.SH UNDERSTANDING YAML
.sp
The default renderer for SLS files is the YAML renderer. YAML is a
markup language with many powerful features. However, Salt uses
a small subset of YAML that maps over very commonly used data structures,
like lists and dictionaries. It is the job of the YAML renderer to take
the YAML data structure and compile it into a Python data structure for
use by Salt.
.sp
Though YAML syntax may seem daunting and terse at first, there are only
three very simple rules to remember when writing YAML for SLS files.
.SS Rule One: Indentation
.sp
YAML uses a fixed indentation scheme to represent relationships between
data layers. Salt requires that the indentation for each level consists
of exactly two spaces. Do not use tabs.
.SS Rule Two: Colons
.sp
Python dictionaries are, of course, simply key\-value pairs. Users from other
languages may recognize this data type as hashes or associative arrays.
.sp
Dictionary keys are represented in YAML as strings terminated by a trailing
colon. Values are represented by either a string following the colon,
separated by a space:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_key: my_value
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In Python, the above maps to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqmy_key\(aq: \(aqmy_value\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, a value can be associated with a key through indentation.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_key:
my_value
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The above syntax is valid YAML but is uncommon in SLS files because most often,
the value for a key is not singular but instead is a \fIlist\fP of values.
.UNINDENT
.UNINDENT
.sp
In Python, the above maps to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqmy_key\(aq: \(aqmy_value\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Dictionaries can be nested:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
first_level_dict_key:
second_level_dict_key: value_in_second_level_dict
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And in Python:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
\(aqfirst_level_dict_key\(aq: {
\(aqsecond_level_dict_key\(aq: \(aqvalue_in_second_level_dict\(aq
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Rule Three: Dashes
.sp
To represent lists of items, a single dash followed by a space is used. Multiple
items are a part of the same list as a function of their having the same level of indentation.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- list_value_one
\- list_value_two
\- list_value_three
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lists can be the value of a key\-value pair. This is quite common in Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_dictionary:
\- list_value_one
\- list_value_two
\- list_value_three
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In Python, the above maps to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqmy_dictionary\(aq: [\(aqlist_value_one\(aq, \(aqlist_value_two\(aq, \(aqlist_value_three\(aq]}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Learning More
.sp
One easy way to learn more about how YAML gets rendered into Python data structures is
to use an online YAML parser to see the Python output.
.sp
One excellent choice for experimenting with YAML parsing is: \fI\%http://yaml\-online\-parser.appspot.com/\fP
.SH MASTER TOPS SYSTEM
.sp
In 0.10.4 the \fIexternal_nodes\fP system was upgraded to allow for modular
subsystems to be used to generate the top file data for a highstate run on
the master.
.sp
The old \fIexternal_nodes\fP option has been removed.
The master tops system contains a number of subsystems that
are loaded via the Salt loader interfaces like modules, states, returners,
runners, etc.
.sp
Using the new \fImaster_tops\fP option is simple:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
ext_nodes: cobbler\-external\-nodes
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
for \fBCobbler\fP or:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
reclass:
inventory_base_uri: /etc/reclass
classes_uri: roles
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
for \fBReclass\fP\&.
.sp
It\(aqs also possible to create custom master_tops modules. These modules must go
in a subdirectory called \fItops\fP in the \fIextension_modules\fP directory.
The \fIextension_modules\fP directory is not defined by default (the
default \fI/srv/salt/_modules\fP will NOT work as of this release)
.sp
Custom tops modules are written like any other execution module, see the source
for the two modules above for examples of fully functional ones. Below is
a degenerate example:
.sp
/etc/salt/master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extension_modules: /srv/salt/modules
master_tops:
customtop: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
/srv/salt/modules/tops/customtop.py:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import logging
import sys
# Define the module\(aqs virtual name
__virtualname__ = \(aqcustomtop\(aq
log = logging.getLogger(__name__)
def __virtual__():
return __virtualname__
def top(**kwargs):
log.debug(\(aqCalling top in customtop\(aq)
return {\(aqbase\(aq: [\(aqtest\(aq]}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fIsalt minion state.show_top\fP should then display something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt minion state.show_top
minion
\-\-\-\-\-\-\-\-\-\-
base:
\- test
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SALT SSH
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Salt ssh is considered production ready in version 2014.7.0
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
On many systems, \fBsalt\-ssh\fP will be in its own package, usually named
\fBsalt\-ssh\fP\&.
.UNINDENT
.UNINDENT
.sp
In version 0.17.0 of Salt a new transport system was introduced, the ability
to use SSH for Salt communication. This addition allows for Salt routines to
be executed on remote systems entirely through ssh, bypassing the need for
a Salt Minion to be running on the remote systems and the need for a Salt
Master.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The Salt SSH system does not supercede the standard Salt communication
systems, it simply offers an SSH based alternative that does not require
ZeroMQ and a remote agent. Be aware that since all communication with Salt SSH is
executed via SSH it is substantially slower than standard Salt with ZeroMQ.
.UNINDENT
.UNINDENT
.sp
Salt SSH is very easy to use, simply set up a basic \fIroster\fP file of the
systems to connect to and run \fBsalt\-ssh\fP commands in a similar way as
standard \fBsalt\fP commands.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The Salt SSH eventually is supposed to support the same set of commands and
functionality as standard \fBsalt\fP command.
.sp
At the moment fileserver operations must be wrapped to ensure that the
relevant files are delivered with the \fBsalt\-ssh\fP commands.
The state module is an exception, which compiles the state run on the
master, and in the process finds all the references to \fBsalt://\fP paths and
copies those files down in the same tarball as the state run.
However, needed fileserver wrappers are still under development.
.UNINDENT
.UNINDENT
.SS Salt SSH Roster
.sp
The roster system in Salt allows for remote minions to be easily defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
See the \fBRoster documentation\fP for more details.
.UNINDENT
.UNINDENT
.sp
Simply create the roster file, the default location is \fI/etc/salt/roster\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
web1: 192.168.42.1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is a very basic roster file where a Salt ID is being assigned to an IP
address. A more elaborate roster can be created:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
web1:
host: 192.168.42.1 # The IP addr or DNS hostname
user: fred # Remote executions will be executed as user fred
passwd: foobarbaz # The password to use for login, if omitted, keys are used
sudo: True # Whether to sudo to root, not enabled by default
web2:
host: 192.168.42.2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
sudo works only if NOPASSWD is set for user in /etc/sudoers:
\fBfred ALL=(ALL) NOPASSWD: ALL\fP
.UNINDENT
.UNINDENT
.SS Calling Salt SSH
.sp
The \fBsalt\-ssh\fP command can be easily executed in the same way as a salt
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-ssh \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Commands with \fBsalt\-ssh\fP follow the same syntax as the \fBsalt\fP command.
.sp
The standard salt functions are available! The output is the same as \fBsalt\fP
and many of the same flags are available. Please see
\fI\%http://docs.saltstack.com/ref/cli/salt\-ssh.html\fP for all of the available
options.
.SS Raw Shell Calls
.sp
By default \fBsalt\-ssh\fP runs Salt execution modules on the remote system,
but \fBsalt\-ssh\fP can also execute raw shell commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-ssh \(aq*\(aq \-r \(aqifconfig\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS States Via Salt SSH
.sp
The Salt State system can also be used with \fBsalt\-ssh\fP\&. The state system
abstracts the same interface to the user in \fBsalt\-ssh\fP as it does when using
standard \fBsalt\fP\&. The intent is that Salt Formulas defined for standard
\fBsalt\fP will work seamlessly with \fBsalt\-ssh\fP and vice\-versa.
.sp
The standard Salt States walkthroughs function by simply replacing \fBsalt\fP
commands with \fBsalt\-ssh\fP\&.
.SS Targeting with Salt SSH
.sp
Due to the fact that the targeting approach differs in salt\-ssh, only glob
and regex targets are supported as of this writing, the remaining target
systems still need to be implemented.
.SS Configuring Salt SSH
.sp
Salt SSH takes its configuration from a master configuration file. Normally, this
file is in \fB/etc/salt/master\fP\&. If one wishes to use a customized configuration file,
the \fB\-c\fP option to Salt SSH facilitates passing in a directory to look inside for a
configuration file named \fBmaster\fP\&.
.SS Running Salt SSH as non\-root user
.sp
By default, Salt read all the configuration from /etc/salt/. If you are running
Salt SSH with a regular user you have to modify some paths or you will get
"Permission denied" messages. You have to modify two parameters: \fBpki_dir\fP
and \fBcachedir\fP\&. Those should point to a full path writable for the user.
.sp
It\(aqs recommed not to modify /etc/salt for this purpose. Create a private copy
of /etc/salt for the user and run the command with \fB\-c /new/config/path\fP\&.
.SS Define CLI Options with Saltfile
.sp
If you are commonly passing in CLI options to \fBsalt\-ssh\fP, you can create
a \fBSaltfile\fP to automatically use these options. This is common if you\(aqre
managing several different salt projects on the same server.
.sp
So if you \fBcd\fP into a directory with a \fBSaltfile\fP with the following
YAML contents:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-ssh:
config_dir: path/to/config/dir
max_prox: 30
wipe_ssh: true
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instead of having to call
\fBsalt\-ssh \-\-config\-dir=path/to/config/dir \-\-max\-procs=30 \-\-wipe \e* test.ping\fP you
can call \fBsalt\-ssh \e* test.ping\fP\&.
.sp
Boolean\-style options should be specified in their YAML representation.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The option keys specified must match the destination attributes for the
options specified in the parser
\fBsalt.utils.parsers.SaltSSHOptionParser\fP\&. For example, in the
case of the \fB\-\-wipe\fP command line option, its \fBdest\fP is configured to
be \fBwipe_ssh\fP and thus this is what should be configured in the
\fBSaltfile\fP\&. Using the names of flags for this option, being \fBwipe:
true\fP or \fBw: true\fP, will not work.
.UNINDENT
.UNINDENT
.SH SALT ROSTERS
.sp
Salt rosters are pluggable systems added in Salt 0.17.0 to facilitate the
\fBsalt\-ssh\fP system.
The roster system was created because \fBsalt\-ssh\fP needs a means to
identify which systems need to be targeted for execution.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIall\-salt.roster\fP
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The Roster System is not needed or used in standard Salt because the
master does not need to be initially aware of target systems, since the
Salt Minion checks itself into the master.
.UNINDENT
.UNINDENT
.sp
Since the roster system is pluggable, it can be easily augmented to attach to
any existing systems to gather information about what servers are presently
available and should be attached to by \fBsalt\-ssh\fP\&. By default the roster
file is located at /etc/salt/roster.
.SS How Rosters Work
.sp
The roster system compiles a data structure internally referred to as
\fItargets\fP\&. The \fItargets\fP is a list of target systems and attributes about how
to connect to said systems. The only requirement for a roster module in Salt
is to return the \fItargets\fP data structure.
.SS Targets Data
.sp
The information which can be stored in a roster \fItarget\fP is the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<Salt ID>: # The id to reference the target system with
host: # The IP address or DNS name of the remote host
user: # The user to log in as
passwd: # The password to log in with
# Optional parameters
port: # The target system\(aqs ssh port number
sudo: # Boolean to run command via sudo
priv: # File path to ssh private key, defaults to salt\-ssh.rsa
timeout: # Number of seconds to wait for response
.ft P
.fi
.UNINDENT
.UNINDENT
.SH REFERENCE
.SS Full list of builtin auth modules
.TS
center;
|l|l|.
_
T{
\fBauto\fP
T} T{
An "Always Approved" eauth interface to test against, not intended for
T}
_
T{
\fBkeystone\fP
T} T{
Provide authentication using OpenStack Keystone
T}
_
T{
\fBldap\fP
T} T{
Provide authentication using simple LDAP binds
T}
_
T{
\fBpam\fP
T} T{
Authenticate against PAM
T}
_
T{
\fBpki\fP
T} T{
Authenticate via a PKI certificate.
T}
_
T{
\fBstormpath_mod\fP
T} T{
Salt Stormpath Authentication
T}
_
.TE
.SS salt.auth.auto
.sp
An "Always Approved" eauth interface to test against, not intended for
production use
.INDENT 0.0
.TP
.B salt.auth.auto.auth(username, password)
Authenticate!
.UNINDENT
.SS salt.auth.keystone
.sp
Provide authentication using OpenStack Keystone
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
keystoneclient Python module
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.keystone.auth(username, password)
Try and authenticate
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.keystone.get_auth_url()
Try and get the URL from the config, else return localhost
.UNINDENT
.SS salt.auth.ldap
.sp
Provide authentication using simple LDAP binds
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
ldap Python module
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.ldap.auth(username, password)
Simple LDAP auth
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.ldap.groups(username, **kwargs)
Authenticate against an LDAP group
.sp
Uses groupou and basedn specified in group to filter
group search
.UNINDENT
.SS salt.auth.pam
.sp
Authenticate against PAM
.sp
Provides an authenticate function that will allow the caller to authenticate
a user against the Pluggable Authentication Modules (PAM) on the system.
.sp
Implemented using ctypes, so no compilation is necessary.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
PAM authentication will not work for the \fBroot\fP user.
.sp
The Python interface to PAM does not support authenticating as \fBroot\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.auth.pam.PamConv
Wrapper class for pam_conv structure
.INDENT 7.0
.TP
.B appdata_ptr
Structure/Union member
.UNINDENT
.INDENT 7.0
.TP
.B conv
Structure/Union member
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.auth.pam.PamHandle
Wrapper class for pam_handle_t
.INDENT 7.0
.TP
.B handle
Structure/Union member
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.auth.pam.PamMessage
Wrapper class for pam_message structure
.INDENT 7.0
.TP
.B msg
Structure/Union member
.UNINDENT
.INDENT 7.0
.TP
.B msg_style
Structure/Union member
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.auth.pam.PamResponse
Wrapper class for pam_response structure
.INDENT 7.0
.TP
.B resp
Structure/Union member
.UNINDENT
.INDENT 7.0
.TP
.B resp_retcode
Structure/Union member
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.pam.auth(username, password, **kwargs)
Authenticate via pam
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.pam.authenticate(username, password, service=\(aqlogin\(aq)
Returns True if the given username and password authenticate for the
given service. Returns False otherwise
.sp
\fBusername\fP: the username to authenticate
.sp
\fBpassword\fP: the password in plain text
.INDENT 7.0
.TP
.B \fBservice\fP: the PAM service to authenticate against.
Defaults to \(aqlogin\(aq
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.pam.groups(username, *args, **kwargs)
Retrieve groups for a given user for this auth provider
.sp
Uses system groups
.UNINDENT
.SS salt.auth.pki
.sp
Authenticate via a PKI certificate.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module is Experimental and should be used with caution
.UNINDENT
.UNINDENT
.sp
Provides an authenticate function that will allow the caller to authenticate
a user via their public cert against a pre\-defined Certificate Authority.
.sp
TODO: Add a \(aqca_dir\(aq option to configure a directory of CA files, a la Apache.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
pyOpenSSL module
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.pki.auth(pem, **kwargs)
Returns True if the given user cert was issued by the CA.
Returns False otherwise.
.sp
\fBpem\fP: a pem\-encoded user public key (certificate)
.sp
Configure the CA cert in the master config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pki:
ca_file: /etc/pki/tls/ca_certs/trusted\-ca.crt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.auth.stormpath_mod
.sp
Salt Stormpath Authentication
.sp
Module to provide authentication using Stormpath as the backend.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
stormpath\-sdk Python module
.UNINDENT
.TP
.B configuration
This module requires the development branch of the
stormpath\-sdk which can be found here:
\fI\%https://github.com/stormpath/stormpath\-sdk\-python\fP
.sp
The following config items are required in the master config:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
stormpath.api_key_file: <path/to/apiKey.properties>
stormpath.app_url: <Rest url of your Stormpath application>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Ensure that your apiKey.properties is readable by the user the Salt Master
is running as, but not readable by other system users.
.UNINDENT
.INDENT 0.0
.TP
.B salt.auth.stormpath_mod.auth(username, password)
Try and authenticate
.UNINDENT
.SS 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\&.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBConfiguration\fP
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*foo.com\(aq sys.doc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt can also define the target minions with regular expressions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-E \(aq.*\(aq cmd.run \(aqls \-l | grep foo\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or to explicitly list hosts, salt can take a list:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-L foo.bar.baz,quo.qux cmd.run \(aqps aux | grep foo\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.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 glob expression to match the value of the grain. The syntax for
the target is the grain key followed by a globexpression: "os:Arch*".
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos:Fedora\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.items
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
more info on using targeting with grains can be found \fIhere\fP\&.
.SS Targeting with Executions
.sp
As of 0.8.8 targeting with executions is still under heavy development and this
documentation is written to reference the behavior of execution matching in the
future.
.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 arbitrary running
data on the 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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-C \(aqG@os:Debian and webser* or E@db.*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example any minion who\(aqs id starts with \fBwebser\fP 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 \fB@\fP symbol. In the above example a grain
is used with \fBG@\fP as well as a regular expression with \fBE@\fP\&. The
\fBwebser*\fP target does not need to be prefaced with a target type specifier
because it is a glob.
.sp
more info on using compound targeting can be found \fIhere\fP\&.
.SS Node Group Targeting
.sp
New in version 0.9.5.
.sp
For certain cases, it can be convenient to have a predefined group of minions
on which to execute commands. This can be accomplished using what are called
\fInodegroups\fP\&. Nodegroups allow for predefined
compound targets to be declared in the master configuration file, as a sort of
shorthand for having to type out complicated compound expressions.
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
More info on using nodegroups can be found \fIhere\fP\&.
.SS Calling the Function
.sp
The function to call on the specified target is placed after the target
specification.
.sp
New in version 0.9.8.
.sp
Functions may also accept arguments, space\-delimited:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Optional, keyword arguments are also supported:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.install salt timeout=5 upgrade=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
They are always in the form of \fBkwarg=argument\fP\&.
.sp
Arguments are formatted as YAML:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run \(aqecho "Hello: $FIRST_NAME"\(aq env=\(aq{FIRST_NAME: "Joe"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note: dictionaries must have curly braces around them (like the \fBenv\fP
keyword argument above). This was changed in 0.15.1: in the above example,
the first argument used to be parsed as the dictionary
\fB{\(aqecho "Hello\(aq: \(aq$FIRST_NAME"\(aq}\fP\&. This was generally not the expected
behavior.
.sp
If you want to test what parameters are actually passed to a module, use the
\fBtest.arg_repr\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.arg_repr \(aqecho "Hello: $FIRST_NAME"\(aq env=\(aq{FIRST_NAME: "Joe"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Compound Command Execution
.sp
If a series of commands needs to be sent to a single target specification then
the commands can be sent in a single publish. This can make gathering
groups of information faster, and lowers the stress on the network for repeated
commands.
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqcat /proc/cpuinfo\(aq,,foo
.ft P
.fi
.UNINDENT
.UNINDENT
.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\&.
.sp
If you need to pass arguments that include commas, then make sure you add
spaces around the commas that separate arguments. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqecho "1,2,3"\(aq , , foo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You may change the arguments separator using the \fB\-\-args\-separator\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-\-args\-separator=:: \(aq*\(aq some.fun,test.echo params with , comma :: foo
.ft P
.fi
.UNINDENT
.UNINDENT
.SS salt\-call
.SS \fBsalt\-call\fP
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call [options]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The salt\-call command is used to run module functions locally on a minion
instead of executing them from the master.
.SS Options
.INDENT 0.0
.TP
.B \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.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, \-\-documentation
Return the documentation for the specified module or for all modules if
none are specified
.UNINDENT
.INDENT 0.0
.TP
.B \-\-master=MASTER
Specify the master to use. The minion must be authenticated with the
master. If this option is omitted, the master options from the minion
config will be used. If multi masters are set up the first listed master
that responds will be used.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-return RETURNER
Set salt\-call to pass the return data to one or many returner interfaces.
To use many returner interfaces specify a comma delimited list of
returners.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-local
Run salt\-call locally, as if there was no master running.
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBinfo\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/minion\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBinfo\fP\&.
.UNINDENT
.SS Output Options
.INDENT 0.0
.TP
.B \-\-out
Pass in an alternative outputter to display the return of data. This
outputter can be any of the available outputters:
.INDENT 7.0
.INDENT 3.5
\fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP
.UNINDENT
.UNINDENT
.sp
Some outputters are formatted only for data returned from specific
functions; for instance, the \fBgrains\fP outputter will not work for non\-grains
data.
.sp
If an outputter is used that does not support the data passed into it, then
Salt will fall back on the \fBpprint\fP outputter and display the return data
using the Python \fBpprint\fP standard library module.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT
Print the output indented by the provided value in spaces. Negative values
disable indentation. Only applicable in outputters that support
indentation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE
Write the output to the specified file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-color
Disable all colored output
.UNINDENT
.INDENT 0.0
.TP
.B \-\-force\-color
Force colored output
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
When using colored output the color codes are as follows:
.sp
\fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes
changes and success and \fByellow\fP denotes a expected future change in configuration.
.UNINDENT
.UNINDENT
.UNINDENT
.SS See also
.sp
\fIsalt(1)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt
.SS \fBsalt\fP
.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\%\(aqG@os\fP:Arch.* and webserv* or \fI\%G@kernel\fP:FreeBSD\(aq [ options ] 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 \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-t TIMEOUT, \-\-timeout=TIMEOUT
The timeout in seconds to wait for replies from the Salt minions. The
timeout number specifies how long the command line client will wait to
query the minions and check on running jobs. Default: 5
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-static
By default as of version 0.9.8 the salt command returns data to the
console as it is received from minions, but previous releases would return
data only after all data was received. To only return the data with a hard
timeout and after all minions have returned then use the static option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-async
Instead of waiting for the job to run on minions only print the jod id of
the started execution and complete.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-state\-output=STATE_OUTPUT
New in version 0.17.
.sp
Override the configured state_output value for minion output. Default:
full
.UNINDENT
.INDENT 0.0
.TP
.B \-\-subset=SUBSET
Execute the routine on a random subset of the targeted minions. The
minions will be verified that they have the named function before
executing.
.UNINDENT
.INDENT 0.0
.TP
.B \-v VERBOSE, \-\-verbose
Turn on verbosity for the salt call, this will cause the salt command to
print out extra data like the job id.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show\-timeout
Instead of only showing the return data from the online minions this option
also prints the names of the minions which could not be reached.
.UNINDENT
.INDENT 0.0
.TP
.B \-b BATCH, \-\-batch\-size=BATCH
Instead of executing on all targeted minions at once, execute on a
progressive set of minions. This option takes an argument in the form of
an explicit number of minions to execute at once, or a percentage of
minions to execute on.
.UNINDENT
.INDENT 0.0
.TP
.B \-a EAUTH, \-\-auth=EAUTH
Pass in an external authentication medium to validate against. The
credentials will be prompted for. Can be used with the \-T option.
.UNINDENT
.INDENT 0.0
.TP
.B \-T, \-\-make\-token
Used in conjunction with the \-a option. This creates a token that allows
for the authenticated user to send commands without needing to
re\-authenticate.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-return=RETURNER
Chose an alternative returner to call on the minion, if an alternative
returner is used then the return will not come back to the command line
but will be sent to the specified return system.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-doc, \-\-documentation
Return the documentation for the module functions available on the minions
.UNINDENT
.INDENT 0.0
.TP
.B \-\-args\-separator=ARGS_SEPARATOR
Set the special argument used as a delimiter between command arguments of
compound commands. This is useful when one wants to pass commas as
arguments to some of the commands in a compound command.
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/master\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS Target Selection
.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>:<glob
expression>\(aq; example: \(aqos:Arch*\(aq
.sp
This was changed in version 0.9.8 to accept glob expressions instead of
regular expression. To use regular expression matching with grains, use
the \-\-grain\-pcre option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-grain\-pcre
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>:<
regular expression>\(aq; example: \(aqos:Arch.*\(aq
.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 \-R, \-\-range
Instead of using shell globs to evaluate the target, use a range expression
to identify targets. Range expressions look like %cluster.
.sp
Using the Range option requires that a range server is set up and the
location of the range server is referenced in the master configuration
file.
.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 \fBand\fP or \fBor\fP\&. 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 \-I, \-\-pillar
Instead of using shell globs to evaluate the target, use a pillar value to
identify targets. The syntax for the target is the pillar key followed by
a glob expression: "role:production*"
.UNINDENT
.INDENT 0.0
.TP
.B \-S, \-\-ipcidr
Match based on Subnet (CIDR notation) or IPv4 address.
.UNINDENT
.SS Output Options
.INDENT 0.0
.TP
.B \-\-out
Pass in an alternative outputter to display the return of data. This
outputter can be any of the available outputters:
.INDENT 7.0
.INDENT 3.5
\fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP
.UNINDENT
.UNINDENT
.sp
Some outputters are formatted only for data returned from specific
functions; for instance, the \fBgrains\fP outputter will not work for non\-grains
data.
.sp
If an outputter is used that does not support the data passed into it, then
Salt will fall back on the \fBpprint\fP outputter and display the return data
using the Python \fBpprint\fP standard library module.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT
Print the output indented by the provided value in spaces. Negative values
disable indentation. Only applicable in outputters that support
indentation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE
Write the output to the specified file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-color
Disable all colored output
.UNINDENT
.INDENT 0.0
.TP
.B \-\-force\-color
Force colored output
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
When using colored output the color codes are as follows:
.sp
\fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes
changes and success and \fByellow\fP denotes a expected future change in configuration.
.UNINDENT
.UNINDENT
.UNINDENT
.SS See also
.sp
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt\-cloud
.SS \fBsalt\-cloud\fP
.sp
Provision virtual machines in the cloud with Salt
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-m /etc/salt/cloud.map
salt\-cloud \-p PROFILE NAME
salt\-cloud \-p PROFILE NAME1 NAME2 NAME3 NAME4 NAME5 NAME6
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
Salt Cloud is the system used to provision virtual machines on various public
clouds via a cleanly controlled profile and mapping system.
.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 \-p PROFILE, \-\-profile=PROFILE
Select a single profile to build the named cloud VMs from. The profile
must be defined in the specified profiles file.
.UNINDENT
.INDENT 0.0
.TP
.B \-m MAP, \-\-map=MAP
Specify a map file to use. If used without any other options, this option
will ensure that all of the mapped VMs are created. If the named VM
already exists then it will be skipped.
.UNINDENT
.INDENT 0.0
.TP
.B \-H, \-\-hard
When specifying a map file, the default behavior is to ensure that all of
the VMs specified in the map file are created. If the \-\-hard option is
set, then any VMs that exist on configured cloud providers that are
not specified in the map file will be destroyed. Be advised that this can
be a destructive operation and should be used with care.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-destroy
Pass in the name(s) of VMs to destroy, salt\-cloud will search the
configured cloud providers for the specified names and destroy the
VMs. Be advised that this is a destructive operation and should be used
with care. Can be used in conjunction with the \-m option to specify a map
of VMs to be deleted.
.UNINDENT
.INDENT 0.0
.TP
.B \-P, \-\-parallel
Normally when building many cloud VMs they are executed serially. The \-P
option will run each cloud vm build in a separate process allowing for
large groups of VMs to be build at once.
.sp
Be advised that some cloud provider\(aqs systems don\(aqt seem to be well suited
for this influx of vm creation. When creating large groups of VMs watch the
cloud provider carefully.
.UNINDENT
.INDENT 0.0
.TP
.B \-Q, \-\-query
Execute a query and print out information about all cloud VMs. Can be used
in conjunction with \-m to display only information about the specified map.
.UNINDENT
.INDENT 0.0
.TP
.B \-F, \-\-full\-query
Execute a query and print out all available information about all cloud VMs.
Can be used in conjunction with \-m to display only information about the
specified map.
.UNINDENT
.INDENT 0.0
.TP
.B \-S, \-\-select\-query
Execute a query and print out selected information about all cloud VMs.
Can be used in conjunction with \-m to display only information about the
specified map.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-list\-images
Display a list of images available in configured cloud providers.
Pass the cloud provider that available images are desired on, aka
"linode", or pass "all" to list images for all configured cloud providers.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-list\-sizes
Display a list of sizes available in configured cloud providers. Pass the
cloud provider that available sizes are desired on, aka "aws", or pass
"all" to list sizes for all configured cloud providers
.UNINDENT
.INDENT 0.0
.TP
.B \-C CLOUD_CONFIG, \-\-cloud\-config=CLOUD_CONFIG
Specify an alternative location for the salt cloud configuration file.
Default location is /etc/salt/cloud.
.UNINDENT
.INDENT 0.0
.TP
.B \-M MASTER_CONFIG, \-\-master\-config=MASTER_CONFIG
Specify an alternative location for the salt master configuration file.
The salt master configuration file is used to determine how to handle the
minion RSA keys. Default location is /etc/salt/master.
.UNINDENT
.INDENT 0.0
.TP
.B \-V VM_CONFIG, \-\-profiles=VM_CONFIG, \-\-vm_config=VM_CONFIG
Specify an alternative location for the salt cloud profiles file.
Default location is /etc/salt/cloud.profiles.
.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 \-\-out=OUTPUT, \-\-output=OUTPUT
Print the output from the salt\-cloud command using the specified outputter. The
builtins are \(aqraw\(aq, \(aqcompact\(aq, \(aqno_return\(aq, \(aqgrains\(aq, \(aqoverstatestage\(aq, \(aqpprint\(aq,
\(aqjson\(aq, \(aqnested\(aq, \(aqyaml\(aq, \(aqhighstate\(aq, \(aqquiet\(aq, \(aqkey\(aq, \(aqtxt\(aq, \(aqnewline_values_only\(aq,
\(aqvirt_query\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-color
Disable all colored output.
.UNINDENT
.SS Examples
.sp
To create 4 VMs named web1, web2, db1 and db2 from specified profiles:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p fedora_rackspace web1 web2 db1 db2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To read in a map file and create all VMs specified therein:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-m /path/to/cloud.map
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To read in a map file and create all VMs specified therein in parallel:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-m /path/to/cloud.map \-P
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To delete any VMs specified in the map file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-m /path/to/cloud.map \-d
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To delete any VMs NOT specified in the map file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-m /path/to/cloud.map \-H
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To display the status of all VMs specified in the map file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-m /path/to/cloud.map \-Q
.ft P
.fi
.UNINDENT
.UNINDENT
.SS See also
.sp
\fIsalt\-cloud(7)\fP
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt\-cp
.SS \fBsalt\-cp\fP
.sp
Copy a file to a set of systems
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.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 \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-t TIMEOUT, \-\-timeout=TIMEOUT
The timeout in seconds to wait for replies from the Salt minions. The
timeout number specifies how long the command line client will wait to
query the minions and check on running jobs. Default: 5
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/master\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS Target Selection
.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>:<glob
expression>\(aq; example: \(aqos:Arch*\(aq
.sp
This was changed in version 0.9.8 to accept glob expressions instead of
regular expression. To use regular expression matching with grains, use
the \-\-grain\-pcre option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-grain\-pcre
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>:<
regular expression>\(aq; example: \(aqos:Arch.*\(aq
.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 \-R, \-\-range
Instead of using shell globs to evaluate the target, use a range expression
to identify targets. Range expressions look like %cluster.
.sp
Using the Range option requires that a range server is set up and the
location of the range server is referenced in the master configuration
file.
.UNINDENT
.SS See also
.sp
\fIsalt(1)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt\-key
.SS \fBsalt\-key\fP
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-key [ options ]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
Salt\-key executes simple management of Salt server public keys used for
authentication.
.SS Options
.INDENT 0.0
.TP
.B \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Suppress output
.UNINDENT
.INDENT 0.0
.TP
.B \-y, \-\-yes
Answer \(aqYes\(aq to all questions presented, defaults to False
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/minion\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS Output Options
.INDENT 0.0
.TP
.B \-\-out
Pass in an alternative outputter to display the return of data. This
outputter can be any of the available outputters:
.INDENT 7.0
.INDENT 3.5
\fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP
.UNINDENT
.UNINDENT
.sp
Some outputters are formatted only for data returned from specific
functions; for instance, the \fBgrains\fP outputter will not work for non\-grains
data.
.sp
If an outputter is used that does not support the data passed into it, then
Salt will fall back on the \fBpprint\fP outputter and display the return data
using the Python \fBpprint\fP standard library module.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT
Print the output indented by the provided value in spaces. Negative values
disable indentation. Only applicable in outputters that support
indentation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE
Write the output to the specified file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-color
Disable all colored output
.UNINDENT
.INDENT 0.0
.TP
.B \-\-force\-color
Force colored output
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
When using colored output the color codes are as follows:
.sp
\fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes
changes and success and \fByellow\fP denotes a expected future change in configuration.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Actions
.INDENT 0.0
.TP
.B \-l ARG, \-\-list=ARG
List the public keys. The args \fBpre\fP, \fBun\fP, and \fBunaccepted\fP will
list unaccepted/unsigned keys. \fBacc\fP or \fBaccepted\fP will list
accepted/signed keys. \fBrej\fP or \fBrejected\fP will list rejected keys.
Finally, \fBall\fP will list all keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-L, \-\-list\-all
List all public keys. (Deprecated: use \fB\-\-list all\fP)
.UNINDENT
.INDENT 0.0
.TP
.B \-a ACCEPT, \-\-accept=ACCEPT
Accept the specified public key (use \-\-include\-all to match rejected keys
in addition to pending keys). Globs are supported.
.UNINDENT
.INDENT 0.0
.TP
.B \-A, \-\-accept\-all
Accepts all pending keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-r REJECT, \-\-reject=REJECT
Reject the specified public key (use \-\-include\-all to match accepted keys
in addition to pending keys). Globs are supported.
.UNINDENT
.INDENT 0.0
.TP
.B \-R, \-\-reject\-all
Rejects all pending keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-include\-all
Include non\-pending keys when accepting/rejecting.
.UNINDENT
.INDENT 0.0
.TP
.B \-p PRINT, \-\-print=PRINT
Print the specified public key.
.UNINDENT
.INDENT 0.0
.TP
.B \-P, \-\-print\-all
Print all public keys
.UNINDENT
.INDENT 0.0
.TP
.B \-d DELETE, \-\-delete=DELETE
Delete the specified key. Globs are supported.
.UNINDENT
.INDENT 0.0
.TP
.B \-D, \-\-delete\-all
Delete all keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-f FINGER, \-\-finger=FINGER
Print the specified key\(aqs fingerprint.
.UNINDENT
.INDENT 0.0
.TP
.B \-F, \-\-finger\-all
Print all keys\(aq fingerprints.
.UNINDENT
.SS Key Generation Options
.INDENT 0.0
.TP
.B \-\-gen\-keys=GEN_KEYS
Set a name to generate a keypair for use with salt
.UNINDENT
.INDENT 0.0
.TP
.B \-\-gen\-keys\-dir=GEN_KEYS_DIR
Set the directory to save the generated keypair. Only works
with \(aqgen_keys_dir\(aq option; default is the current directory.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keysize=KEYSIZE
Set the keysize for the generated key, only works with
the \(aq\-\-gen\-keys\(aq option, the key size must be 2048 or
higher, otherwise it will be rounded up to 2048. The
default is 2048.
.UNINDENT
.SS See also
.sp
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt\-master
.SS \fBsalt\-master\fP
.sp
The Salt master daemon, used to control the Salt minions
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master [ options ]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The master daemon controls the Salt minions
.SS Options
.INDENT 0.0
.TP
.B \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-u USER, \-\-user=USER
Specify user to run salt\-master
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run salt\-master as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file PIDFILE
Specify the location of the pidfile. Default: /var/run/salt\-master\&.pid
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/master\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS See also
.sp
\fIsalt(1)\fP
\fIsalt(7)\fP
\fIsalt\-minion(1)\fP
.SS salt\-minion
.SS \fBsalt\-minion\fP
.sp
The Salt minion daemon, receives commands from a remote Salt master.
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion [ options ]
.ft P
.fi
.UNINDENT
.UNINDENT
.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 \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-u USER, \-\-user=USER
Specify user to run salt\-minion
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run salt\-minion as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file PIDFILE
Specify the location of the pidfile. Default: /var/run/salt\-minion\&.pid
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/minion\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS See also
.sp
\fIsalt(1)\fP
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
.SS salt\-run
.SS \fBsalt\-run\fP
.sp
Execute a Salt runner
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run RUNNER
.ft P
.fi
.UNINDENT
.UNINDENT
.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 \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-t TIMEOUT, \-\-timeout=TIMEOUT
The timeout in seconds to wait for replies from the Salt minions. The
timeout number specifies how long the command line client will wait to
query the minions and check on running jobs. Default: 1
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-doc, \-\-documentation
Display documentation for runners, pass a module or a runner to see
documentation on only that module/runner.
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/master\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS See also
.sp
\fIsalt(1)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt\-ssh
.SS \fBsalt\-ssh\fP
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-ssh \(aq*\(aq [ options ] sys.doc
salt\-ssh \-E \(aq.*\(aq [ options ] sys.doc cmd
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
Salt SSH allows for salt routines to be executed using only SSH for transport
.SS Options
.INDENT 0.0
.TP
.B \-r, \-\-raw, \-\-raw\-shell
Execute a raw shell command.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-priv
Specify the SSH private key file to be used for authentication.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-roster
Define which roster system to use, this defines if a database backend,
scanner, or custom roster system is used. Default is the flat file roster.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-roster\-file
Define an alternative location for the default roster file location. The
default roster file is called \fBroster\fP and is found in the same directory
as the master config file.
.sp
New in version 2014.1.0.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-refresh, \-\-refresh\-cache
Force a refresh of the master side data cache of the target\(aqs data. This
is needed if a target\(aqs grains have been changed and the auto refresh
timeframe has not been reached.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-procs
Set the number of concurrent minions to communicate with. This value
defines how many processes are opened up at a time to manage connections,
the more running process the faster communication should be, default
is 25.
.UNINDENT
.INDENT 0.0
.TP
.B \-i, \-\-ignore\-host\-keys
Ignore the ssh host keys which by default are honored and connections
would ask for approval.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-passwd
Set the default password to attempt to use when authenticating.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-key\-deploy
Set this flag to attempt to deploy the authorized ssh key with all
minions. This combined with \-\-passwd can make initial deployment of keys
very fast and easy.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.SS Target Selection
.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>:<glob
expression>\(aq; example: \(aqos:Arch*\(aq
.sp
This was changed in version 0.9.8 to accept glob expressions instead of
regular expression. To use regular expression matching with grains, use
the \-\-grain\-pcre option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-grain\-pcre
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>:<
regular expression>\(aq; example: \(aqos:Arch.*\(aq
.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 \-R, \-\-range
Instead of using shell globs to evaluate the target, use a range expression
to identify targets. Range expressions look like %cluster.
.sp
Using the Range option requires that a range server is set up and the
location of the range server is referenced in the master configuration
file.
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/ssh\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS Output Options
.INDENT 0.0
.TP
.B \-\-out
Pass in an alternative outputter to display the return of data. This
outputter can be any of the available outputters:
.INDENT 7.0
.INDENT 3.5
\fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP
.UNINDENT
.UNINDENT
.sp
Some outputters are formatted only for data returned from specific
functions; for instance, the \fBgrains\fP outputter will not work for non\-grains
data.
.sp
If an outputter is used that does not support the data passed into it, then
Salt will fall back on the \fBpprint\fP outputter and display the return data
using the Python \fBpprint\fP standard library module.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT
Print the output indented by the provided value in spaces. Negative values
disable indentation. Only applicable in outputters that support
indentation.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE
Write the output to the specified file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-color
Disable all colored output
.UNINDENT
.INDENT 0.0
.TP
.B \-\-force\-color
Force colored output
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
When using colored output the color codes are as follows:
.sp
\fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes
changes and success and \fByellow\fP denotes a expected future change in configuration.
.UNINDENT
.UNINDENT
.UNINDENT
.SS See also
.sp
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt\-syndic
.SS \fBsalt\-syndic\fP
.sp
The Salt syndic daemon, a special minion that passes through commands from a
higher master
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-syndic [ options ]
.ft P
.fi
.UNINDENT
.UNINDENT
.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 \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory contains
the configuration files for Salt master and minions. The default location
on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-u USER, \-\-user=USER
Specify user to run salt\-syndic
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run salt\-syndic as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file PIDFILE
Specify the location of the pidfile. Default: /var/run/salt\-syndic\&.pid
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/master\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SS See also
.sp
\fIsalt(1)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SS salt\-api
.SS \fBsalt\-api\fP
.sp
Start interfaces used to remotely connect to the salt master
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-api
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Description
.sp
The Salt API system manages network api connectors for the Salt 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
Specify an alternative location for the salt master configuration file.
.UNINDENT
.SS See also
.sp
\fIsalt\-api(7)\fP
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
.SS Client ACL system
.sp
The salt client ACL system is a means to allow system users other than root to
have access to execute select salt commands on minions from the master.
.sp
The client ACL system is configured in the master configuration file via the
\fBclient_acl\fP configuration option. Under the \fBclient_acl\fP configuration
option the users open to send commands are specified and then a list of regular
expressions which specify the minion functions which will be made available to
specified user. This configuration is much like the \fBpeer\fP configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Allow thatch to execute anything and allow fred to use ping and pkg
client_acl:
thatch:
\- .*
fred:
\- test.*
\- pkg.*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Permission Issues
.sp
Directories required for \fBclient_acl\fP must be modified to be readable by the
users specified:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chmod 755 /var/cache/salt /var/cache/salt/jobs /var/run/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In addition to the changes above you will also need to modify the
permissions of /var/log/salt and the existing log file. If you do not
wish to do this then you must disable logging or Salt will generate
errors as it cannot write to the logs as the system users.
.UNINDENT
.UNINDENT
.sp
If you are upgrading from earlier versions of salt you must also remove any
existing user keys and re\-start the Salt master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rm /var/cache/salt/.*key
service salt\-master restart
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Python client API
.sp
Salt provides several entry points for interfacing with Python applications.
These entry points are often referred to as \fB*Client()\fP APIs. Each client
accesses different parts of Salt, either from the master or from a minion. Each
client is detailed below.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
There are many ways to access Salt programmatically.
.sp
Salt can be used from CLI scripts as well as via a REST interface.
.sp
See Salt\(aqs \fIoutputter system\fP to retrieve structured
data from Salt as JSON, or as shell\-friendly text, or many other formats.
.sp
See the \fBstate.event\fP runner to utilize
Salt\(aqs event bus from shell scripts.
.sp
See the \fI\%salt\-api\fP project to access Salt externally via a REST interface.
It uses Salt\(aqs Python interface documented below and is also useful as a
reference implementation.
.UNINDENT
.UNINDENT
.SS Salt\(aqs \fBopts\fP dictionary
.sp
Some clients require access to Salt\(aqs \fBopts\fP dictionary. (The dictionary
representation of the \fImaster\fP or
\fIminion\fP config files.)
.sp
A common pattern for fetching the \fBopts\fP dictionary is to defer to
environment variables if they exist or otherwise fetch the config from the
default location.
.INDENT 0.0
.TP
.B salt.config.client_config(path, env_var=\(aqSALT_CLIENT_CONFIG\(aq, defaults=None)
Load Master configuration data
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.config
master_opts = salt.config.client_config(\(aq/etc/salt/master\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a dictionary of the Salt Master configuration file with necessary
options needed to communicate with a locally\-running Salt Master daemon.
This function searches for client specific configurations and adds them to
the data from the master configuration.
.sp
This is useful for master\-side operations like
\fI\%LocalClient\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B salt.config.minion_config(path, env_var=\(aqSALT_MINION_CONFIG\(aq, defaults=None, minion_id=False)
Reads in the minion configuration file and sets up special options
.sp
This is useful for Minion\-side operations, such as the
\fI\%Caller\fP class, and manually running the loader
interface.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.client
minion_opts = salt.config.minion_config(\(aq/etc/salt/minion\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Salt\(aqs Loader Interface
.sp
Modules in the Salt ecosystem are loaded into memory using a custom loader
system. This allows modules to have conditional requirements (OS, OS version,
installed libraries, etc) and allows Salt to inject special variables
(\fB__salt__\fP, \fB__opts\fP, etc).
.sp
Most modules can be manually loaded. This is often useful in third\-party Python
apps or when writing tests. However some modules require and expect a full,
running Salt system underneath. Notably modules that facilitate
master\-to\-minion communication such as the \fBmine\fP,
\fBpublish\fP, and \fBpeer\fP execution
modules. The error \fBKeyError: \(aqmaster_uri\(aq\fP is a likely indicator for this
situation. In those instances use the \fI\%Caller\fP class
to execute those modules instead.
.sp
Each module type has a corresponding loader function.
.INDENT 0.0
.TP
.B salt.loader.minion_mods(opts, context=None, whitelist=None)
Load execution modules
.sp
Returns a dictionary of execution modules appropriate for the current
system by evaluating the __virtual__() function in each module.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.config
import salt.loader
__opts__ = salt.config.minion_config(\(aq/etc/salt/minion\(aq)
__grains__ = salt.loader.grains(__opts__)
__opts__[\(aqgrains\(aq] = __grains__
__salt__ = salt.loader.minion_mods(__opts__)
__salt__[\(aqtest.ping\(aq]()
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.loader.raw_mod(opts, name, functions)
Returns a single module loaded raw and bypassing the __virtual__ function
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.config
import salt.loader
__opts__ = salt.config.minion_config(\(aq/etc/salt/minion\(aq)
testmod = salt.loader.raw_mod(__opts__, \(aqtest\(aq, None)
testmod[\(aqtest.ping\(aq]()
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.loader.states(opts, functions, whitelist=None)
Returns the state modules
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.config
import salt.loader
__opts__ salt.config.minion_config(\(aq/etc/salt/minion\(aq)
statemods = salt.loader.states(__opts__, None)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.loader.grains(opts, force_refresh=False)
Return the functions for the dynamic grains and the values for the static
grains.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.config
import salt.loader
__opts__ salt.config.minion_config(\(aq/etc/salt/minion\(aq)
__grains__ = salt.loader.grains(__opts__)
print __grains__[\(aqid\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Salt\(aqs Client Interfaces
.SS LocalClient
.INDENT 0.0
.TP
.B class salt.client.LocalClient(c_path=\(aq/etc/salt/master\(aq, mopts=None, skip_perm_errors=False)
The interface used by the \fBsalt\fP CLI tool on the Salt Master
.sp
\fBLocalClient\fP is used to send a command to Salt minions to execute
\fIexecution modules\fP and return the results to the
Salt Master.
.sp
Importing and using \fBLocalClient\fP must be done on the same machine as the
Salt Master and it must be done using the same user that the Salt Master is
running as. (Unless \fBexternal_auth\fP is configured and
authentication credentials are included in the execution).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.client
local = salt.client.LocalClient()
local.cmd(\(aq*\(aq, \(aqtest.fib\(aq, [10])
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, **kwargs)
Synchronously execute a command on targeted minions
.sp
The cmd method will execute and wait for the timeout period for all
minions to reply, then it will return all minion data at once.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> import salt.client
>>> local = salt.client.LocalClient()
>>> local.cmd(\(aq*\(aq, \(aqcmd.run\(aq, [\(aqwhoami\(aq])
{\(aqjerry\(aq: \(aqroot\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With extra keyword arguments for the command function to be run:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
local.cmd(\(aq*\(aq, \(aqtest.arg\(aq, [\(aqarg1\(aq, \(aqarg2\(aq], kwarg={\(aqfoo\(aq: \(aqbar\(aq})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Compound commands can be used for multiple executions in a single
publish. Function names and function arguments are provided in separate
lists but the index values must correlate and an empty list must be
used if no arguments are required.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> local.cmd(\(aq*\(aq, [
\(aqgrains.items\(aq,
\(aqsys.doc\(aq,
\(aqcmd.run\(aq,
],
[
[],
[],
[\(aquptime\(aq],
])
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtgt\fP (\fIstring or list\fP) \-\- Which minions to target for the execution. Default is shell
glob. Modified by the \fBexpr_form\fP option.
.IP \(bu 2
\fBfun\fP (\fIstring or list of strings\fP) \-\-
.sp
The module and function to call on the specified minions of
the form \fBmodule.function\fP\&. For example \fBtest.ping\fP or
\fBgrains.items\fP\&.
.INDENT 2.0
.TP
.B Compound commands
Multiple functions may be called in a single publish by
passing a list of commands. This can dramatically lower
overhead and speed up the application communicating with Salt.
.sp
This requires that the \fBarg\fP param is a list of lists. The
\fBfun\fP list and the \fBarg\fP list must correlate by index
meaning a function that does not take arguments must still have
a corresponding empty list at the expected index.
.UNINDENT
.IP \(bu 2
\fBarg\fP (\fIlist or list\-of\-lists\fP) \-\- A list of arguments to pass to the remote function. If the
function takes no arguments \fBarg\fP may be omitted except when
executing a compound command.
.IP \(bu 2
\fBtimeout\fP \-\- Seconds to wait after the last minion returns but
before all minions return.
.IP \(bu 2
\fBexpr_form\fP \-\-
.sp
The type of \fBtgt\fP\&. Allowed values:
.INDENT 2.0
.IP \(bu 2
\fBglob\fP \- Bash glob completion \- Default
.IP \(bu 2
\fBpcre\fP \- Perl style regular expression
.IP \(bu 2
\fBlist\fP \- Python list of hosts
.IP \(bu 2
\fBgrain\fP \- Match based on a grain comparison
.IP \(bu 2
\fBgrain_pcre\fP \- Grain comparison with a regex
.IP \(bu 2
\fBpillar\fP \- Pillar data comparison
.IP \(bu 2
\fBnodegroup\fP \- Match on nodegroup
.IP \(bu 2
\fBrange\fP \- Use a Range server for matching
.IP \(bu 2
\fBcompound\fP \- Pass a compound match string
.UNINDENT
.IP \(bu 2
\fBret\fP \-\- The returner to use. The value passed can be single
returner, or a comma delimited list of returners to call in order
on the minions
.IP \(bu 2
\fBkwarg\fP \-\- A dictionary with keyword arguments for the function.
.IP \(bu 2
\fBkwargs\fP \-\-
.sp
Optional keyword arguments.
Authentication credentials may be passed when using
\fBexternal_auth\fP\&.
.sp
For example: \fBlocal.cmd(\(aq*\(aq, \(aqtest.ping\(aq, username=\(aqsaltdev\(aq,
password=\(aqsaltdev\(aq, eauth=\(aqpam\(aq)\fP\&.
Or: \fBlocal.cmd(\(aq*\(aq, \(aqtest.ping\(aq,
token=\(aq5871821ea51754fdcea8153c1c745433\(aq)\fP
.UNINDENT
.TP
.B Returns
A dictionary with the result of the execution, keyed by
minion ID. A compound command will return a sub\-dictionary keyed by
function name.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_async(tgt, fun, arg=(), expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, **kwargs)
Asynchronously send a command to connected minions
.sp
The function signature is the same as \fBcmd()\fP with the
following exceptions.
.INDENT 7.0
.TP
.B Returns
A job ID or 0 on failure.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> local.cmd_async(\(aq*\(aq, \(aqtest.sleep\(aq, [300])
\(aq20131219215921857715\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_batch(tgt, fun, arg=(), expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, batch=\(aq10%\(aq, **kwargs)
Iteratively execute a command on subsets of minions at a time
.sp
The function signature is the same as \fBcmd()\fP with the
following exceptions.
.INDENT 7.0
.TP
.B Parameters
\fBbatch\fP \-\- The batch identifier of systems to execute on
.TP
.B Returns
A generator of minion returns
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> returns = local.cmd_batch(\(aq*\(aq, \(aqstate.highstate\(aq, bat=\(aq10%\(aq)
>>> for return in returns:
\&... print return
{\(aqjerry\(aq: {...}}
{\(aqdave\(aq: {...}}
{\(aqstewart\(aq: {...}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_iter(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, **kwargs)
Yields the individual minion returns as they come in
.sp
The function signature is the same as \fBcmd()\fP with the
following exceptions.
.INDENT 7.0
.TP
.B Returns
A generator
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> ret = local.cmd_iter(\(aq*\(aq, \(aqtest.ping\(aq)
>>> for i in ret:
\&... print i
{\(aqjerry\(aq: {\(aqret\(aq: True}}
{\(aqdave\(aq: {\(aqret\(aq: True}}
{\(aqstewart\(aq: {\(aqret\(aq: True}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_iter_no_block(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, **kwargs)
Blocks while waiting for individual minions to return.
.sp
The function signature is the same as \fBcmd()\fP with the
following exceptions.
.INDENT 7.0
.TP
.B Returns
None until the next minion returns. This allows for actions
to be injected in between minion returns.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> ret = local.cmd_iter(\(aq*\(aq, \(aqtest.ping\(aq)
>>> for i in ret:
\&... print i
None
{\(aqjerry\(aq: {\(aqret\(aq: True}}
{\(aqdave\(aq: {\(aqret\(aq: True}}
None
{\(aqstewart\(aq: {\(aqret\(aq: True}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_subset(tgt, fun, arg=(), expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, sub=3, cli=False, **kwargs)
Execute a command on a random subset of the targeted systems
.sp
The function signature is the same as \fBcmd()\fP with the
following exceptions.
.INDENT 7.0
.TP
.B Parameters
\fBsub\fP \-\- The number of systems to execute on
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> SLC.cmd_subset(\(aq*\(aq, \(aqtest.ping\(aq, sub=1)
{\(aqjerry\(aq: True}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B get_cli_returns(jid, minions, timeout=None, tgt=\(aq*\(aq, tgt_type=\(aqglob\(aq, verbose=False, show_jid=False, **kwargs)
Starts a watcher looking at the return data for a specified JID
.INDENT 7.0
.TP
.B Returns
all of the information for the JID
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B get_event_iter_returns(jid, minions, timeout=None)
Gather the return data from the event system, break hard when timeout
is reached.
.UNINDENT
.INDENT 7.0
.TP
.B run_job(tgt, fun, arg=(), expr_form=\(aqglob\(aq, ret=\(aq\(aq, timeout=None, kwarg=None, **kwargs)
Asynchronously send a command to connected minions
.sp
Prep the job directory and publish a command to any targeted minions.
.INDENT 7.0
.TP
.B Returns
A dictionary of (validated) \fBpub_data\fP or an empty
dictionary on failure. The \fBpub_data\fP contains the job ID and a
list of all minions that are expected to return data.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> local.run_job(\(aq*\(aq, \(aqtest.sleep\(aq, [300])
{\(aqjid\(aq: \(aq20131219215650131543\(aq, \(aqminions\(aq: [\(aqjerry\(aq]}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Salt Caller
.INDENT 0.0
.TP
.B class salt.client.Caller(c_path=\(aq/etc/salt/minion\(aq, mopts=None)
\fBCaller\fP is the same interface used by the \fBsalt\-call\fP
command\-line tool on the Salt Minion.
.sp
Importing and using \fBCaller\fP must be done on the same machine as a
Salt Minion and it must be done using the same user that the Salt Minion is
running as.
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.client
caller = salt.client.Caller()
caller.function(\(aqtest.ping\(aq)
# Or call objects directly
caller.sminion.functions[\(aqcmd.run\(aq](\(aqls \-l\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note, a running master or minion daemon is not required to use this class.
Running \fBsalt\-call \-\-local\fP simply sets \fBfile_client\fP to
\fB\(aqlocal\(aq\fP\&. The same can be achieved at the Python level by including that
setting in a minion config file.
.sp
Instantiate a new Caller() instance using a file system path to the minion
config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
caller = salt.client.Caller(\(aq/path/to/custom/minion_config\(aq)
caller.sminion.functions[\(aqgrains.items\(aq]()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instantiate a new Caller() instance using a dictionary of the minion
config:
.sp
New in version 2014.7.0: Pass the minion config as a dictionary.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.client
import salt.config
opts = salt.config.minion_config(\(aq/etc/salt/minion\(aq)
opts[\(aqfile_client\(aq] = \(aqlocal\(aq
caller = salt.client.Caller(mopts=opts)
caller.sminion.functions[\(aqgrains.items\(aq]()
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B function(fun, *args, **kwargs)
Call a single salt function
.UNINDENT
.UNINDENT
.SS RunnerClient
.INDENT 0.0
.TP
.B class salt.runner.RunnerClient(opts)
The interface used by the \fBsalt\-run\fP CLI tool on the Salt Master
.sp
It executes \fIrunner modules\fP which run on the Salt
Master.
.sp
Importing and using \fBRunnerClient\fP must be done on the same machine as
the Salt Master and it must be done using the same user that the Salt
Master is running as.
.sp
Salt\(aqs \fBexternal_auth\fP can be used to authenticate calls. The
eauth user must be authorized to execute runner modules: (\fB@runner\fP).
Only the \fBmaster_call()\fP below supports eauth.
.INDENT 7.0
.TP
.B async(fun, low, user=\(aqUNKNOWN\(aq)
Execute the function in a multiprocess and return the event tag to use
to watch for the return
.UNINDENT
.INDENT 7.0
.TP
.B cmd(fun, arg, pub_data=None, kwarg=None)
Execute a runner function
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> opts = salt.config.master_config(\(aq/etc/salt/master\(aq)
>>> runner = salt.runner.RunnerClient(opts)
>>> runner.cmd(\(aqjobs.list_jobs\(aq, [])
{
\(aq20131219215650131543\(aq: {
\(aqArguments\(aq: [300],
\(aqFunction\(aq: \(aqtest.sleep\(aq,
\(aqStartTime\(aq: \(aq2013, Dec 19 21:56:50.131543\(aq,
\(aqTarget\(aq: \(aq*\(aq,
\(aqTarget\-type\(aq: \(aqglob\(aq,
\(aqUser\(aq: \(aqsaltdev\(aq
},
\(aq20131219215921857715\(aq: {
\(aqArguments\(aq: [300],
\(aqFunction\(aq: \(aqtest.sleep\(aq,
\(aqStartTime\(aq: \(aq2013, Dec 19 21:59:21.857715\(aq,
\(aqTarget\(aq: \(aq*\(aq,
\(aqTarget\-type\(aq: \(aqglob\(aq,
\(aqUser\(aq: \(aqsaltdev\(aq
},
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_async(low)
Execute a runner function asynchronously; eauth is respected
.sp
This function requires that \fBexternal_auth\fP is configured
and the user is authorized to execute runner functions: (\fB@runner\fP).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
runner.eauth_async({
\(aqfun\(aq: \(aqjobs.list_jobs\(aq,
\(aqusername\(aq: \(aqsaltdev\(aq,
\(aqpassword\(aq: \(aqsaltdev\(aq,
\(aqeauth\(aq: \(aqpam\(aq,
})
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_sync(low, timeout=None)
Execute a runner function synchronously; eauth is respected
.sp
This function requires that \fBexternal_auth\fP is configured
and the user is authorized to execute runner functions: (\fB@runner\fP).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
runner.eauth_sync({
\(aqfun\(aq: \(aqjobs.list_jobs\(aq,
\(aqusername\(aq: \(aqsaltdev\(aq,
\(aqpassword\(aq: \(aqsaltdev\(aq,
\(aqeauth\(aq: \(aqpam\(aq,
})
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS WheelClient
.INDENT 0.0
.TP
.B class salt.wheel.WheelClient(opts=None)
An interface to Salt\(aqs wheel modules
.sp
\fIWheel modules\fP interact with various parts of the
Salt Master.
.sp
Importing and using \fBWheelClient\fP must be done on the same machine as the
Salt Master and it must be done using the same user that the Salt Master is
running as. Unless \fBexternal_auth\fP is configured and the user
is authorized to execute wheel functions: (\fB@wheel\fP).
.INDENT 7.0
.TP
.B async(fun, low, user=\(aqUNKNOWN\(aq)
Execute the function in a multiprocess and return the event tag to use
to watch for the return
.UNINDENT
.INDENT 7.0
.TP
.B cmd(fun, **kwargs)
Execute a wheel function
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> opts = salt.config.master_config(\(aq/etc/salt/master\(aq)
>>> wheel = salt.wheel.Wheel(opts)
>>> wheel.call_func(\(aqkey.list_all\(aq)
{\(aqlocal\(aq: [\(aqmaster.pem\(aq, \(aqmaster.pub\(aq],
\(aqminions\(aq: [\(aqjerry\(aq],
\(aqminions_pre\(aq: [],
\(aqminions_rejected\(aq: []}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_async(low)
Execute a wheel function asynchronously; eauth is respected
.sp
This function requires that \fBexternal_auth\fP is configured
and the user is authorized to execute runner functions: (\fB@wheel\fP).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> wheel.cmd_async({
\(aqfun\(aq: \(aqkey.finger\(aq,
\(aqmatch\(aq: \(aqjerry\(aq,
\(aqeauth\(aq: \(aqauto\(aq,
\(aqusername\(aq: \(aqsaltdev\(aq,
\(aqpassword\(aq: \(aqsaltdev\(aq,
})
{\(aqjid\(aq: \(aq20131219224744416681\(aq, \(aqtag\(aq: \(aqsalt/wheel/20131219224744416681\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cmd_sync(low, timeout=None)
Execute a wheel function synchronously; eauth is respected
.sp
This function requires that \fBexternal_auth\fP is configured
and the user is authorized to execute runner functions: (\fB@wheel\fP).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> wheel.cmd_sync({
\(aqfun\(aq: \(aqkey.finger\(aq,
\(aqmatch\(aq: \(aqjerry\(aq,
\(aqeauth\(aq: \(aqauto\(aq,
\(aqusername\(aq: \(aqsaltdev\(aq,
\(aqpassword\(aq: \(aqsaltdev\(aq,
})
{\(aqminions\(aq: {\(aqjerry\(aq: \(aq5d:f6:79:43:5e:d4:42:3f:57:b8:45:a8:7e:a4:6e:ca\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CloudClient
.INDENT 0.0
.TP
.B class salt.cloud.CloudClient(path=None, opts=None, config_dir=None, pillars=None)
The client class to wrap cloud interactions
.INDENT 7.0
.TP
.B action(fun=None, cloudmap=None, names=None, provider=None, instance=None, kwargs=None)
Execute a single action via the cloud plugin backend
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
client.action(fun=\(aqshow_instance\(aq, names=[\(aqmyinstance\(aq])
client.action(fun=\(aqshow_image\(aq, provider=\(aqmy\-ec2\-config\(aq,
kwargs={\(aqimage\(aq: \(aqami\-10314d79\(aq}
)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B create(provider, names, **kwargs)
Create the named VMs, without using a profile
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
client.create(names=[\(aqmyinstance\(aq], provider=\(aqmy\-ec2\-config\(aq,
kwargs={\(aqimage\(aq: \(aqami\-1624987f\(aq, \(aqsize\(aq: \(aqMicro Instance\(aq,
\(aqssh_username\(aq: \(aqec2\-user\(aq, \(aqsecuritygroup\(aq: \(aqdefault\(aq,
\(aqdelvol_on_destroy\(aq: True})
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B destroy(names)
Destroy the named VMs
.UNINDENT
.INDENT 7.0
.TP
.B extra_action(names, provider, action, **kwargs)
Perform actions with block storage devices
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
client.extra_action(names=[\(aqmyblock\(aq], action=\(aqvolume_create\(aq,
provider=\(aqmy\-nova\(aq, kwargs={\(aqvoltype\(aq: \(aqSSD\(aq, \(aqsize\(aq: 1000}
)
client.extra_action(names=[\(aqsalt\-net\(aq], action=\(aqnetwork_create\(aq,
provider=\(aqmy\-nova\(aq, kwargs={\(aqcidr\(aq: \(aq192.168.100.0/24\(aq}
)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B full_query(query_type=\(aqlist_nodes_full\(aq)
Query all instance information
.UNINDENT
.INDENT 7.0
.TP
.B list_images(provider=None)
List all available images in configured cloud systems
.UNINDENT
.INDENT 7.0
.TP
.B list_locations(provider=None)
List all available locations in configured cloud systems
.UNINDENT
.INDENT 7.0
.TP
.B list_sizes(provider=None)
List all available sizes in configured cloud systems
.UNINDENT
.INDENT 7.0
.TP
.B low(fun, low)
Pass the cloud function and low data structure to run
.UNINDENT
.INDENT 7.0
.TP
.B map_run(path, **kwargs)
Pass in a location for a map to execute
.UNINDENT
.INDENT 7.0
.TP
.B min_query(query_type=\(aqlist_nodes_min\(aq)
Query select instance information
.UNINDENT
.INDENT 7.0
.TP
.B profile(profile, names, vm_overrides=None, **kwargs)
Pass in a profile to create, names is a list of vm names to allocate
.INDENT 7.0
.INDENT 3.5
vm_overrides is a special dict that will be per node options
overrides
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> client= salt.cloud.CloudClient(path=\(aq/etc/salt/cloud\(aq)
>>> client.profile(\(aqdo_512_git\(aq, names=[\(aqminion01\(aq,])
{\(aqminion01\(aq: {u\(aqbackups_active\(aq: \(aqFalse\(aq,
u\(aqcreated_at\(aq: \(aq2014\-09\-04T18:10:15Z\(aq,
u\(aqdroplet\(aq: {u\(aqevent_id\(aq: 31000502,
u\(aqid\(aq: 2530006,
u\(aqimage_id\(aq: 5140006,
u\(aqname\(aq: u\(aqminion01\(aq,
u\(aqsize_id\(aq: 66},
u\(aqid\(aq: \(aq2530006\(aq,
u\(aqimage_id\(aq: \(aq5140006\(aq,
u\(aqip_address\(aq: \(aq107.XXX.XXX.XXX\(aq,
u\(aqlocked\(aq: \(aqTrue\(aq,
u\(aqname\(aq: \(aqminion01\(aq,
u\(aqprivate_ip_address\(aq: None,
u\(aqregion_id\(aq: \(aq4\(aq,
u\(aqsize_id\(aq: \(aq66\(aq,
u\(aqstatus\(aq: \(aqnew\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B query(query_type=\(aqlist_nodes\(aq)
Query basic instance information
.UNINDENT
.INDENT 7.0
.TP
.B select_query(query_type=\(aqlist_nodes_select\(aq)
Query select instance information
.UNINDENT
.UNINDENT
.SS Full list of Salt Cloud modules
.TS
center;
|l|l|.
_
T{
\fBaliyun\fP
T} T{
AliYun ECS Cloud Module
T}
_
T{
\fBbotocore_aws\fP
T} T{
The AWS Cloud Module
T}
_
T{
\fBcloudstack\fP
T} T{
CloudStack Cloud Module
T}
_
T{
\fBdigital_ocean\fP
T} T{
DigitalOcean Cloud Module
T}
_
T{
\fBec2\fP
T} T{
The EC2 Cloud Module
T}
_
T{
\fBgce\fP
T} T{
Copyright 2013 Google Inc.
T}
_
T{
\fBgogrid\fP
T} T{
GoGrid Cloud Module
T}
_
T{
\fBjoyent\fP
T} T{
Joyent Cloud Module
T}
_
T{
\fBlibcloud_aws\fP
T} T{
The AWS Cloud Module
T}
_
T{
\fBlinode\fP
T} T{
Linode Cloud Module
T}
_
T{
\fBlxc\fP
T} T{
Install Salt on an LXC Container
T}
_
T{
\fBmsazure\fP
T} T{
Azure Cloud Module
T}
_
T{
\fBnova\fP
T} T{
OpenStack Nova Cloud Module
T}
_
T{
\fBopennebula\fP
T} T{
OpenNebula Cloud Module
T}
_
T{
\fBopenstack\fP
T} T{
OpenStack Cloud Module
T}
_
T{
\fBparallels\fP
T} T{
Parallels Cloud Module
T}
_
T{
\fBproxmox\fP
T} T{
Proxmox Cloud Module
T}
_
T{
\fBrackspace\fP
T} T{
Rackspace Cloud Module
T}
_
T{
\fBsaltify\fP
T} T{
Saltify Module ============== The Saltify module is designed to install Salt on a remote machine, virtual or bare metal, using SSH.
T}
_
T{
\fBsoftlayer\fP
T} T{
SoftLayer Cloud Module
T}
_
T{
\fBsoftlayer_hw\fP
T} T{
SoftLayer HW Cloud Module
T}
_
T{
\fBvsphere\fP
T} T{
vSphere Cloud Module
T}
_
.TE
.SS salt.cloud.clouds.aliyun
.SS AliYun ECS Cloud Module
.sp
New in version 2014.7.0.
.sp
The Aliyun cloud module is used to control access to the aliyun ECS.
\fI\%http://www.aliyun.com/\fP
.sp
Use of this module requires the \fBid\fP and \fBkey\fP parameter to be set.
Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/aliyun.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-aliyun\-config:
# aliyun Access Key ID
id: wFGEwgregeqw3435gDger
# aliyun Access Key Secret
key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
location: cn\-qingdao
provider: aliyun
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B depends
requests
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.avail_images(kwargs=None, call=None)
Return a list of the images that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.avail_locations(call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.avail_sizes(call=None)
Return a list of the image sizes that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.create_node(kwargs)
Convenience function to make the rest api call for node creation.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.destroy(name, call=None)
Destroy a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a destroy myinstance
salt\-cloud \-d myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.get_image(vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.get_location(vm_=None)
.INDENT 7.0
.TP
.B Return the aliyun region to use, in this order:
.INDENT 7.0
.IP \(bu 2
CLI parameter
.IP \(bu 2
VM parameter
.IP \(bu 2
Cloud profile setting
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.get_securitygroup(vm_)
Return the security group
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.get_size(vm_)
Return the VM\(aqs size. Used by create_node().
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.list_availability_zones(call=None)
List all availability zones in the current region
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.list_monitor_data(kwargs=None, call=None)
Get monitor data of the instance. If instance name is
missing, will show all the instance monitor data on the region.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f list_monitor_data aliyun
salt\-cloud \-f list_monitor_data aliyun name=AY14051311071990225bd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.list_nodes(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.list_nodes_full(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.list_nodes_min(call=None)
Return a list of the VMs that are on the provider. Only a list of VM names,
and their state, is returned. This is the minimum amount of information
needed to check for existing VMs.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.list_securitygroup(call=None)
Return a list of security group
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.query(params=None)
Make a web call to aliyun ECS REST API
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.reboot(name, call=None)
Reboot a node
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a reboot myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.show_disk(name, call=None)
Show the disk details of the instance
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_disk aliyun myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.show_image(kwargs, call=None)
Show the details from aliyun image
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.show_instance(name, call=None)
Show the details from aliyun instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.start(name, call=None)
Start a node
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a start myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.aliyun.stop(name, force=False, call=None)
Stop a node
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a stop myinstance
salt\-cloud \-a stop myinstance force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.cloud.clouds.botocore_aws
.SS The AWS Cloud Module
.sp
The AWS cloud module is used to interact with the Amazon Web Services system.
.sp
This module has been replaced by the EC2 cloud module, and is no longer
supported. The documentation shown here is for reference only; it is highly
recommended to change all usages of this driver over to the EC2 driver.
.INDENT 0.0
.TP
.B If this driver is still needed, set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/aws.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-aws\-botocore\-config:
# The AWS API authentication id
id: GKTADJGHEIQSXMKKRBJ08H
# The AWS API authentication key
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# The ssh keyname to use
keyname: default
# The amazon security group
securitygroup: ssh_open
# The location of the private key which corresponds to the keyname
private_key: /root/default.pem
provider: aws
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.botocore_aws.disable_term_protect(name, call=None)
Disable termination protection on a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a disable_term_protect mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.botocore_aws.enable_term_protect(name, call=None)
Enable termination protection on a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a enable_term_protect mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.botocore_aws.get_configured_provider()
Return the first configured instance.
.UNINDENT
.SS salt.cloud.clouds.cloudstack
.SS CloudStack Cloud Module
.sp
The CloudStack cloud module is used to control access to a CloudStack based
Public Cloud.
.INDENT 0.0
.TP
.B depends
libcloud
.UNINDENT
.sp
Use of this module requires the \fBapikey\fP, \fBsecretkey\fP, \fBhost\fP and
\fBpath\fP parameters.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-cloudstack\-cloud\-config:
apikey: <your api key >
secretkey: <your secret key >
host: localhost
path: /client/api
provider: cloudstack
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.avail_locations(conn=None, call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.avail_sizes(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.destroy(name, conn=None, call=None)
Delete a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_image(conn, vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_ip(data)
Return the IP address of the VM
If the VM has public IP as defined by libcloud module then use it
Otherwise try to extract the private IP and use that one.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_key()
Returns the ssh private key for VM access
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_keypair(vm_)
Return the keypair to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_location(conn, vm_)
Return the node location to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_networkid(vm_)
Return the networkid to use, only valid for Advanced Zone
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_node(conn, name)
Return a libcloud node for the named VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_password(vm_)
Return the password to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.get_size(conn, vm_)
Return the VM\(aqs size object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.list_nodes(conn=None, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.list_nodes_full(conn=None, call=None)
Return a list of the VMs that are on the provider, with all fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.list_nodes_select(conn=None, call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.cloudstack.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.SS salt.cloud.clouds.digital_ocean
.SS DigitalOcean Cloud Module
.sp
The DigitalOcean cloud module is used to control access to the DigitalOcean
VPS system.
.sp
Use of this module only requires the \fBapi_key\fP parameter to be set. Set up the
cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/digital_ocean.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-digital\-ocean\-config:
# DigitalOcean account keys
client_key: wFGEwgregeqw3435gDger
api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
provider: digital_ocean
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B depends
requests
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.avail_images(call=None)
Return a list of the images that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.avail_locations(call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.avail_sizes(call=None)
Return a list of the image sizes that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.create_node(args)
Create a node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.destroy(name, call=None)
Destroy a node. Will check termination protection and warn if enabled.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.get_image(vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.get_keyid(keyname)
Return the ID of the keyname
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.get_location(vm_)
Return the VM\(aqs location
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.get_size(vm_)
Return the VM\(aqs size. Used by create_node().
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.list_keypairs(call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.list_nodes(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.list_nodes_full(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.query(method=\(aqdroplets\(aq, droplet_id=None, command=None, args=None)
Make a web call to DigitalOcean
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.show_instance(name, call=None)
Show the details from DigitalOcean concerning a droplet
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.digital_ocean.show_keypair(kwargs=None, call=None)
Show the details of an SSH keypair
.UNINDENT
.SS salt.cloud.clouds.ec2
.SS The EC2 Cloud Module
.sp
The EC2 cloud module is used to interact with the Amazon Elastic Cloud
Computing. This driver is highly experimental! Use at your own risk!
.INDENT 0.0
.TP
.B To use the EC2 cloud module, set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/ec2.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-config:
# The EC2 API authentication id
id: GKTADJGHEIQSXMKKRBJ08H
# The EC2 API authentication key
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# The ssh keyname to use
keyname: default
# The amazon security group
securitygroup: ssh_open
# The location of the private key which corresponds to the keyname
private_key: /root/default.pem
# Be default, service_url is set to amazonaws.com. If you are using this
# driver for something other than Amazon EC2, change it here:
service_url: amazonaws.com
# The endpoint that is ultimately used is usually formed using the region
# and the service_url. If you would like to override that entirely, you
# can explicitly define the endpoint:
endpoint: myendpoint.example.com:1138/services/Cloud
# SSH Gateways can be used with this provider. Gateways can be used
# when a salt\-master is not on the same private network as the instance
# that is being deployed.
# Defaults to None
# Required
ssh_gateway: gateway.example.com
# Defaults to port 22
# Optional
ssh_gateway_port: 22
# Defaults to root
# Optional
ssh_gateway_username: root
# One authentication method is required. If both
# are specified, Private key wins.
# Private key defaults to None
ssh_gateway_private_key: /path/to/key.pem
# Password defaults to None
ssh_gateway_password: ExamplePasswordHere
provider: ec2
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B depends
requests
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.attach_volume(name=None, kwargs=None, instance_id=None, call=None)
Attach a volume to an instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.avail_images(kwargs=None, call=None)
Return a dict of all available VM images on the cloud provider.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.avail_locations(call=None)
List all available locations
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.avail_sizes(call=None)
Return a dict of all available VM sizes on the cloud provider with
relevant data. Latest version can be found at:
.sp
\fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance\-types.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.block_device_mappings(vm_)
Return the block device mapping:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[{\(aqDeviceName\(aq: \(aq/dev/sdb\(aq, \(aqVirtualName\(aq: \(aqephemeral0\(aq},
{\(aqDeviceName\(aq: \(aq/dev/sdc\(aq, \(aqVirtualName\(aq: \(aqephemeral1\(aq}]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.copy_snapshot(kwargs=None, call=None)
Copy a snapshot
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.create(vm_=None, call=None)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.create_attach_volumes(name, kwargs, call=None, wait_to_finish=True)
Create and attach volumes to created node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.create_keypair(kwargs=None, call=None)
Create an SSH keypair
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.create_snapshot(kwargs=None, call=None, wait_to_finish=False)
Create a snapshot
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.create_volume(kwargs=None, call=None, wait_to_finish=False)
Create a volume
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.del_tags(name=None, kwargs=None, call=None, instance_id=None, resource_id=None)
Delete tags for a resource. Normally a VM name or instance_id is passed in,
but a resource_id may be passed instead. If both are passed in, the
instance_id will be used.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a del_tags mymachine tags=tag1,tag2,tag3
salt\-cloud \-a del_tags resource_id=vol\-3267ab32 tags=tag1,tag2,tag3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.delete_keypair(kwargs=None, call=None)
Delete an SSH keypair
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.delete_snapshot(kwargs=None, call=None)
Delete a snapshot
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.delete_volume(name=None, kwargs=None, instance_id=None, call=None)
Delete a volume
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.delvol_on_destroy(name, kwargs=None, call=None)
Delete all/specified EBS volumes upon instance termination
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a delvol_on_destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.describe_snapshots(kwargs=None, call=None)
Describe a snapshot (or snapshots)
.INDENT 7.0
.TP
.B snapshot_id
One or more snapshot IDs. Multiple IDs must be separated by ",".
.TP
.B owner
Return the snapshots owned by the specified owner. Valid values
include: self, amazon, <AWS Account ID>. Multiple values must be
separated by ",".
.TP
.B restorable_by
One or more AWS accounts IDs that can create volumes from the snapshot.
Multiple aws account IDs must be separated by ",".
.UNINDENT
.sp
TODO: Add all of the filters.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.describe_volumes(kwargs=None, call=None)
Describe a volume (or volumes)
.INDENT 7.0
.TP
.B volume_id
One or more volume IDs. Multiple IDs must be separated by ",".
.UNINDENT
.sp
TODO: Add all of the filters.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.destroy(name, call=None)
Destroy a node. Will check termination protection and warn if enabled.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.detach_volume(name=None, kwargs=None, instance_id=None, call=None)
Detach a volume from an instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.disable_term_protect(name, call=None)
Disable termination protection on a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a disable_term_protect mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.enable_term_protect(name, call=None)
Enable termination protection on a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a enable_term_protect mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_availability_zone(vm_)
Return the availability zone to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_console_output(name=None, instance_id=None, call=None, kwargs=None)
Show the console output from the instance.
.sp
By default, returns decoded data, not the Base64\-encoded data that is
actually returned from the EC2 API.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_location(vm_=None)
.INDENT 7.0
.TP
.B Return the EC2 region to use, in this order:
.INDENT 7.0
.IP \(bu 2
CLI parameter
.IP \(bu 2
VM parameter
.IP \(bu 2
Cloud profile setting
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_placementgroup(vm_)
Returns the PlacementGroup to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_spot_config(vm_)
Returns the spot instance configuration for the provided vm
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_ssh_gateway_config(vm_)
Return the ssh_gateway configuration.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_subnetid(vm_)
Returns the SubnetId to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_tags(name=None, instance_id=None, call=None, location=None, kwargs=None, resource_id=None)
Retrieve tags for a resource. Normally a VM name or instance_id is passed
in, but a resource_id may be passed instead. If both are passed in, the
instance_id will be used.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a get_tags mymachine
salt\-cloud \-a get_tags resource_id=vol\-3267ab32
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.get_tenancy(vm_)
Returns the Tenancy to use.
.sp
Can be "dedicated" or "default". Cannot be present for spot instances.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.iam_profile(vm_)
Return the IAM profile.
.sp
The IAM instance profile to associate with the instances.
This is either the Amazon Resource Name (ARN) of the instance profile
or the name of the role.
.sp
Type: String
.sp
Default: None
.sp
Required: No
.sp
Example: arn:aws:iam::111111111111:instance\-profile/s3access
.sp
Example: s3access
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.keepvol_on_destroy(name, kwargs=None, call=None)
Do not delete all/specified EBS volumes upon instance termination
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a keepvol_on_destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.keyname(vm_)
Return the keyname
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.list_availability_zones()
List all availability zones in the current region
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.list_nodes(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.list_nodes_full(location=None, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.list_nodes_min(location=None, call=None)
Return a list of the VMs that are on the provider. Only a list of VM names,
and their state, is returned. This is the minimum amount of information
needed to check for existing VMs.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.optimize_providers(providers)
Return an optimized list of providers.
.sp
We want to reduce the duplication of querying
the same region.
.sp
If a provider is using the same credentials for the same region
the same data will be returned for each provider, thus causing
un\-wanted duplicate data and API calls to EC2.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.query(params=None, setname=None, requesturl=None, location=None, return_url=False, return_root=False)
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.query_instance(vm_=None, call=None)
Query an instance upon creation from the EC2 API
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.queue_instances(instances)
Queue a set of instances to be provisioned later. Expects a list.
.sp
Currently this only queries node data, and then places it in the cloud
cache (if configured). If the salt\-cloud\-reactor is being used, these
instances will be automatically provisioned using that.
.sp
For more information about the salt\-cloud\-reactor, see:
.sp
\fI\%https://github.com/saltstack\-formulas/salt\-cloud\-reactor\fP
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.reboot(name, call=None)
Reboot a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a reboot mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.rename(name, kwargs, call=None)
Properly rename a node. Pass in the new name as "new name".
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a rename mymachine newname=yourmachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.request_instance(vm_=None, call=None)
Put together all of the information necessary to request an instance on EC2,
and then fire off the request the instance.
.sp
Returns data about the instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.securitygroup(vm_)
Return the security group
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.securitygroupid(vm_)
Returns the SecurityGroupId
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.set_tags(name=None, tags=None, call=None, location=None, instance_id=None, resource_id=None, kwargs=None)
Set tags for a resource. Normally a VM name or instance_id is passed in,
but a resource_id may be passed instead. If both are passed in, the
instance_id will be used.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a set_tags mymachine tag1=somestuff tag2=\(aqOther stuff\(aq
salt\-cloud \-a set_tags resource_id=vol\-3267ab32 tag=somestuff
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.show_delvol_on_destroy(name, kwargs=None, call=None)
Do not delete all/specified EBS volumes upon instance termination
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_delvol_on_destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.show_image(kwargs, call=None)
Show the details from EC2 concerning an AMI
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.show_instance(name=None, instance_id=None, call=None, kwargs=None)
Show the details from EC2 concerning an AMI.
.sp
Can be called as an action (which requires a name):
.INDENT 7.0
.INDENT 3.5
salt\-cloud \-a show_instance myinstance
.UNINDENT
.UNINDENT
.sp
\&...or as a function (which requires either a name or instance_id):
.INDENT 7.0
.INDENT 3.5
salt\-cloud \-f show_instance my\-ec2 name=myinstance
salt\-cloud \-f show_instance my\-ec2 instance_id=i\-d34db33f
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.show_keypair(kwargs=None, call=None)
Show the details of an SSH keypair
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.show_term_protect(name=None, instance_id=None, call=None, quiet=False)
Show the details from EC2 concerning an AMI
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.show_volume(kwargs=None, call=None)
Wrapper around describe_volumes.
Here just to keep functionality.
Might be depreciated later.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.ssh_interface(vm_)
Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default)
or \(aqprivate_ips\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.start(name, call=None)
Start a node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.stop(name, call=None)
Stop a node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.ec2.wait_for_instance(vm_=None, data=None, ip_address=None, display_ssh_output=True, call=None)
Wait for an instance upon creation from the EC2 API, to become available
.UNINDENT
.SS salt.cloud.clouds.gce
.sp
Copyright 2013 Google Inc. All Rights Reserved.
.sp
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
.INDENT 0.0
.INDENT 3.5
\fI\%http://www.apache.org/licenses/LICENSE\-2.0\fP
.UNINDENT
.UNINDENT
.sp
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.SS Google Compute Engine Module
.sp
The Google Compute Engine module. This module interfaces with Google Compute
Engine. To authenticate to GCE, you will need to create a Service Account.
.INDENT 0.0
.TP
.B Setting up Service Account Authentication:
.INDENT 7.0
.IP \(bu 2
Go to the Cloud Console at: \fI\%https://cloud.google.com/console\fP\&.
.IP \(bu 2
Create or navigate to your desired Project.
.IP \(bu 2
Make sure Google Compute Engine service is enabled under the Services
section.
.IP \(bu 2
Go to "APIs and auth" and then the "Registered apps" section.
.IP \(bu 2
Click the "REGISTER APP" button and give it a meaningful name.
.IP \(bu 2
Select "Web Application" and click "Register".
.IP \(bu 2
Select Certificate, then "Generate Certificate"
.IP \(bu 2
Copy the Email Address for inclusion in your /etc/salt/cloud file
in the \(aqservice_account_email_address\(aq setting.
.IP \(bu 2
Download the Private Key
.IP \(bu 2
The key that you download is a PKCS12 key. It needs to be converted to
the PEM format.
.IP \(bu 2
Convert the key using OpenSSL (the default password is \(aqnotasecret\(aq):
C{openssl pkcs12 \-in PRIVKEY.p12 \-passin pass:notasecret \-nodes \-nocerts | openssl rsa \-out ~/PRIVKEY.pem}
.IP \(bu 2
Add the full path name of the converted private key to your
/etc/salt/cloud file as \(aqservice_account_private_key\(aq setting.
.IP \(bu 2
Consider using a more secure location for your private key.
.UNINDENT
.TP
.B Supported commands:
# Create a few instances fro profile_name in /etc/salt/cloud.profiles
\- salt\-cloud \-p profile_name inst1 inst2 inst3
# Delete an instance
\- salt\-cloud \-d inst1
# Look up data on an instance
\- salt\-cloud \-a show_instance inst2
# List available locations (aka \(aqzones\(aq) for provider \(aqgce\(aq
\- salt\-cloud \-\-list\-locations gce
# List available instance sizes (aka \(aqmachine types\(aq) for provider \(aqgce\(aq
\- salt\-cloud \-\-list\-sizes gce
# List available images for provider \(aqgce\(aq
\- salt\-cloud \-\-list\-images gce
# Create a persistent disk
\- salt\-cloud \-f create_disk gce disk_name=pd location=us\-central1\-b ima...
# Permanently delete a persistent disk
\- salt\-cloud \-f delete_disk gce disk_name=pd
# Attach an existing disk to an existing instance
\- salt\-cloud \-a attach_disk myinstance disk_name=mydisk mode=READ_ONLY
# Detach a disk from an instance
\- salt\-cloud \-a detach_disk myinstance disk_name=mydisk
# Show information about the named disk
\- salt\-cloud \-a show_disk myinstance disk_name=pd
\- salt\-cloud \-f show_disk gce disk_name=pd
# Create a snapshot of a persistent disk
\- salt\-cloud \-f create_snapshot gce name=snap\-1 disk_name=pd
# Permanently delete a disk snapshot
\- salt\-cloud \-f delete_snapshot gce name=snap\-1
# Show information about the named snapshot
\- salt\-cloud \-f show_snapshot gce name=snap\-1
# Create a network
\- salt\-cloud \-f create_network gce name=mynet cidr=10.10.10.0/24
# Delete a network
\- salt\-cloud \-f delete_network gce name=mynet
# Show info for a network
\- salt\-cloud \-f show_network gce name=mynet
# Create a firewall rule
\- salt\-cloud \-f create_fwrule gce name=fw1 network=mynet allow=tcp:80
# Delete a firewall rule
\- salt\-cloud \-f delete_fwrule gce name=fw1
# Show info for a firewall rule
\-salt\-cloud \-f show_fwrule gce name=fw1
# Create a load\-balancer HTTP health check
\- salt\-cloud \-f create_hc gce name=hc path=/ port=80
# Delete a load\-balancer HTTP health check
\- salt\-cloud \-f delete_hc gce name=hc
# Show info about an HTTP health check
\- salt\-cloud \-f show_hc gce name=hc
# Create a load\-balancer configuration
\- salt\-cloud \-f create_lb gce name=lb region=us\-central1 ports=80 ...
# Delete a load\-balancer configuration
\- salt\-cloud \-f delete_lb gce name=lb
# Show details about load\-balancer
\- salt\-cloud \-f show_lb gce name=lb
# Add member to load\-balancer
\- salt\-cloud \-f attach_lb gce name=lb member=www1
# Remove member from load\-balancer
\- salt\-cloud \-f detach_lb gce name=lb member=www1
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-gce\-config:
# The Google Cloud Platform Project ID
project: google.com:erjohnso
# The Service ACcount client ID
service_account_email_address: 1234567890@developer.gserviceaccount.com
# The location of the private key (PEM format)
service_account_private_key: /home/erjohnso/PRIVKEY.pem
provider: gce
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B maintainer
Eric Johnson <\fI\%erjohnso@google.com\fP>
.TP
.B maturity
new
.TP
.B depends
libcloud >= 0.14.1
.TP
.B depends
pycrypto >= 2.1
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.attach_disk(name=None, kwargs=None, call=None)
Attach an existing disk to an existing instance.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a attach_disk myinstance disk_name=mydisk mode=READ_WRITE
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.attach_lb(kwargs=None, call=None)
Add an existing node/member to an existing load\-balancer configuration.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f attach_lb gce name=lb member=myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.avail_images(conn=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.sp
Note that for GCE, there are custom images within the project, but the
generic images are in other projects. This returns a dict of images in
the project plus images in \(aqdebian\-cloud\(aq and \(aqcentos\-cloud\(aq (If there is
overlap in names, the one in the current project is used.)
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.avail_locations(conn=None, call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.avail_sizes(conn=None)
Return a dict of available instances sizes (a.k.a machine types) and
convert them to something more serializable.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.create(vm_=None, call=None)
Create a single GCE instance from a data dict.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.create_disk(kwargs=None, call=None)
Create a new persistent disk. Must specify \fIdisk_name\fP and \fIlocation\fP\&.
Can also specify an \fIimage\fP or \fIsnapshot\fP but if neither of those are
specified, a \fIsize\fP (in GB) is required.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_disk gce disk_name=pd size=300 location=us\-central1\-b
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.create_fwrule(kwargs=None, call=None)
Create a GCE firewall rule. The \(aqdefault\(aq network is used if not specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_fwrule gce name=allow\-http allow=tcp:80
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.create_hc(kwargs=None, call=None)
Create an HTTP health check configuration.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_hc gce name=hc path=/healthy port=80
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.create_lb(kwargs=None, call=None)
Create a load\-balancer configuration.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_lb gce name=lb region=us\-central1 ports=80
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.create_network(kwargs=None, call=None)
Create a GCE network.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_network gce name=mynet cidr=10.10.10.0/24
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.create_snapshot(kwargs=None, call=None)
Create a new disk snapshot. Must specify \fIname\fP and \fIdisk_name\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f create_snapshot gce name=snap1 disk_name=pd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.delete_disk(kwargs=None, call=None)
Permanently delete a persistent disk.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_disk gce disk_name=pd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.delete_fwrule(kwargs=None, call=None)
Permanently delete a firewall rule.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_fwrule gce name=allow\-http
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.delete_hc(kwargs=None, call=None)
Permanently delete a health check.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_hc gce name=hc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.delete_lb(kwargs=None, call=None)
Permanently delete a load\-balancer.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_lb gce name=lb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.delete_network(kwargs=None, call=None)
Permanently delete a network.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_network gce name=mynet
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.delete_snapshot(kwargs=None, call=None)
Permanently delete a disk snapshot.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_snapshot gce name=disk\-snap\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.destroy(vm_name, call=None)
Call \(aqdestroy\(aq on the instance. Can be called with "\-a destroy" or \-d
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a destroy myinstance1 myinstance2 ...
salt\-cloud \-d myinstance1 myinstance2 ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.detach_disk(name=None, kwargs=None, call=None)
Detach a disk from an instance.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a detach_disk myinstance disk_name=mydisk
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.detach_lb(kwargs=None, call=None)
Remove an existing node/member from an existing load\-balancer configuration.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f detach_lb gce name=lb member=myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.get_lb_conn(gce_driver=None)
Return a load\-balancer conn object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.list_nodes(conn=None, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.list_nodes_full(conn=None, call=None)
Return a list of the VMs that are on the provider, with all fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.list_nodes_select(conn=None, call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.reboot(vm_name, call=None)
Call GCE \(aqreset\(aq on the instance.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a reboot myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.show_disk(name=None, kwargs=None, call=None)
Show the details of an existing disk.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a show_disk myinstance disk_name=mydisk
salt\-cloud \-f show_disk gce disk_name=mydisk
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.show_fwrule(kwargs=None, call=None)
Show the details of an existing firewall rule.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_fwrule gce name=allow\-http
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.show_hc(kwargs=None, call=None)
Show the details of an existing health check.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_hc gce name=hc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.show_instance(vm_name, call=None)
Show the details of the existing instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.show_lb(kwargs=None, call=None)
Show the details of an existing load\-balancer.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_lb gce name=lb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.show_network(kwargs=None, call=None)
Show the details of an existing network.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_network gce name=mynet
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gce.show_snapshot(kwargs=None, call=None)
Show the details of an existing snapshot.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f show_snapshot gce name=mysnapshot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.cloud.clouds.gogrid
.SS GoGrid Cloud Module
.sp
The GoGrid cloud module. This module interfaces with the gogrid public cloud
service. To use Salt Cloud with GoGrid log into the GoGrid web interface and
create an api key. Do this by clicking on "My Account" and then going to the
API Keys tab.
.INDENT 0.0
.TP
.B depends
libcloud >= 0.13.2
.UNINDENT
.sp
Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/gogrid.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-gogrid\-config:
# The generated api key to use
apikey: asdff7896asdh789
# The apikey\(aqs shared secret
sharedsecret: saltybacon
provider: gogrid
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.avail_sizes(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.destroy(name, conn=None, call=None)
Delete a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.get_image(conn, vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.get_size(conn, vm_)
Return the VM\(aqs size object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.list_nodes(conn=None, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.list_nodes_full(conn=None, call=None)
Return a list of the VMs that are on the provider, with all fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.list_nodes_select(conn=None, call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.gogrid.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.SS salt.cloud.clouds.joyent
.SS Joyent Cloud Module
.sp
The Joyent Cloud module is used to interact with the Joyent cloud system.
.sp
Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/joyent.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-joyent\-config:
# The Joyent login user
user: fred
# The Joyent user\(aqs password
password: saltybacon
# The location of the ssh private key that can log into the new VM
private_key: /root/joyent.pem
provider: joyent
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When creating your profiles for the joyent cloud, add the location attribute to
the profile, this will automatically get picked up when performing tasks
associated with that vm. An example profile might look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
joyent_512:
provider: my\-joyent\-config
size: Extra Small 512 MB
image: centos\-6
location: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B depends
requests
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.avail_images(call=None)
get list of available images
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-images
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.avail_locations(call=None)
List all available locations
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.avail_sizes(call=None)
get list of available packages
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-sizes
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.create(vm_)
Create a single VM from a data dict
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p profile_name vm_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.create_node(**kwargs)
convenience function to make the rest api call for node creation.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.delete_key(kwargs=None, call=None)
List the keys available
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f delete_key joyent keyname=mykey
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.destroy(name, call=None)
destroy a machine by name
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- name given to the machine
.IP \(bu 2
\fBcall\fP \-\- call value in this case is \(aqaction\(aq
.UNINDENT
.TP
.B Returns
array of booleans , true if successfully stopped and true if
successfully removed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-d vm_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.get_image(vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.get_location(vm_=None)
.INDENT 7.0
.TP
.B Return the joyent data center to use, in this order:
.INDENT 7.0
.IP \(bu 2
CLI parameter
.IP \(bu 2
VM parameter
.IP \(bu 2
Cloud profile setting
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.get_location_path(location=\(aqus\-east\-1\(aq)
create url from location variable
:param location: joyent data center location
:return: url
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.get_node(name)
gets the node from the full node list by name
:param name: name of the vm
:return: node object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.get_size(vm_)
Return the VM\(aqs size object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.has_method(obj, method_name)
Find if the provided object has a specific method
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.import_key(kwargs=None, call=None)
List the keys available
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f import_key joyent keyname=mykey keyfile=/tmp/mykey.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.joyent_node_state(id_)
Convert joyent returned state to state common to other data center return
values for consistency
.INDENT 7.0
.TP
.B Parameters
\fBid\fP \-\- joyent state value
.TP
.B Returns
libcloudfuncs state value
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.key_list(key=\(aqname\(aq, items=None)
convert list to dictionary using the key as the identifier
:param key: identifier \- must exist in the arrays elements own dictionary
:param items: array to iterate over
:return: dictionary
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.list_keys(kwargs=None, call=None)
List the keys available
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.list_nodes(full=False, call=None)
list of nodes, keeping only a brief listing
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-Q
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.list_nodes_full(call=None)
list of nodes, maintaining all content provided from joyent listings
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-F
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.query(action=None, command=None, args=None, method=\(aqGET\(aq, location=None, data=None)
Make a web call to Joyent
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.reboot(name, call=None)
reboot a machine by name
:param name: name given to the machine
:param call: call value in this case is \(aqaction\(aq
:return: true if successful
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a reboot vm_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.reformat_node(item=None, full=False)
Reformat the returned data from joyent, determine public/private IPs and
strip out fields if necessary to provide either full or brief content.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBitem\fP \-\- node dictionary
.IP \(bu 2
\fBfull\fP \-\- full or brief output
.UNINDENT
.TP
.B Returns
dict
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.show_key(kwargs=None, call=None)
List the keys available
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.ssh_interface(vm_)
Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default)
or \(aqprivate_ips\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.start(name, call=None)
start a machine by name
:param name: name given to the machine
:param call: call value in this case is \(aqaction\(aq
:return: true if successful
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a start vm_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.stop(name, call=None)
stop a machine by name
:param name: name given to the machine
:param call: call value in this case is \(aqaction\(aq
:return: true if successful
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a stop vm_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.joyent.take_action(name=None, call=None, command=None, data=None, method=\(aqGET\(aq, location=\(aqus\-east\-1\(aq)
take action call used by start,stop, reboot
:param name: name given to the machine
:param call: call value in this case is \(aqaction\(aq
:command: api path
:data: any data to be passed to the api, must be in json format
:method: GET,POST,or DELETE
:location: data center to execute the command on
:return: true if successful
.UNINDENT
.SS salt.cloud.clouds.libcloud_aws
.SS The AWS Cloud Module
.sp
The AWS cloud module is used to interact with the Amazon Web Services system.
.sp
This module has been replaced by the EC2 cloud module, and is no longer
supported. The documentation shown here is for reference only; it is highly
recommended to change all usages of this driver over to the EC2 driver.
.INDENT 0.0
.TP
.B If this driver is still needed, set up the cloud configuration at
\fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/aws.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-aws\-config:
# The AWS API authentication id
id: GKTADJGHEIQSXMKKRBJ08H
# The AWS API authentication key
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# The ssh keyname to use
keyname: default
# The amazon security group
securitygroup: ssh_open
# The location of the private key which corresponds to the keyname
private_key: /root/default.pem
provider: aws
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.block_device_mappings(vm_)
Return the block device mapping:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[{\(aqDeviceName\(aq: \(aq/dev/sdb\(aq, \(aqVirtualName\(aq: \(aqephemeral0\(aq},
{\(aqDeviceName\(aq: \(aq/dev/sdc\(aq, \(aqVirtualName\(aq: \(aqephemeral1\(aq}]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.create_attach_volumes(volumes, location, data)
Create and attach volumes to created node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.del_tags(name, kwargs, call=None)
Delete tags for a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a del_tags mymachine tag1,tag2,tag3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.destroy(name)
Wrap core libcloudfuncs destroy method, adding check for termination
protection
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.get_availability_zone(conn, vm_)
Return the availability zone to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.get_conn(**kwargs)
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.get_location(vm_=None)
.INDENT 7.0
.TP
.B Return the AWS region to use, in this order:
.INDENT 7.0
.IP \(bu 2
CLI parameter
.IP \(bu 2
Cloud profile setting
.IP \(bu 2
Global salt\-cloud config
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.get_tags(name, call=None)
Retrieve tags for a node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.iam_profile(vm_)
Return the IAM role
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.keyname(vm_)
Return the keyname
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.rename(name, kwargs, call=None)
Properly rename a node. Pass in the new name as "new name".
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a rename mymachine newname=yourmachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.securitygroup(vm_)
Return the security group
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.set_tags(name, tags, call=None)
Set tags for a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a set_tags mymachine tag1=somestuff tag2=\(aqOther stuff\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.ssh_interface(vm_)
Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default)
or \(aqprivate_ips\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.ssh_username(vm_)
Return the ssh_username. Defaults to \(aqec2\-user\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.start(name, call=None)
Start a node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.libcloud_aws.stop(name, call=None)
Stop a node
.UNINDENT
.SS salt.cloud.clouds.linode
.SS Linode Cloud Module
.sp
The Linode cloud module is used to control access to the Linode VPS system
.sp
Use of this module only requires the \fBapikey\fP parameter.
.INDENT 0.0
.TP
.B depends
libcloud >= 0.13.2
.UNINDENT
.sp
Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/linode.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-linode\-config:
# Linode account api key
apikey: JVkbSJDGHSDKUKSDJfhsdklfjgsjdkflhjlsdfffhgdgjkenrtuinv
provider: linode
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.avail_locations(conn=None, call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.avail_sizes(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.destroy(name, conn=None, call=None)
Delete a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_disk_size(vm_, size, swap)
Return the size of of the root disk in MB
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_image(conn, vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_location(conn, vm_)
Return the node location to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_node(conn, name)
Return a libcloud node for the named VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_password(vm_)
Return the password to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_private_ip(vm_)
Return True if a private ip address is requested
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_size(conn, vm_)
Return the VM\(aqs size object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.get_swap(vm_)
Return the amount of swap space to use in MB
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.list_nodes(conn=None, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.list_nodes_full(conn=None, call=None)
Return a list of the VMs that are on the provider, with all fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.list_nodes_select(conn=None, call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.linode.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.SS salt.cloud.clouds.lxc
.SS Install Salt on an LXC Container
.sp
New in version 2014.7.0.
.sp
Please read \fIcore config documentation\fP\&.
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.avail_images()
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.create(vm_, call=None)
Create an lxc Container.
This function is idempotent and will try to either provision
or finish the provision of an lxc container.
.sp
NOTE: Most of the initialization code has been moved and merged
with the lxc runner and lxc.init functions
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.destroy(vm_, call=None)
Destroy a lxc container
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.get_configured_provider(vm_=None)
Return the contextual provider of None if no configured
one can be found.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.get_provider(name)
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.list_nodes(conn=None, call=None)
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.list_nodes_full(conn=None, call=None)
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.lxc.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.SS salt.cloud.clouds.msazure
.SS Azure Cloud Module
.sp
The Azure cloud module is used to control access to Microsoft Azure
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
\fI\%Microsoft Azure SDK for Python\fP
.UNINDENT
.TP
.B configuration
Required provider parameters:
.INDENT 7.0
.IP \(bu 2
\fBapikey\fP
.IP \(bu 2
\fBcertificate_path\fP
.IP \(bu 2
\fBsubscription_id\fP
.UNINDENT
.sp
A Management Certificate (.pem and .crt files) must be created and the .pem
file placed on the same machine that salt\-cloud is run from. Information on
creating the pem file to use, and uploading the associated cer file can be
found at:
.sp
\fI\%http://www.windowsazure.com/en\-us/develop/python/how\-to\-guides/service\-management/\fP
.UNINDENT
.sp
Example \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/azure.conf\fP configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-azure\-config:
provider: azure
subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617
certificate_path: /etc/salt/azure.pem
management_host: management.core.windows.net
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.avail_images(conn=None, call=None)
List available images for Azure
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.avail_locations(conn=None, call=None)
List available locations for Azure
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.avail_sizes(call=None)
Because sizes are built into images with Azure, there will be no sizes to
return here
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.destroy(name, conn=None, call=None, kwargs=None)
Destroy a VM
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-d myminion
salt\-cloud \-a destroy myminion service_name=myservice
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.list_disks(conn=None, call=None)
Destroy a VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.list_hosted_services(conn=None, call=None)
List VMs on this Azure account, with full information
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.list_nodes(conn=None, call=None)
List VMs on this Azure account
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.list_nodes_full(conn=None, call=None)
List VMs on this Azure account, with full information
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.list_nodes_select(conn=None, call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.list_storage_services(conn=None, call=None)
List VMs on this Azure account, with full information
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.msazure.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.SS salt.cloud.clouds.nova
.SS OpenStack Nova Cloud Module
.sp
PLEASE NOTE: This module is currently in early development, and considered to
be experimental and unstable. It is not recommended for production use. Unless
you are actively developing code in this module, you should use the OpenStack
module instead.
.sp
OpenStack is an open source project that is in use by a number a cloud
providers, each of which have their own ways of using it.
.sp
The OpenStack Nova module for Salt Cloud was bootstrapped from the OpenStack
module for Salt Cloud, which uses a libcloud\-based connection. The Nova module
is designed to use the nova and glance modules already built into Salt.
.sp
These modules use the Python novaclient and glanceclient libraries,
respectively. In order to use this module, the proper salt configuration must
also be in place. This can be specified in the master config, the minion
config, a set of grains or a set of pillars.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_openstack_profile:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that there is currently a dependency upon netaddr. This can be installed
on Debian\-based systems by means of the python\-netaddr package.
.sp
This module currently requires the latest develop branch of Salt to be
installed.
.sp
This module has been tested to work with HP Cloud and Rackspace. See the
documentation for specific options for either of these providers. These
examples could be set up in the cloud configuration at
\fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/openstack.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
# The ID of the minion that will execute the salt nova functions
auth_minion: myminion
# The name of the configuration profile to use on said minion
config_profile: my_openstack_profile
ssh_key_name: mykey
provider: nova
userdata_file: /tmp/userdata.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For local installations that only use private IP address ranges, the
following option may be useful. Using the old syntax:
.sp
Note: For api use, you will need an auth plugin. The base novaclient does not
support apikeys, but some providers such as rackspace have extended keystone to
accept them
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
# Ignore IP addresses on this network for bootstrap
ignore_cidr: 192.168.50.0/24
my\-nova:
identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/\(aq
compute_region: IAD
user: myusername
password: mypassword
tenant: <userid>
provider: nova
my\-api:
identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/\(aq
compute_region: IAD
user: myusername
api_key: <api_key>
os_auth_plugin: rackspace
tenant: <userid>
provider: nova
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.avail_images()
Return a dict of all available VM images on the cloud provider.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.avail_locations(conn=None, call=None)
Return a list of locations
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.avail_sizes()
Return a dict of all available VM sizes on the cloud provider.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.destroy(name, conn=None, call=None)
Delete a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.get_image(conn, vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.get_size(conn, vm_)
Return the VM\(aqs size object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.ignore_cidr(vm_, ip)
Return True if we are to ignore the specified IP. Compatible with IPv4.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.list_nodes(call=None, **kwargs)
Return a list of the VMs that in this location
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.list_nodes_full(call=None, **kwargs)
Return a list of the VMs that in this location
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.managedcloud(vm_)
Determine if we should wait for the managed cloud automation before
running. Either \(aqFalse\(aq (default) or \(aqTrue\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.network_create(name, **kwargs)
Create private networks
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.network_list(call=None, **kwargs)
List private networks
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.preferred_ip(vm_, ips)
Return the preferred Internet protocol. Either \(aqipv4\(aq (default) or \(aqipv6\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.rackconnect(vm_)
Determine if we should wait for rackconnect automation before running.
Either \(aqFalse\(aq (default) or \(aqTrue\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.reboot(name, conn=None)
Reboot a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.request_instance(vm_=None, call=None)
Put together all of the information necessary to request an instance
through Novaclient and then fire off the request the instance.
.sp
Returns data about the instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.ssh_interface(vm_)
Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default)
or \(aqprivate_ips\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.virtual_interface_create(name, net_name, **kwargs)
Create private networks
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.virtual_interface_list(name, **kwargs)
Create private networks
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.volume_attach(name, server_name, device=\(aq/dev/xvdb\(aq, **kwargs)
Attach block volume
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.volume_create(name, size=100, snapshot=None, voltype=None, **kwargs)
Create block storage device
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.volume_delete(name, **kwargs)
Delete block storage device
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.volume_detach(name, **kwargs)
Detach block volume
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.nova.volume_list(**kwargs)
List block devices
.UNINDENT
.SS salt.cloud.clouds.opennebula
.SS OpenNebula Cloud Module
.sp
The OpenNebula cloud module is used to control access to an OpenNebula
cloud.
.sp
Use of this module requires the \fBxml_rpc\fP, \fBuser\fP and
\fBpassword\fP parameter to be set. Set up the cloud configuration
at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/opennebula.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-opennebula\-config:
xml_rpc: http://localhost:2633/RPC2
user: oneadmin
password: JHGhgsayu32jsa
provider: opennebula
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.avail_images(call=None)
Return a list of the templates that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.avail_locations(call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.avail_sizes(call=None)
Because sizes are built into templates with OpenNebula, there will be no sizes to
return here
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.destroy(name, call=None)
Destroy a node. Will check termination protection and warn if enabled.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.get_image(vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.get_location(vm_)
Return the VM\(aqs location
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.list_nodes(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.list_nodes_full(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.opennebula.show_instance(name, call=None)
Show the details from OpenNebula concerning a VM
.UNINDENT
.SS salt.cloud.clouds.openstack
.SS OpenStack Cloud Module
.sp
OpenStack is an open source project that is in use by a number a cloud
providers, each of which have their own ways of using it.
.INDENT 0.0
.TP
.B depends
libcloud >\- 0.13.2
.UNINDENT
.sp
OpenStack provides a number of ways to authenticate. This module uses password\-
based authentication, using auth v2.0. It is likely to start supporting other
methods of authentication provided by OpenStack in the future.
.sp
Note that there is currently a dependency upon netaddr. This can be installed
on Debian\-based systems by means of the python\-netaddr package.
.sp
This module has been tested to work with HP Cloud and Rackspace. See the
documentation for specific options for either of these providers. Some
examples, using the old cloud configuration syntax, are provided below:
.sp
Set up in the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/openstack.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
# The OpenStack identity service url
identity_url: https://region\-b.geo\-1.identity.hpcloudsvc.com:35357/v2.0/
# The OpenStack compute region
compute_region: region\-b.geo\-1
# The OpenStack compute service name
compute_name: Compute
# The OpenStack tenant name (not tenant ID)
tenant: myuser\-tenant1
# The OpenStack user name
user: myuser
# The OpenStack keypair name
ssh_key_name: mykey
# Skip SSL certificate validation
insecure: false
# The ssh key file
ssh_key_file: /path/to/keyfile/test.pem
# The OpenStack network UUIDs
networks:
\- fixed:
\- 4402cd51\-37ee\-435e\-a966\-8245956dc0e6
\- floating:
\- Ext\-Net
files:
/path/to/dest.txt:
/local/path/to/src.txt
# Skips the service catalog API endpoint, and uses the following
base_url: http://192.168.1.101:3000/v2/12345
provider: openstack
userdata_file: /tmp/userdata.txt
# config_drive is required for userdata at rackspace
config_drive: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For in\-house Openstack Essex installation, libcloud needs the service_type :
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
identity_url: \(aqhttp://control.openstack.example.org:5000/v2.0/\(aq
compute_name : Compute Service
service_type : compute
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Either a password or an API key must also be specified:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-password\-or\-api\-config:
# The OpenStack password
password: letmein
# The OpenStack API key
apikey: 901d3f579h23c8v73q9
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Optionally, if you don\(aqt want to save plain\-text password in your configuration file, you can use keyring:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-keyring\-config:
# The OpenStack password is stored in keyring
# don\(aqt forget to set the password by running something like:
# salt\-cloud \-\-set\-password=myuser my\-openstack\-keyring\-config
password: USE_KEYRING
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For local installations that only use private IP address ranges, the
following option may be useful. Using the old syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
# Ignore IP addresses on this network for bootstrap
ignore_cidr: 192.168.50.0/24
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is possible to upload a small set of files (no more than 5, and nothing too
large) to the remote server. Generally this should not be needed, as salt
itself can upload to the server after it is spun up, with nowhere near the
same restrictions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
files:
/path/to/dest.txt:
/local/path/to/src.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, one could use the private IP to connect by specifying:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-openstack\-config:
ssh_interface: private_ips
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.avail_locations(conn=None, call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.avail_sizes(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.destroy(name, conn=None, call=None)
Delete a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.get_image(conn, vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.get_node(conn, name)
Return a libcloud node for the named VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.get_size(conn, vm_)
Return the VM\(aqs size object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.ignore_cidr(vm_, ip)
Return True if we are to ignore the specified IP. Compatible with IPv4.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.list_nodes(conn=None, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.list_nodes_full(conn=None, call=None)
Return a list of the VMs that are on the provider, with all fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.list_nodes_select(conn=None, call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.managedcloud(vm_)
Determine if we should wait for the managed cloud automation before
running. Either \(aqFalse\(aq (default) or \(aqTrue\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.preferred_ip(vm_, ips)
Return the preferred Internet protocol. Either \(aqipv4\(aq (default) or \(aqipv6\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.rackconnect(vm_)
Determine if we should wait for rackconnect automation before running.
Either \(aqFalse\(aq (default) or \(aqTrue\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.reboot(name, conn=None)
Reboot a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.request_instance(vm_=None, call=None)
Put together all of the information necessary to request an instance on Openstack
and then fire off the request the instance.
.sp
Returns data about the instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.openstack.ssh_interface(vm_)
Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default)
or \(aqprivate_ips\(aq.
.UNINDENT
.SS salt.cloud.clouds.parallels
.SS Parallels Cloud Module
.sp
The Parallels cloud module is used to control access to cloud providers using
the Parallels VPS system.
.INDENT 0.0
.TP
.B Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/parallels.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-parallels\-config:
# Parallels account information
user: myuser
password: mypassword
url: https://api.cloud.xmission.com:4465/paci/v1.0/
provider: parallels
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.avail_images(call=None)
Return a list of the images that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.create_node(vm_)
Build and submit the XML to create a node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.destroy(name, call=None)
Destroy a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.get_image(vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.list_nodes(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.list_nodes_full(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.query(action=None, command=None, args=None, method=\(aqGET\(aq, data=None)
Make a web call to a Parallels provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.show_image(kwargs, call=None)
Show the details from Parallels concerning an image
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.show_instance(name, call=None)
Show the details from Parallels concerning an instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.start(name, call=None)
Start a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a start mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.stop(name, call=None)
Stop a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a stop mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.parallels.wait_until(name, state, timeout=300)
Wait until a specific state has been reached on a node
.UNINDENT
.SS salt.cloud.clouds.proxmox
.SS Proxmox Cloud Module
.sp
New in version 2014.7.0.
.sp
The Proxmox cloud module is used to control access to cloud providers using
the Proxmox system (KVM / OpenVZ).
.INDENT 0.0
.TP
.B Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/proxmox.conf\fP:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-proxmox\-config:
# Proxmox account information
user: myuser@pam or myuser@pve
password: mypassword
url: hypervisor.domain.tld
provider: proxmox
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B maintainer
Frank Klaassen <\fI\%frank@cloudright.nl\fP>
.TP
.B maturity
new
.TP
.B depends
requests >= 2.2.1
.TP
.B depends
IPy >= 0.81
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.avail_images(call=None, location=\(aqlocal\(aq)
Return a list of the images that are on the provider
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-images my\-proxmox\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.avail_locations(call=None)
Return a list of the hypervisors (nodes) which this Proxmox PVE machine manages
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-list\-locations my\-proxmox\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.create(vm_)
Create a single VM from a data dict
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-p proxmox\-ubuntu vmhostname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.create_node(vm_)
Build and submit the requestdata to create a new node
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.destroy(name, call=None)
Destroy a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.get_resources_nodes(call=None, resFilter=None)
Retrieve all hypervisors (nodes) available on this environment
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f get_resources_nodes my\-proxmox\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.get_resources_vms(call=None, resFilter=None, includeConfig=True)
Retrieve all VMs available on this environment
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-f get_resources_vms my\-proxmox\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.get_vm_status(vmid=None, name=None)
Get the status for a VM, either via the ID or the hostname
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.get_vmconfig(vmid, node=None, node_type=\(aqopenvz\(aq)
Get VM configuration
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.list_nodes(call=None)
Return a list of the VMs that are managed by the provider
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-Q my\-proxmox\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.list_nodes_full(call=None)
Return a list of the VMs that are on the provider
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-F my\-proxmox\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-S my\-proxmox\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.query(conn_type, option, post_data=None)
Execute the HTTP request to the API
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.set_vm_status(status, name=None, vmid=None)
Convenience function for setting VM status
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.show_instance(name, call=None)
Show the details from Proxmox concerning an instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.shutdown(name=None, vmid=None, call=None)
Shutdown a node via ACPI.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a shutdown mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.start(name, vmid=None, call=None)
Start a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a start mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.stop(name, vmid=None, call=None)
Stop a node ("pulling the plug").
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-a stop mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.wait_for_created(upid, timeout=300)
Wait until a the vm has been created successfully
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.proxmox.wait_for_state(vmid, node, nodeType, state, timeout=300)
Wait until a specific state has been reached on a node
.UNINDENT
.SS salt.cloud.clouds.rackspace
.SS Rackspace Cloud Module
.sp
The Rackspace cloud module. This module uses the preferred means to set up a
libcloud based cloud module and should be used as the general template for
setting up additional libcloud based modules.
.INDENT 0.0
.TP
.B depends
libcloud >= 0.13.2
.UNINDENT
.sp
Please note that the \fIrackspace\fP driver is only intended for 1st gen instances,
aka, "the old cloud" at Rackspace. It is required for 1st gen instances, but
will \fInot\fP work with OpenStack\-based instances. Unless you explicitly have a
reason to use it, it is highly recommended that you use the \fIopenstack\fP driver
instead.
.sp
The rackspace cloud module interfaces with the Rackspace public cloud service
and requires that two configuration parameters be set for use, \fBuser\fP and
\fBapikey\fP\&.
.sp
Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or
\fB/etc/salt/cloud.providers.d/rackspace.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-rackspace\-config:
provider: rackspace
# The Rackspace login user
user: fred
# The Rackspace user\(aqs apikey
apikey: 901d3f579h23c8v73q9
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.avail_locations(conn=None, call=None)
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.avail_sizes(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.destroy(name, conn=None, call=None)
Delete a single VM
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.get_image(conn, vm_)
Return the image object to use
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.get_size(conn, vm_)
Return the VM\(aqs size object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.list_nodes(conn=None, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.list_nodes_full(conn=None, call=None)
Return a list of the VMs that are on the provider, with all fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.list_nodes_select(conn=None, call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.preferred_ip(vm_, ips)
Return the preferred Internet protocol. Either \(aqipv4\(aq (default) or \(aqipv6\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.show_instance(name, call=None)
Show the details from the provider concerning an instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.rackspace.ssh_interface(vm_)
Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default)
or \(aqprivate_ips\(aq.
.UNINDENT
.SS salt.cloud.clouds.saltify
.SS Saltify Module
.sp
The Saltify module is designed to install Salt on a remote machine, virtual or
bare metal, using SSH. This module is useful for provisioning machines which
are already installed, but not Salted.
.sp
Use of this module requires no configuration in the main cloud configuration
file. However, profiles must still be configured, as described in the
\fIcore config documentation\fP\&.
.INDENT 0.0
.TP
.B salt.cloud.clouds.saltify.create(vm_)
Provision a single machine
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.saltify.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.saltify.list_nodes()
Because this module is not specific to any cloud providers, there will be
no nodes to list.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.saltify.list_nodes_full()
Because this module is not specific to any cloud providers, there will be
no nodes to list.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.saltify.list_nodes_select()
Because this module is not specific to any cloud providers, there will be
no nodes to list.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.saltify.script(vm_)
Return the script deployment object
.UNINDENT
.SS salt.cloud.clouds.softlayer
.SS SoftLayer Cloud Module
.sp
The SoftLayer cloud module is used to control access to the SoftLayer VPS
system.
.sp
Use of this module only requires the \fBapikey\fP parameter. Set up the cloud
configuration at:
.sp
\fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/softlayer.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-softlayer\-config:
# SoftLayer account api key
user: MYLOGIN
apikey: JVkbSJDGHSDKUKSDJfhsdklfjgsjdkflhjlsdfffhgdgjkenrtuinv
provider: softlayer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The SoftLayer Python Library needs to be installed in order to use the
SoftLayer salt.cloud modules. See: \fI\%https://pypi.python.org/pypi/SoftLayer\fP
.INDENT 0.0
.TP
.B depends
softlayer
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.avail_images(call=None)
Return a dict of all available VM images on the cloud provider.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.avail_locations(call=None)
List all available locations
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.avail_sizes(call=None)
Return a dict of all available VM sizes on the cloud provider with
relevant data. This data is provided in three dicts.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.destroy(name, call=None)
Destroy a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.get_conn(service=\(aqSoftLayer_Virtual_Guest\(aq)
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.get_location(vm_=None)
.INDENT 7.0
.TP
.B Return the location to use, in this order:
.INDENT 7.0
.IP \(bu 2
CLI parameter
.IP \(bu 2
VM parameter
.IP \(bu 2
Cloud profile setting
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.list_custom_images(call=None)
Return a dict of all custom VM images on the cloud provider.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.list_nodes(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.list_nodes_full(mask=\(aqmask[id]\(aq, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.list_vlans(call=None)
List all VLANs associated with the account
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer.show_instance(name, call=None)
Show the details from SoftLayer concerning a guest
.UNINDENT
.SS salt.cloud.clouds.softlayer_hw
.SS SoftLayer HW Cloud Module
.sp
The SoftLayer HW cloud module is used to control access to the SoftLayer
hardware cloud system
.sp
Use of this module only requires the \fBapikey\fP parameter. Set up the cloud
configuration at:
.sp
\fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/softlayer.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-softlayer\-config:
# SoftLayer account api key
user: MYLOGIN
apikey: JVkbSJDGHSDKUKSDJfhsdklfjgsjdkflhjlsdfffhgdgjkenrtuinv
provider: softlayer_hw
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The SoftLayer Python Library needs to be installed in order to use the
SoftLayer salt.cloud modules. See: \fI\%https://pypi.python.org/pypi/SoftLayer\fP
.INDENT 0.0
.TP
.B depends
softlayer
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.avail_images(call=None)
Return a dict of all available VM images on the cloud provider.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.avail_locations(call=None)
List all available locations
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.avail_sizes(call=None)
Return a dict of all available VM sizes on the cloud provider with
relevant data. This data is provided in three dicts.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.destroy(name, call=None)
Destroy a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.get_conn(service=\(aqSoftLayer_Hardware\(aq)
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.get_location(vm_=None)
.INDENT 7.0
.TP
.B Return the location to use, in this order:
.INDENT 7.0
.IP \(bu 2
CLI parameter
.IP \(bu 2
VM parameter
.IP \(bu 2
Cloud profile setting
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.list_nodes(call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.list_nodes_full(mask=\(aqmask[id, hostname, primaryIpAddress, primaryBackendIpAddress, processorPhysicalCoreAmount, memoryCount]\(aq, call=None)
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.list_nodes_select(call=None)
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.list_vlans(call=None)
List all VLANs associated with the account
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.softlayer_hw.show_instance(name, call=None)
Show the details from SoftLayer concerning a guest
.UNINDENT
.SS salt.cloud.clouds.vsphere
.SS vSphere Cloud Module
.sp
New in version 2014.7.0.
.sp
The vSphere cloud module is used to control access to VMWare vSphere.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
PySphere Python module
.UNINDENT
.UNINDENT
.sp
Use of this module only requires a URL, username and password. Set up the cloud
configuration at:
.sp
\fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/vsphere.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-vsphere\-config:
provider: vsphere
user: myuser
password: verybadpass
url: \(aqhttps://10.1.1.1:443\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B folder: Name of the folder that will contain the new VM. If not set, the VM will
be added to the folder the original VM belongs to.
.TP
.B resourcepool: MOR of the resourcepool to be used for the new vm. If not set, it
uses the same resourcepool than the original vm.
.TP
.B datastore: MOR of the datastore where the virtual machine should be located. If
not specified, the current datastore is used.
.TP
.B host: MOR of the host where the virtual machine should be registered.
.INDENT 7.0
.TP
.B IF not specified:
.INDENT 7.0
.IP \(bu 2
if resourcepool is not specified, current host is used.
.IP \(bu 2
if resourcepool is specified, and the target pool represents a
stand\-alone host, the host is used.
.IP \(bu 2
if resourcepool is specified, and the target pool represents a
DRS\-enabled cluster, a host selected by DRS is used.
.IP \(bu 2
if resourcepool is specified and the target pool represents a cluster
without DRS enabled, an InvalidArgument exception will be thrown.
.UNINDENT
.UNINDENT
.TP
.B template: Specifies whether or not the new virtual machine should be marked as a
template. Default is False.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.avail_images()
Return a dict of all available VM images on the cloud provider.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.avail_locations()
Return a dict of all available VM locations on the cloud provider with
relevant data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.create(vm_)
Create a single VM from a data dict
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.destroy(name, call=None)
Destroy a node.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-cloud \-\-destroy mymachine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.get_configured_provider()
Return the first configured instance.
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.get_conn()
Return a conn object for the passed VM data
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_clusters(kwargs=None, call=None)
List the clusters for this VMware environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_datacenters(kwargs=None, call=None)
List the data centers for this VMware environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_datastores(kwargs=None, call=None)
List the datastores for this VMware environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_folders(kwargs=None, call=None)
List the folders for this VMWare environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_hosts(kwargs=None, call=None)
List the hosts for this VMware environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_nodes()
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_nodes_full()
Return a list of the VMs that are on the provider
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_nodes_min()
Return a list of the nodes in the provider, with no details
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_nodes_select()
Return a list of the VMs that are on the provider, with select fields
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.list_resourcepools(kwargs=None, call=None)
List the hosts for this VMware environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.script(vm_)
Return the script deployment object
.UNINDENT
.INDENT 0.0
.TP
.B salt.cloud.clouds.vsphere.show_instance(name, call=None)
Show the details from vSphere concerning a guest
.UNINDENT
.SS 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
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
##### Primary configuration settings #####
##########################################
# This configuration file is used to manage the behavior of the Salt Master.
# Values that are commented out but have no space after the comment are
# defaults that need not be set in the config. If there is a space after the
# comment that the value is presented as an example and is not the default.
# Per default, the master will automatically include all config files
# from master.d/*.conf (master.d is a directory in the same directory
# as the main master config file).
#default_include: master.d/*.conf
# The address of the interface to bind to:
#interface: 0.0.0.0
# Whether the master should listen for IPv6 connections. If this is set to True,
# the interface option must be adjusted, too. (For example: "interface: \(aq::\(aq")
#ipv6: False
# The tcp port used by the publisher:
#publish_port: 4505
# The user under which the salt master will run. Salt will update all
# permissions to allow the specified user to run the master. The exception is
# the job cache, which must be deleted if this user is changed. If the
# modified files cause conflicts, set verify_env to False.
#user: root
# Max open files
#
# Each minion connecting to the master uses AT LEAST one file descriptor, the
# master subscription connection. If enough minions connect you might start
# seeing on the console (and then salt\-master crashes):
# Too many open files (tcp_listener.cpp:335)
# Aborted (core dumped)
#
# By default this value will be the one of \(gaulimit \-Hn\(ga, ie, the hard limit for
# max open files.
#
# If you wish to set a different value than the default one, uncomment and
# configure this setting. Remember that this value CANNOT be higher than the
# hard limit. Raising the hard limit depends on your OS and/or distribution,
# a good way to find the limit is to search the internet. For example:
# raise max open files hard limit debian
#
#max_open_files: 100000
# The number of worker threads to start. These threads are used to manage
# return calls made from minions to the master. If the master seems to be
# running slowly, increase the number of threads.
#worker_threads: 5
# The port used by the communication interface. The ret (return) port is the
# interface used for the file server, authentication, job returns, etc.
#ret_port: 4506
# Specify the location of the daemon process ID file:
#pidfile: /var/run/salt\-master.pid
# The root directory prepended to these options: pki_dir, cachedir,
# sock_dir, log_file, autosign_file, autoreject_file, extension_modules,
# key_logfile, pidfile:
#root_dir: /
# Directory used to store public key data:
#pki_dir: /etc/salt/pki/master
# Directory to store job and cache data:
#cachedir: /var/cache/salt/master
# Directory for custom modules. This directory can contain subdirectories for
# each of Salt\(aqs module types such as "runners", "output", "wheel", "modules",
# "states", "returners", etc.
#extension_modules: <no default>
# Verify and set permissions on configuration directories at startup:
#verify_env: True
# Set the number of hours to keep old job information in the job cache:
#keep_jobs: 24
# Set the default timeout for the salt command and api. The default is 5
# seconds.
#timeout: 5
# The loop_interval option controls the seconds for the master\(aqs maintenance
# process check cycle. This process updates file server backends, cleans the
# job cache and executes the scheduler.
#loop_interval: 60
# Set the default outputter used by the salt command. The default is "nested".
#output: nested
# By default, output is colored. To disable colored output, set the color value
# to False.
#color: True
# Do not strip off the colored output from nested results and state outputs
# (true by default).
# strip_colors: False
# Set the directory used to hold unix sockets:
#sock_dir: /var/run/salt/master
# The master can take a while to start up when lspci and/or dmidecode is used
# to populate the grains for the master. Enable if you want to see GPU hardware
# data for your master.
# enable_gpu_grains: False
# The master maintains a job cache. While this is a great addition, it can be
# a burden on the master for larger deployments (over 5000 minions).
# Disabling the job cache will make previously executed jobs unavailable to
# the jobs system and is not generally recommended.
#job_cache: True
# Cache minion grains and pillar data in the cachedir.
#minion_data_cache: True
# Passing very large events can cause the minion to consume large amounts of
# memory. This value tunes the maximum size of a message allowed onto the
# master event bus. The value is expressed in bytes.
#max_event_size: 1048576
# By default, the master AES key rotates every 24 hours. The next command
# following a key rotation will trigger a key refresh from the minion which may
# result in minions which do not respond to the first command after a key refresh.
#
# To tell the master to ping all minions immediately after an AES key refresh, set
# ping_on_rotate to True. This should mitigate the issue where a minion does not
# appear to initially respond after a key is rotated.
#
# Note that ping_on_rotate may cause high load on the master immediately after
# the key rotation event as minions reconnect. Consider this carefully if this
# salt master is managing a large number of minions.
#
# If disabled, it is recommended to handle this event by listening for the
# \(aqaes_key_rotate\(aq event with the \(aqkey\(aq tag and acting appropriately.
# ping_on_rotate: False
# By default, the master deletes its cache of minion data when the key for that
# minion is removed. To preserve the cache after key deletion, set
# \(aqpreserve_minion_cache\(aq to True.
#
# WARNING: This may have security implications if compromised minions auth with
# a previous deleted minion ID.
#preserve_minion_cache: False
# If max_minions is used in large installations, the master might experience
# high\-load situations because of having to check the number of connected
# minions for every authentication. This cache provides the minion\-ids of
# all connected minions to all MWorker\-processes and greatly improves the
# performance of max_minions.
# con_cache: False
# The master can include configuration from other files. To enable this,
# pass a list of paths to this option. The paths can be either relative or
# absolute; if relative, they are considered to be relative to the directory
# the main master configuration file lives in (this file). Paths can make use
# of shell\-style globbing. If no files are matched by a path passed to this
# option, then the master will log a warning message.
#
# Include a config file from some other path:
#include: /etc/salt/extra_config
#
# Include config from several files and directories:
#include:
# \- /etc/salt/extra_config
##### Security settings #####
##########################################
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
# you do so at your own risk!
#open_mode: False
# Enable auto_accept, this setting will automatically accept all incoming
# public keys from the minions. Note that this is insecure.
#auto_accept: False
# Time in minutes that a incomming public key with a matching name found in
# pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys
# are removed when the master checks the minion_autosign directory.
# 0 equals no timeout
# autosign_timeout: 120
# If the autosign_file is specified, incoming keys specified in the
# autosign_file will be automatically accepted. This is insecure. Regular
# expressions as well as globing lines are supported.
#autosign_file: /etc/salt/autosign.conf
# Works like autosign_file, but instead allows you to specify minion IDs for
# which keys will automatically be rejected. Will override both membership in
# the autosign_file and the auto_accept setting.
#autoreject_file: /etc/salt/autoreject.conf
# Enable permissive access to the salt keys. This allows you to run the
# master or minion as root, but have a non\-root group be given access to
# your pki_dir. To make the access explicit, root must belong to the group
# you\(aqve given access to. This is potentially quite insecure. If an autosign_file
# is specified, enabling permissive_pki_access will allow group access to that
# specific file.
#permissive_pki_access: False
# Allow users on the master access to execute specific commands on minions.
# This setting should be treated with care since it opens up execution
# capabilities to non root users. By default this capability is completely
# disabled.
#client_acl:
# larry:
# \- test.ping
# \- network.*
# Blacklist any of the following users or modules
#
# This example would blacklist all non sudo users, including root from
# running any commands. It would also blacklist any use of the "cmd"
# module. This is completely disabled by default.
#
#client_acl_blacklist:
# users:
# \- root
# \- \(aq^(?!sudo_).*$\(aq # all non sudo users
# modules:
# \- cmd
# The external auth system uses the Salt auth modules to authenticate and
# validate users to access areas of the Salt system.
#external_auth:
# pam:
# fred:
# \- test.*
# Time (in seconds) for a newly generated token to live. Default: 12 hours
#token_expire: 43200
# Allow minions to push files to the master. This is disabled by default, for
# security purposes.
#file_recv: False
# Set a hard\-limit on the size of the files that can be pushed to the master.
# It will be interpreted as megabytes. Default: 100
#file_recv_max_size: 100
# Signature verification on messages published from the master.
# This causes the master to cryptographically sign all messages published to its event
# bus, and minions then verify that signature before acting on the message.
#
# This is False by default.
#
# Note that to facilitate interoperability with masters and minions that are different
# versions, if sign_pub_messages is True but a message is received by a minion with
# no signature, it will still be accepted, and a warning message will be logged.
# Conversely, if sign_pub_messages is False, but a minion receives a signed
# message it will be accepted, the signature will not be checked, and a warning message
# will be logged. This behavior went away in Salt 2014.1.0 and these two situations
# will cause minion to throw an exception and drop the message.
# sign_pub_messages: False
##### Master Module Management #####
##########################################
# Manage how master side modules are loaded.
# Add any additional locations to look for master runners:
#runner_dirs: []
# Enable Cython for master side modules:
#cython_enable: False
##### State System settings #####
##########################################
# The state system uses a "top" file to tell the minions what environment to
# use and what modules to use. The state_top file is defined relative to the
# root of the base environment as defined in "File Server settings" below.
#state_top: top.sls
# The master_tops option replaces the external_nodes option by creating
# a plugable system for the generation of external top data. The external_nodes
# option is deprecated by the master_tops option.
#
# To gain the capabilities of the classic external_nodes system, use the
# following configuration:
# master_tops:
# ext_nodes: <Shell command which returns yaml>
#
#master_tops: {}
# The external_nodes option allows Salt to gather data that would normally be
# placed in a top file. The external_nodes option is the executable that will
# return the ENC data. Remember that Salt will look for external nodes AND top
# files and combine the results if both are enabled!
#external_nodes: None
# The renderer to use on the minions to render the state data
#renderer: yaml_jinja
# The Jinja renderer can strip extra carriage returns and whitespace
# See http://jinja.pocoo.org/docs/api/#high\-level\-api
#
# If this is set to True the first newline after a Jinja block is removed
# (block, not variable tag!). Defaults to False, corresponds to the Jinja
# environment init variable "trim_blocks".
# jinja_trim_blocks: False
#
# If this is set to True leading spaces and tabs are stripped from the start
# of a line to a block. Defaults to False, corresponds to the Jinja
# environment init variable "lstrip_blocks".
# jinja_lstrip_blocks: False
# The failhard option tells the minions to stop immediately after the first
# failure detected in the state execution, defaults to False
#failhard: False
# The state_verbose and state_output settings can be used to change the way
# state system data is printed to the display. By default all data is printed.
# The state_verbose setting can be set to True or False, when set to False
# all data that has a result of True and no changes will be suppressed.
#state_verbose: True
# The state_output setting changes if the output is the full multi line
# output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq
# the output will be shortened to a single line. If set to \(aqmixed\(aq, the output
# will be terse unless a state failed, in which case that output will be full.
# If set to \(aqchanges\(aq, the output will be full unless the state didn\(aqt change.
#state_output: full
# Automatically aggregate all states that have support for mod_aggregate by
# setting to True. Or pass a list of state module names to automatically
# aggregate just those types.
#
# state_aggregate:
# \- pkg
#
#state_aggregate: 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
#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.
#
# Prior to changing this value, the master should be stopped and all Salt
# caches should be cleared.
#hash_type: md5
# The buffer size in the file server can be adjusted here:
#file_buffer_size: 1048576
# A regular expression (or a list of expressions) that will be matched
# against the file path before syncing the modules and states to the minions.
# This includes files affected by the file.recurse state.
# For example, if you manage your custom modules and states in subversion
# and don\(aqt want all the \(aq.svn\(aq folders and content synced to your minions,
# you could set this to \(aq/\e.svn($|/)\(aq. By default nothing is ignored.
#file_ignore_regex:
# \- \(aq/\e.svn($|/)\(aq
# \- \(aq/\e.git($|/)\(aq
# A file glob (or list of file globs) that will be matched against the file
# path before syncing the modules and states to the minions. This is similar
# to file_ignore_regex above, but works on globs instead of regex. By default
# nothing is ignored.
# file_ignore_glob:
# \- \(aq*.pyc\(aq
# \- \(aq*/somefolder/*.bak\(aq
# \- \(aq*.swp\(aq
# File Server Backend
#
# Salt supports a modular fileserver backend system, this system allows
# the salt master to link directly to third party systems to gather and
# manage the files available to minions. Multiple backends can be
# configured and will be searched for the requested file in the order in which
# they are defined here. The default setting only enables the standard backend
# "roots" which uses the "file_roots" option.
#fileserver_backend:
# \- roots
#
# To use multiple backends list them in the order they are searched:
#fileserver_backend:
# \- git
# \- roots
#
# Uncomment the line below if you do not want the file_server to follow
# symlinks when walking the filesystem tree. This is set to True
# by default. Currently this only applies to the default roots
# fileserver_backend.
#fileserver_followsymlinks: False
#
# Uncomment the line below if you do not want symlinks to be
# treated as the files they are pointing to. By default this is set to
# False. By uncommenting the line below, any detected symlink while listing
# files on the Master will not be returned to the Minion.
#fileserver_ignoresymlinks: True
#
# By default, the Salt fileserver recurses fully into all defined environments
# to attempt to find files. To limit this behavior so that the fileserver only
# traverses directories with SLS files and special Salt directories like _modules,
# enable the option below. This might be useful for installations where a file root
# has a very large number of files and performance is impacted. Default is False.
# fileserver_limit_traversal: False
#
# The fileserver can fire events off every time the fileserver is updated,
# these are disabled by default, but can be easily turned on by setting this
# flag to True
#fileserver_events: False
# Git File Server Backend Configuration
#
# Gitfs can be provided by one of two python modules: GitPython or pygit2. If
# using pygit2, both libgit2 and git must also be installed.
#gitfs_provider: gitpython
#
# When using the git fileserver backend at least one git remote needs to be
# defined. The user running the salt master will need read access to the repo.
#
# The repos will be searched in order to find the file requested by a client
# and the first repo to have the file will return it.
# When using the git backend branches and tags are translated into salt
# environments.
# Note: file:// repos will be treated as a remote, so refs you want used must
# exist in that repo as *local* refs.
#gitfs_remotes:
# \- git://github.com/saltstack/salt\-states.git
# \- file:///var/git/saltmaster
#
# The gitfs_ssl_verify option specifies whether to ignore ssl certificate
# errors when contacting the gitfs backend. You might want to set this to
# false if you\(aqre using a git backend that uses a self\-signed certificate but
# keep in mind that setting this flag to anything other than the default of True
# is a security concern, you may want to try using the ssh transport.
#gitfs_ssl_verify: True
#
# The gitfs_root option gives the ability to serve files from a subdirectory
# within the repository. The path is defined relative to the root of the
# repository and defaults to the repository root.
#gitfs_root: somefolder/otherfolder
##### Pillar settings #####
##########################################
# Salt Pillars allow for the building of global data that can be made selectively
# available to different minions based on minion grain filtering. The Salt
# Pillar is laid out in the same fashion as the file server, with environments,
# a top file and sls files. However, pillar data does not need to be in the
# highstate format, and is generally just key/value pairs.
#pillar_roots:
# base:
# \- /srv/pillar
#
#ext_pillar:
# \- hiera: /etc/hiera.yaml
# \- cmd_yaml: cat /etc/salt/yaml
# The pillar_gitfs_ssl_verify option specifies whether to ignore ssl certificate
# errors when contacting the pillar gitfs backend. You might want to set this to
# false if you\(aqre using a git backend that uses a self\-signed certificate but
# keep in mind that setting this flag to anything other than the default of True
# is a security concern, you may want to try using the ssh transport.
#pillar_gitfs_ssl_verify: True
# The pillar_opts option adds the master configuration file data to a dict in
# the pillar called "master". This is used to set simple configurations in the
# master config file that can then be used on minions.
#pillar_opts: True
##### Syndic settings #####
##########################################
# The Salt syndic is used to pass commands through a master from a higher
# master. Using the syndic is simple, if this is a master that will have
# syndic servers(s) below it set the "order_masters" setting to True, if this
# is a master that will be running a syndic daemon for passthrough the
# "syndic_master" setting needs to be set to the location of the master server
# to receive commands from.
# Set the order_masters setting to True if this master will command lower
# masters\(aq syndic interfaces.
#order_masters: False
# If this master will be running a salt syndic daemon, syndic_master tells
# this master where to receive commands from.
#syndic_master: masterofmaster
# This is the \(aqret_port\(aq of the MasterOfMaster:
#syndic_master_port: 4506
# PID file of the syndic daemon:
#syndic_pidfile: /var/run/salt\-syndic.pid
# LOG file of the syndic daemon:
#syndic_log_file: syndic.log
##### Peer Publish settings #####
##########################################
# Salt minions can send commands to other minions, but only if the minion is
# allowed to. By default "Peer Publication" is disabled, and when enabled it
# is enabled for specific minions and specific commands. This allows secure
# compartmentalization of commands based on individual minions.
# The configuration uses regular expressions to match minions and then a list
# of regular expressions to match functions. The following will allow the
# minion authenticated as foo.example.com to execute functions from the test
# and pkg modules.
#peer:
# foo.example.com:
# \- test.*
# \- pkg.*
#
# This will allow all minions to execute all commands:
#peer:
# .*:
# \- .*
#
# This is not recommended, since it would allow anyone who gets root on any
# single minion to instantly have root on all of the minions!
# Minions can also be allowed to execute runners from the salt master.
# Since executing a runner from the minion could be considered a security risk,
# it needs to be enabled. This setting functions just like the peer setting
# except that it opens up runners instead of module functions.
#
# All peer runner support is turned off by default and must be enabled before
# using. This will enable all peer runners for all minions:
#peer_run:
# .*:
# \- .*
#
# To enable just the manage.up runner for the minion foo.example.com:
#peer_run:
# foo.example.com:
# \- manage.up
##### Mine settings #####
##########################################
# Restrict mine.get access from minions. By default any minion has a full access
# to get all mine data from master cache. In acl definion below, only pcre matches
# are allowed.
# mine_get:
# .*:
# \- .*
#
# The example below enables minion foo.example.com to get \(aqnetwork.interfaces\(aq mine
# data only, minions web* to get all network.* and disk.* mine data and all other
# minions won\(aqt get any mine data.
# mine_get:
# foo.example.com:
# \- network.interfaces
# web.*:
# \- network.*
# \- disk.*
##### Logging settings #####
##########################################
# The location of the master log file
# The master log can be sent to a regular file, local path name, or network
# location. Remote logging works best when configured to use rsyslogd(8) (e.g.:
# \(ga\(gafile:///dev/log\(ga\(ga), with rsyslogd(8) configured for network logging. The URI
# format is: <file|udp|tcp>://<host|socketpath>:<port\-if\-required>/<log\-facility>
#log_file: /var/log/salt/master
#log_file: file:///dev/log
#log_file: udp://loghost:10514
#log_file: /var/log/salt/master
#key_logfile: /var/log/salt/key
# The level of messages to send to the console.
# One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq.
#log_level: warning
# The level of messages to send to the log file.
# One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq.
# If using \(aqlog_granular_levels\(aq this must be set to the highest desired level.
#log_level_logfile: warning
# The date and time format used in log messages. Allowed date/time formating
# can be seen here: http://docs.python.org/library/time.html#time.strftime
#log_datefmt: \(aq%H:%M:%S\(aq
#log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq
# The format of the console logging messages. Allowed formatting options can
# be seen here: http://docs.python.org/library/logging.html#logrecord\-attributes
#log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq
#log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq
# This can be used to control logging levels more specificically. This
# example sets the main salt library at the \(aqwarning\(aq level, but sets
# \(aqsalt.modules\(aq to log 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
##### Range Cluster settings #####
##########################################
# The range server (and optional port) that serves your cluster information
# https://github.com/ytoolshed/range/wiki/%22yamlfile%22\-module\-file\-spec
#
#range_server: range:80
##### Windows Software Repo settings #####
##############################################
# Location of the repo on the master:
#win_repo: \(aq/srv/salt/win/repo\(aq
# Location of the master\(aqs repo cache file:
#win_repo_mastercachefile: \(aq/srv/salt/win/repo/winrepo.p\(aq
# List of git repositories to include with the local repo:
#win_gitrepos:
# \- \(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example minion configuration file
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
##### Primary configuration settings #####
##########################################
# This configuration file is used to manage the behavior of the Salt Minion.
# With the exception of the location of the Salt Master Server, values that
# are commented out but have no space after the comment are defaults that need
# not be set in the config. If there is a space after the comment that the value
# is presented as an example and is not the default.
# Per default the minion will automatically include all config files
# from minion.d/*.conf (minion.d is a directory in the same directory
# as the main minion config file).
#default_include: minion.d/*.conf
# Set the location of the salt master server. If the master server cannot be
# resolved, then the minion will fail to start.
#master: salt
# If multiple masters are specified in the \(aqmaster\(aq setting, the default behavior
# is to always try to connect to them in the order they are listed. If random_master is
# set to True, the order will be randomized instead. This can be helpful in distributing
# the load of many minions executing salt\-call requests, for example, from a cron job.
# If only one master is listed, this setting is ignored and a warning will be logged.
#random_master: False
# Set whether the minion should connect to the master via IPv6:
#ipv6: False
# Set the number of seconds to wait before attempting to resolve
# the master hostname if name resolution fails. Defaults to 30 seconds.
# Set to zero if the minion should shutdown and not retry.
# retry_dns: 30
# Set the port used by the master reply and authentication server.
#master_port: 4506
# The user to run salt.
#user: root
# Specify the location of the daemon process ID file.
#pidfile: /var/run/salt\-minion.pid
# The root directory prepended to these options: pki_dir, cachedir, log_file,
# sock_dir, pidfile.
#root_dir: /
# The directory to store the pki information in
#pki_dir: /etc/salt/pki/minion
# Explicitly declare the id for this minion to use, if left commented the id
# will be the hostname as returned by the python call: socket.getfqdn()
# Since salt uses detached ids it is possible to run multiple minions on the
# same machine but with different ids, this can be useful for salt compute
# clusters.
#id:
# Append a domain to a hostname in the event that it does not exist. This is
# useful for systems where socket.getfqdn() does not actually result in a
# FQDN (for instance, Solaris).
#append_domain:
# Custom static grains for this minion can be specified here and used in SLS
# files just like all other grains. This example sets 4 custom grains, with
# the \(aqroles\(aq grain having two values that can be matched against.
#grains:
# roles:
# \- webserver
# \- memcache
# deployment: datacenter4
# cabinet: 13
# cab_u: 14\-15
# Where cache data goes.
#cachedir: /var/cache/salt/minion
# Verify and set permissions on configuration directories at startup.
#verify_env: True
# The minion can locally cache the return data from jobs sent to it, this
# can be a good way to keep track of jobs the minion has executed
# (on the minion side). By default this feature is disabled, to enable, set
# cache_jobs to True.
#cache_jobs: False
# Set the directory used to hold unix sockets.
#sock_dir: /var/run/salt/minion
# Set the default outputter used by the salt\-call command. The default is
# "nested".
#output: nested
#
# By default output is colored. To disable colored output, set the color value
# to False.
#color: True
# Do not strip off the colored output from nested results and state outputs
# (true by default).
# strip_colors: False
# Backup files that are replaced by file.managed and file.recurse under
# \(aqcachedir\(aq/file_backups relative to their original location and appended
# with a timestamp. The only valid setting is "minion". Disabled by default.
#
# Alternatively this can be specified for each file in state files:
# /etc/ssh/sshd_config:
# file.managed:
# \- source: salt://ssh/sshd_config
# \- backup: minion
#
#backup_mode: minion
# When waiting for a master to accept the minion\(aqs public key, salt will
# continuously attempt to reconnect until successful. This is the time, in
# seconds, between those reconnection attempts.
#acceptance_wait_time: 10
# If this is nonzero, the time between reconnection attempts will increase by
# acceptance_wait_time seconds per iteration, up to this maximum. If this is
# set to zero, the time between reconnection attempts will stay constant.
#acceptance_wait_time_max: 0
# If the master rejects the minion\(aqs public key, retry instead of exiting.
# Rejected keys will be handled the same as waiting on acceptance.
#rejected_retry: False
# When the master key changes, the minion will try to re\-auth itself to receive
# the new master key. In larger environments this can cause a SYN flood on the
# master because all minions try to re\-auth immediately. To prevent this and
# have a minion wait for a random amount of time, use this optional parameter.
# The wait\-time will be a random number of seconds between 0 and the defined value.
#random_reauth_delay: 60
# When waiting for a master to accept the minion\(aqs public key, salt will
# continuously attempt to reconnect until successful. This is the timeout value,
# in seconds, for each individual attempt. After this timeout expires, the minion
# will wait for acceptance_wait_time seconds before trying again. Unless your master
# is under unusually heavy load, this should be left at the default.
#auth_timeout: 60
# Number of consecutive SaltReqTimeoutError that are acceptable when trying to
# authenticate.
#auth_tries: 1
# If authentication fails due to SaltReqTimeoutError, continue without stopping the
# minion.
#auth_safemode: False
# If the minion hits an error that is recoverable, restart the minion.
#restart_on_error: False
# Ping Master to ensure connection is alive (minutes).
#ping_interval: 0
# To auto recover minions if master changes IP address (DDNS)
# auth_tries: 10
# auth_safemode: False
# ping_interval: 90
# restart_on_error: True
#
# Minions won\(aqt know master is missing until a ping fails. After the ping fail,
# the minion will attempt authentication and likely fails out and cause a restart.
# When the minion restarts it will resolve the masters IP and attempt to reconnect.
# If you don\(aqt have any problems with syn\-floods, don\(aqt bother with the
# three recon_* settings described below, just leave the defaults!
#
# The ZeroMQ pull\-socket that binds to the masters publishing interface tries
# to reconnect immediately, if the socket is disconnected (for example if
# the master processes are restarted). In large setups this will have all
# minions reconnect immediately which might flood the master (the ZeroMQ\-default
# is usually a 100ms delay). To prevent this, these three recon_* settings
# can be used.
# recon_default: the interval in milliseconds that the socket should wait before
# trying to reconnect to the master (1000ms = 1 second)
#
# recon_max: the maximum time a socket should wait. each interval the time to wait
# is calculated by doubling the previous time. if recon_max is reached,
# it starts again at recon_default. Short example:
#
# reconnect 1: the socket will wait \(aqrecon_default\(aq milliseconds
# reconnect 2: \(aqrecon_default\(aq * 2
# reconnect 3: (\(aqrecon_default\(aq * 2) * 2
# reconnect 4: value from previous interval * 2
# reconnect 5: value from previous interval * 2
# reconnect x: if value >= recon_max, it starts again with recon_default
#
# recon_randomize: generate a random wait time on minion start. The wait time will
# be a random value between recon_default and recon_default +
# recon_max. Having all minions reconnect with the same recon_default
# and recon_max value kind of defeats the purpose of being able to
# change these settings. If all minions have the same values and your
# setup is quite large (several thousand minions), they will still
# flood the master. The desired behavior is to have timeframe within
# all minions try to reconnect.
#
# Example on how to use these settings. The goal: have all minions reconnect within a
# 60 second timeframe on a disconnect.
# recon_default: 1000
# recon_max: 59000
# recon_randomize: True
#
# Each minion will have a randomized reconnect value between \(aqrecon_default\(aq
# and \(aqrecon_default + recon_max\(aq, which in this example means between 1000ms
# 60000ms (or between 1 and 60 seconds). The generated random\-value will be
# doubled after each attempt to reconnect. Lets say the generated random
# value is 11 seconds (or 11000ms).
# reconnect 1: wait 11 seconds
# reconnect 2: wait 22 seconds
# reconnect 3: wait 33 seconds
# reconnect 4: wait 44 seconds
# reconnect 5: wait 55 seconds
# reconnect 6: wait time is bigger than 60 seconds (recon_default + recon_max)
# reconnect 7: wait 11 seconds
# reconnect 8: wait 22 seconds
# reconnect 9: wait 33 seconds
# reconnect x: etc.
#
# In a setup with ~6000 thousand hosts these settings would average the reconnects
# to about 100 per second and all hosts would be reconnected within 60 seconds.
# recon_default: 100
# recon_max: 5000
# recon_randomize: False
# The loop_interval sets how long in seconds the minion will wait between
# evaluating the scheduler and running cleanup tasks. This defaults to a
# sane 60 seconds, but if the minion scheduler needs to be evaluated more
# often lower this value
#loop_interval: 60
# The grains_refresh_every setting allows for a minion to periodically check
# its grains to see if they have changed and, if so, to inform the master
# of the new grains. This operation is moderately expensive, therefore
# care should be taken not to set this value too low.
#
# Note: This value is expressed in __minutes__!
#
# A value of 10 minutes is a reasonable default.
#
# If the value is set to zero, this check is disabled.
#grains_refresh_every: 1
# Cache grains on the minion. Default is False.
#grains_cache: False
# Grains cache expiration, in seconds. If the cache file is older than this
# number of seconds then the grains cache will be dumped and fully re\-populated
# with fresh data. Defaults to 5 minutes. Will have no effect if \(aqgrains_cache\(aq
# is not enabled.
# grains_cache_expiration: 300
# When healing, a dns_check is run. This is to make sure that the originally
# resolved dns has not changed. If this is something that does not happen in
# your environment, set this value to False.
#dns_check: True
# Windows platforms lack posix IPC and must rely on slower TCP based inter\-
# process communications. Set ipc_mode to \(aqtcp\(aq on such systems
#ipc_mode: ipc
# Overwrite the default tcp ports used by the minion when in tcp mode
#tcp_pub_port: 4510
#tcp_pull_port: 4511
# Passing very large events can cause the minion to consume large amounts of
# memory. This value tunes the maximum size of a message allowed onto the
# minion event bus. The value is expressed in bytes.
#max_event_size: 1048576
# The minion can include configuration from other files. To enable this,
# pass a list of paths to this option. The paths can be either relative or
# absolute; if relative, they are considered to be relative to the directory
# the main minion configuration file lives in (this file). Paths can make use
# of shell\-style globbing. If no files are matched by a path passed to this
# option then the minion will log a warning message.
#
# Include a config file from some other path:
# include: /etc/salt/extra_config
#
# Include config from several files and directories:
#include:
# \- /etc/salt/extra_config
# \- /etc/roles/webserver
##### Minion module management #####
##########################################
# Disable specific modules. This allows the admin to limit the level of
# access the master has to the minion.
#disable_modules: [cmd,test]
#disable_returners: []
#
# Modules can be loaded from arbitrary paths. This enables the easy deployment
# of third party modules. Modules for returners and minions can be loaded.
# Specify a list of extra directories to search for minion modules and
# returners. These paths must be fully qualified!
#module_dirs: []
#returner_dirs: []
#states_dirs: []
#render_dirs: []
#utils_dirs: []
#
# A module provider can be statically overwritten or extended for the minion
# via the providers option, in this case the default module will be
# overwritten by the specified module. In this example the pkg module will
# be provided by the yumpkg5 module instead of the system default.
#providers:
# pkg: yumpkg5
#
# Enable Cython modules searching and loading. (Default: False)
#cython_enable: False
#
# Specify a max size (in bytes) for modules on import. This feature is currently
# only supported on *nix operating systems and requires psutil.
# modules_max_memory: \-1
##### State Management Settings #####
###########################################
# The state management system executes all of the state templates on the minion
# to enable more granular control of system state management. The type of
# template and serialization used for state management needs to be configured
# on the minion, the default renderer is yaml_jinja. This is a yaml file
# rendered from a jinja template, the available options are:
# yaml_jinja
# yaml_mako
# yaml_wempy
# json_jinja
# json_mako
# json_wempy
#
#renderer: yaml_jinja
#
# The failhard option tells the minions to stop immediately after the first
# failure detected in the state execution. Defaults to False.
#failhard: False
#
# autoload_dynamic_modules turns on automatic loading of modules found in the
# environments on the master. This is turned on by default. To turn of
# autoloading modules when states run, set this value to False.
#autoload_dynamic_modules: True
#
# clean_dynamic_modules keeps the dynamic modules on the minion in sync with
# the dynamic modules on the master, this means that if a dynamic module is
# not on the master it will be deleted from the minion. By default, this is
# enabled and can be disabled by changing this value to False.
#clean_dynamic_modules: True
#
# Normally, the minion is not isolated to any single environment on the master
# when running states, but the environment can be isolated on the minion side
# by statically setting it. Remember that the recommended way to manage
# environments is to isolate via the top file.
#environment: None
#
# If using the local file directory, then the state top file name needs to be
# defined, by default this is top.sls.
#state_top: top.sls
#
# Run states when the minion daemon starts. To enable, set startup_states to:
# \(aqhighstate\(aq \-\- Execute state.highstate
# \(aqsls\(aq \-\- Read in the sls_list option and execute the named sls files
# \(aqtop\(aq \-\- Read top_file option and execute based on that file on the Master
#startup_states: \(aq\(aq
#
# List of states to run when the minion starts up if startup_states is \(aqsls\(aq:
#sls_list:
# \- edit.vim
# \- hyper
#
# Top file to execute if startup_states is \(aqtop\(aq:
#top_file: \(aq\(aq
# Automatically aggregate all states that have support for mod_aggregate by
# setting to True. Or pass a list of state module names to automatically
# aggregate just those types.
#
# state_aggregate:
# \- pkg
#
#state_aggregate: False
##### File Directory Settings #####
##########################################
# The Salt Minion can redirect all file server operations to a local directory,
# this allows for the same state tree that is on the master to be used if
# copied completely onto the minion. This is a literal copy of the settings on
# the master but used to reference a local directory on the minion.
# Set the file client. The client defaults to looking on the master server for
# files, but can be directed to look at the local file directory setting
# defined below by setting it to local.
#file_client: remote
# The file directory works on environments passed to the minion, each environment
# can have multiple root directories, the subdirectories in the multiple file
# roots cannot match, otherwise the downloaded files will not be able to be
# reliably ensured. A base environment is required to house the top file.
# Example:
# file_roots:
# base:
# \- /srv/salt/
# dev:
# \- /srv/salt/dev/services
# \- /srv/salt/dev/states
# prod:
# \- /srv/salt/prod/services
# \- /srv/salt/prod/states
#
#file_roots:
# base:
# \- /srv/salt
# By default, the Salt fileserver recurses fully into all defined environments
# to attempt to find files. To limit this behavior so that the fileserver only
# traverses directories with SLS files and special Salt directories like _modules,
# enable the option below. This might be useful for installations where a file root
# has a very large number of files and performance is negatively impacted. Default
# is False.
#fileserver_limit_traversal: False
# The hash_type is the hash to use when discovering the hash of a file in
# the local fileserver. The default is md5, but sha1, sha224, sha256, sha384
# and sha512 are also supported.
#
# Warning: Prior to changing this value, the minion should be stopped and all
# Salt caches should be cleared.
#hash_type: md5
# The Salt pillar is searched for locally if file_client is set to local. If
# this is the case, and pillar data is defined, then the pillar_roots need to
# also be configured on the minion:
#pillar_roots:
# base:
# \- /srv/pillar
###### Security settings #####
###########################################
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
# you do so at your own risk!
#open_mode: False
# Enable permissive access to the salt keys. This allows you to run the
# master or minion as root, but have a non\-root group be given access to
# your pki_dir. To make the access explicit, root must belong to the group
# you\(aqve given access to. This is potentially quite insecure.
#permissive_pki_access: False
# The state_verbose and state_output settings can be used to change the way
# state system data is printed to the display. By default all data is printed.
# The state_verbose setting can be set to True or False, when set to False
# all data that has a result of True and no changes will be suppressed.
#state_verbose: True
# The state_output setting changes if the output is the full multi line
# output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq
# the output will be shortened to a single line.
#state_output: full
# The state_output_diff setting changes whether or not the output from
# successful states is returned. Useful when even the terse output of these
# states is cluttering the logs. Set it to True to ignore them.
#state_output_diff: False
# Fingerprint of the master public key to double verify the master is valid,
# the master fingerprint can be found by running "salt\-key \-F master" on the
# salt master.
#master_finger: \(aq\(aq
###### Thread settings #####
###########################################
# Disable multiprocessing support, by default when a minion receives a
# publication a new process is spawned and the command is executed therein.
#multiprocessing: True
##### Logging settings #####
##########################################
# The location of the minion log file
# The minion log can be sent to a regular file, local path name, or network
# location. Remote logging works best when configured to use rsyslogd(8) (e.g.:
# \(ga\(gafile:///dev/log\(ga\(ga), with rsyslogd(8) configured for network logging. The URI
# format is: <file|udp|tcp>://<host|socketpath>:<port\-if\-required>/<log\-facility>
#log_file: /var/log/salt/minion
#log_file: file:///dev/log
#log_file: udp://loghost:10514
#
#log_file: /var/log/salt/minion
#key_logfile: /var/log/salt/key
# The level of messages to send to the console.
# One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq.
# Default: \(aqwarning\(aq
#log_level: warning
# The level of messages to send to the log file.
# One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq.
# If using \(aqlog_granular_levels\(aq this must be set to the highest desired level.
# Default: \(aqwarning\(aq
#log_level_logfile:
# The date and time format used in log messages. Allowed date/time formating
# can be seen here: http://docs.python.org/library/time.html#time.strftime
#log_datefmt: \(aq%H:%M:%S\(aq
#log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq
# The format of the console logging messages. Allowed formatting options can
# be seen here: http://docs.python.org/library/logging.html#logrecord\-attributes
#log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq
#log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq
# This can be used to control logging levels more specificically. This
# example sets the main salt library at the \(aqwarning\(aq level, but sets
# \(aqsalt.modules\(aq to log 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 applied via the yaml dict construct, some examples:
#
# You can specify that all modules should run in test mode:
#test: True
#
# A simple value for the test module:
#test.foo: foo
#
# A list for the test module:
#test.bar: [baz,quo]
#
# A dict for the test module:
#test.baz: {spam: sausage, cheese: bread}
###### Update settings ######
###########################################
# Using the features in Esky, a salt minion can both run as a frozen app and
# be updated on the fly. These options control how the update process
# (saltutil.update()) behaves.
#
# The url for finding and downloading updates. Disabled by default.
#update_url: False
#
# The list of services to restart after a successful update. Empty by default.
#update_restart_services: []
###### Keepalive settings ######
############################################
# ZeroMQ now includes support for configuring SO_KEEPALIVE if supported by
# the OS. If connections between the minion and the master pass through
# a state tracking device such as a firewall or VPN gateway, there is
# the risk that it could tear down the connection the master and minion
# without informing either party that their connection has been taken away.
# Enabling TCP Keepalives prevents this from happening.
# Overall state of TCP Keepalives, enable (1 or True), disable (0 or False)
# or leave to the OS defaults (\-1), on Linux, typically disabled. Default True, enabled.
#tcp_keepalive: True
# How long before the first keepalive should be sent in seconds. Default 300
# to send the first keepalive after 5 minutes, OS default (\-1) is typically 7200 seconds
# on Linux see /proc/sys/net/ipv4/tcp_keepalive_time.
#tcp_keepalive_idle: 300
# How many lost probes are needed to consider the connection lost. Default \-1
# to use OS defaults, typically 9 on Linux, see /proc/sys/net/ipv4/tcp_keepalive_probes.
#tcp_keepalive_cnt: \-1
# How often, in seconds, to send keepalives after the first one. Default \-1 to
# use OS defaults, typically 75 seconds on Linux, see
# /proc/sys/net/ipv4/tcp_keepalive_intvl.
#tcp_keepalive_intvl: \-1
###### Windows Software settings ######
############################################
# Location of the repository cache file on the master:
#win_repo_cachefile: \(aqsalt://win/repo/winrepo.p\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS 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.
.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\&.
.SS Master Configuration
.sp
By default the Salt master listens on ports 4505 and 4506 on all
interfaces (0.0.0.0). To bind Salt to a specific IP, redefine the
"interface" directive in the master configuration file, typically
\fB/etc/salt/master\fP, as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- #interface: 0.0.0.0
+ interface: 10.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After updating the configuration file, restart the Salt master.
See the \fBmaster configuration reference\fP
for more details about other configurable options.
.SS Minion Configuration
.sp
Although there are many Salt Minion configuration options, configuring
a Salt Minion is very simple. By default a Salt Minion will
try to connect to the DNS name "salt"; if the Minion is able to
resolve that name correctly, no configuration is needed.
.sp
If the DNS name "salt" does not resolve to point to the correct
location of the Master, redefine the "master" directive in the minion
configuration file, typically \fB/etc/salt/minion\fP, as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- #master: salt
+ master: 10.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After updating the configuration file, restart the Salt minion.
See the \fBminion configuration reference\fP
for more details about other configurable options.
.SS Running Salt
.INDENT 0.0
.IP 1. 3
Start the master in the foreground (to daemonize the process, pass the
\fB\-d flag\fP):
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Start the minion in the foreground (to daemonize the process, pass the
\fB\-d flag\fP):
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "Having trouble?"
.sp
The simplest way to troubleshoot Salt is to run the master and minion in
the foreground with \fBlog level\fP set to \fBdebug\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master \-\-log\-level=debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For information on salt\(aqs logging system please see the \fBlogging
document\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "Run as an unprivileged (non\-root) user"
.sp
To run Salt as another user, set the \fBuser\fP parameter in the
master config file.
.sp
Additionally, ownership and permissions need to be set such that the
desired user can read from and write to the following directories (and
their subdirectories, where applicable):
.INDENT 0.0
.IP \(bu 2
/etc/salt
.IP \(bu 2
/var/cache/salt
.IP \(bu 2
/var/log/salt
.IP \(bu 2
/var/run/salt
.UNINDENT
.sp
More information about running salt as a non\-privileged user can be found
\fBhere\fP\&.
.UNINDENT
.UNINDENT
.sp
There is also a full \fBtroubleshooting guide\fP
available.
.SS Key Management
.sp
Salt uses AES encryption for all communication between the Master and
the Minion. This ensures that the commands sent to the Minions cannot
be tampered with, and that communication between Master and Minion is
authenticated through trusted, accepted keys.
.sp
Before commands can be sent to a Minion, its key must be accepted on
the Master. Run the \fBsalt\-key\fP command to list the keys known to
the Salt Master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@master ~]# salt\-key \-L
Unaccepted Keys:
alpha
bravo
charlie
delta
Accepted Keys:
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example shows that the Salt Master is aware of four Minions, but none of
the keys has been accepted. To accept the keys and allow the Minions to be
controlled by the Master, again use the \fBsalt\-key\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@master ~]# salt\-key \-A
[root@master ~]# salt\-key \-L
Unaccepted Keys:
Accepted Keys:
alpha
bravo
charlie
delta
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBsalt\-key\fP command allows for signing keys individually or in bulk. The
example above, using \fB\-A\fP bulk\-accepts all pending keys. To accept keys
individually use the lowercase of the same option, \fB\-a keyname\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBsalt\-key manpage\fP
.UNINDENT
.UNINDENT
.SS Sending Commands
.sp
Communication between the Master and a Minion may be verified by running
the \fBtest.ping\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@master ~]# salt alpha test.ping
alpha:
True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Communication between the Master and all Minions may be tested in a
similar way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@master ~]# salt \(aq*\(aq test.ping
alpha:
True
bravo:
True
charlie:
True
delta:
True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Each of the Minions should send a \fBTrue\fP response as shown above.
.SS What\(aqs Next?
.sp
Understanding \fBtargeting\fP is important. From there,
depending on the way you wish to use Salt, you should also proceed to learn
about \fBStates\fP and \fBExecution Modules\fP\&.
.SS 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.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIexample master configuration file\fP
.UNINDENT
.UNINDENT
.sp
The configuration file for the salt\-master is located at
\fB/etc/salt/master\fP by default. A notable exception is FreeBSD, where the
configuration file is located at \fB/usr/local/etc/salt\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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
interface: 192.168.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBipv6\fP
.sp
Default: \fBFalse\fP
.sp
Whether the master should listen for IPv6 connections. If this is set to True,
the interface option must be adjusted too (for example: "interface: \(aq::\(aq")
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ipv6: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBpublish_port\fP
.sp
Default: \fB4505\fP
.sp
The network port to set up the publication interface
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
publish_port: 4505
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_id\fP
.sp
Default: \fBNone\fP
.sp
The id to be passed in the publish job to minions. This is used for MultiSyndics
to return the job to the requesting master. Note, this must be the same string
as the syndic is configured with.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_id: MasterOfMaster
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBuser\fP
.sp
Default: \fBroot\fP
.sp
The user to run the Salt processes
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
user: root
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmax_open_files\fP
.sp
Default: \fB100000\fP
.sp
Each minion connecting to the master uses AT LEAST one file descriptor, the
master subscription connection. If enough minions connect you might start
seeing on the console(and then salt\-master crashes):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Too many open files (tcp_listener.cpp:335)
Aborted (core dumped)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
max_open_files: 100000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default this value will be the one of \fIulimit \-Hn\fP, i.e., the hard limit for
max open files.
.sp
To set a different value than the default one, uncomment and configure this
setting. Remember that this value CANNOT be higher than the hard limit. Raising
the hard limit depends on the OS and/or distribution, a good way to find the
limit is to search the internet for something like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
raise max open files hard limit debian
.ft P
.fi
.UNINDENT
.UNINDENT
.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
Worker threads should not be put below 3 when using the peer system, but can
drop down to 1 worker otherwise.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
worker_threads: 5
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ret_port: 4506
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBpidfile\fP
.sp
Default: \fB/var/run/salt\-master.pid\fP
.sp
Specify the location of the master pidfile
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pidfile: /var/run/salt\-master.pid
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBroot_dir\fP
.sp
Default: \fB/\fP
.sp
The system root directory to operate from, change this to make Salt run from
an alternative root.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root_dir: /
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This directory is prepended to the following options:
\fI\%pki_dir\fP, \fI\%cachedir\fP, \fI\%sock_dir\fP,
\fI\%log_file\fP, \fI\%autosign_file\fP,
\fI\%autoreject_file\fP, \fI\%pidfile\fP\&.
.UNINDENT
.UNINDENT
.SS \fBpki_dir\fP
.sp
Default: \fB/etc/salt/pki\fP
.sp
The directory to store the pki authentication keys.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pki_dir: /etc/salt/pki
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBextension_modules\fP
.sp
Directory for custom modules. This directory can contain subdirectories for
each of Salt\(aqs module types such as "runners", "output", "wheel", "modules",
"states", "returners", etc. This path is appended to \fI\%root_dir\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extension_modules: srv/modules
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cachedir: /var/cache/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBverify_env\fP
.sp
Default: \fBTrue\fP
.sp
Verify and set permissions on configuration directories at startup.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
verify_env: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBkeep_jobs\fP
.sp
Default: \fB24\fP
.sp
Set the number of hours to keep old job information
.SS \fBtimeout\fP
.sp
Default: \fB5\fP
.sp
Set the default timeout for the salt command and api.
.SS \fBloop_interval\fP
.sp
Default: \fB60\fP
.sp
The loop_interval option controls the seconds for the master\(aqs maintenance
process check cycle. This process updates file server backends, cleans the
job cache and executes the scheduler.
.SS \fBoutput\fP
.sp
Default: \fBnested\fP
.sp
Set the default outputter used by the salt command.
.SS \fBcolor\fP
.sp
Default: \fBTrue\fP
.sp
By default output is colored, to disable colored output set the color value
to False
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
color: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsock_dir\fP
.sp
Default: \fB/var/run/salt/master\fP
.sp
Set the location to use for creating Unix sockets for master process
communication
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sock_dir: /var/run/salt/master
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBenable_gpu_grains\fP
.sp
Default: \fBFalse\fP
.sp
The master can take a while to start up when lspci and/or dmidecode is used
to populate the grains for the master. Enable if you want to see GPU hardware
data for your master.
.SS \fBjob_cache\fP
.sp
Default: \fBTrue\fP
.sp
The master maintains a job cache, while this is a great addition it can be
a burden on the master for larger deployments (over 5000 minions).
Disabling the job cache will make previously executed jobs unavailable to
the jobs system and is not generally recommended. Normally it is wise to make
sure the master has access to a faster IO system or a tmpfs is mounted to the
jobs dir
.SS \fBminion_data_cache\fP
.sp
Default: \fBTrue\fP
.sp
The minion data cache is a cache of information about the minions stored on the
master, this information is primarily the pillar and grains data. The data is
cached in the Master cachedir under the name of the minion and used to pre
determine what minions are expected to reply from executions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
minion_data_cache: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBext_job_cache\fP
.sp
Default: \fB\(aq\(aq\fP
.sp
Used to specify a default returner for all minions, when this option is set
the specified returner needs to be properly configured and the minions will
always default to sending returns to this returner. This will also disable the
local job cache on the master
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_job_cache: redis
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_job_cache\fP
.sp
New in version 2014.7.
.sp
Default: \(aqlocal_cache\(aq
.sp
Specify the returner to use for ther job cache. The job cache will only be
interacted with from the salt master and therefore does not need to be
accesible from the minions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_job_cache: redis
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBenforce_mine_cache\fP
.sp
Default: False
.sp
By\-default when disabling the minion_data_cache mine will stop working since
it is based on cached data, by enabling this option we explicitly enabling
only the cache for the mine system.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
enforce_mine_cache: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmax_minions\fP
.sp
Default: 0
.sp
The number of minions the master should allow to connect. Use this to accommodate
the number of minions per master if you have different types of hardware serving
your minions. The default of \fB0\fP means unlimited connections. Please note, that
this can slow down the authentication process a bit in large setups.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
max_minions: 100
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBpresence_events\fP
.sp
Default: False
.sp
Causes the master to periodically look for actively connected minions.
\fIPresence events\fP are fired on the event bus on a
regular interval with a list of connected minions, as well as events with lists
of newly connected or disconnected minions. This is a master\-only operation
that does not send executions to minions. Note, this does not detect minions
that connect to a master via localhost.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
presence_events: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBroster_file\fP
.sp
Default: \(aq/etc/salt/roster\(aq
.sp
Pass in an alternative location for the salt\-ssh roster file
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
roster_file: /root/roster
.ft P
.fi
.UNINDENT
.UNINDENT
.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 set this value to \fBTrue\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
open_mode: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBauto_accept\fP
.sp
Default: \fBFalse\fP
.sp
Enable auto_accept. This setting will automatically accept all incoming
public keys from minions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
auto_accept: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBautosign_timeout\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB120\fP
.sp
Time in minutes that a incoming public key with a matching name found in
pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys
are removed when the master checks the minion_autosign directory. This method
to auto accept minions can be safer than an autosign_file because the
keyid record can expire and is limited to being an exact name match.
This should still be considered a less than secure option, due to the fact
that trust is based on just the requesting minion id.
.SS \fBautosign_file\fP
.sp
Default: \fBnot defined\fP
.sp
If the \fBautosign_file\fP is specified incoming keys specified in the autosign_file
will be automatically accepted. Matches will be searched for first by string
comparison, then by globbing, then by full\-string regex matching.
This should still be considered a less than secure option, due to the fact
that trust is based on just the requesting minion id.
.SS \fBautoreject_file\fP
.sp
New in version 2014.1.0.
.sp
Default: \fBnot defined\fP
.sp
Works like \fI\%autosign_file\fP, but instead allows you to specify
minion IDs for which keys will automatically be rejected. Will override both
membership in the \fI\%autosign_file\fP and the
\fI\%auto_accept\fP setting.
.SS \fBclient_acl\fP
.sp
Default: \fB{}\fP
.sp
Enable user accounts on the master to execute specific modules. These modules
can be expressed as regular expressions
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
client_acl:
fred:
\- test.ping
\- pkg.*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBclient_acl_blacklist\fP
.sp
Default: \fB{}\fP
.sp
Blacklist users or modules
.sp
This example would blacklist all non sudo users, including root from
running any commands. It would also blacklist any use of the "cmd"
module.
.sp
This is completely disabled by default.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
client_acl_blacklist:
users:
\- root
\- \(aq^(?!sudo_).*$\(aq # all non sudo users
modules:
\- cmd
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBexternal_auth\fP
.sp
Default: \fB{}\fP
.sp
The external auth system uses the Salt auth modules to authenticate and
validate users to access areas of the Salt system.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
fred:
\- test.*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBtoken_expire\fP
.sp
Default: \fB43200\fP
.sp
Time (in seconds) for a newly generated token to live. Default: 12 hours
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
token_expire: 43200
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBfile_recv\fP
.sp
Default: \fBFalse\fP
.sp
Allow minions to push files to the master. This is disabled by default, for
security purposes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_recv: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_sign_pubkey\fP
.sp
Default: \fBFalse\fP
.sp
Sign the master auth\-replies with a cryptographical signature of the masters
public key. Please see the tutorial how to use these settings in the
\fI\%Multimaster\-PKI with Failover Tutorial\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign_pubkey: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_sign_key_name\fP
.sp
Default: \fBmaster_sign\fP
.sp
The customizable name of the signing\-key\-pair without suffix.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign_key_name: <filename_without_suffix>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_pubkey_signature\fP
.sp
Default: \fBmaster_pubkey_signature\fP
.sp
The name of the file in the masters pki\-directory that holds the pre\-calculated
signature of the masters public\-key.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_pubkey_signature: <filename>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_use_pubkey_signature\fP
.sp
Default: \fBFalse\fP
.sp
Instead of computing the signature for each auth\-reply, use a pre\-calculated
signature. The \fI\%master_pubkey_signature\fP must also be set for this.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_use_pubkey_signature: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBrotate_aes_key\fP
.sp
Default: \fBTrue\fP
.sp
Rotate the salt\-masters AES\-key when a minion\-public is deleted with salt\-key.
This is a very important security\-setting. Disabling it will enable deleted
minions to still listen in on the messages published by the salt\-master.
Do not disable this unless it is absolutely clear what this does.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rotate_aes_key: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Master Module Management
.SS \fBrunner_dirs\fP
.sp
Default: \fB[]\fP
.sp
Set additional directories to search for runner modules
.SS \fBcython_enable\fP
.sp
Default: \fBFalse\fP
.sp
Set to true to enable Cython modules (.pyx files) to be compiled on the fly on
the Salt master
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cython_enable: False
.ft P
.fi
.UNINDENT
.UNINDENT
.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
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_top: top.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_tops\fP
.sp
Default: \fB{}\fP
.sp
The master_tops option replaces the external_nodes option by creating
a pluggable system for the generation of external top data. The external_nodes
option is deprecated by the master_tops option.
To gain the capabilities of the classic external_nodes system, use the
following configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
ext_nodes: <Shell command which returns yaml>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBexternal_nodes\fP
.sp
Default: None
.sp
The external_nodes option allows Salt to gather data that would normally be
placed in a top file from and external node controller. The external_nodes
option is the executable that will return the ENC data. Remember that Salt
will look for external nodes AND top files and combine the results if both
are enabled and available!
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_nodes: cobbler\-ext\-nodes
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBrenderer\fP
.sp
Default: \fByaml_jinja\fP
.sp
The renderer to use on the minions to render the state data
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
renderer: yaml_jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBfailhard\fP
.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
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
failhard: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBstate_verbose\fP
.sp
Default: \fBTrue\fP
.sp
Controls the verbosity of state runs. By default, the results of all states are
returned, but setting this value to \fBFalse\fP will cause salt to only display
output for states which either failed, or succeeded without making any changes
to the minion.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_verbose: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBstate_output\fP
.sp
Default: \fBfull\fP
.sp
The state_output setting changes if the output is the full multi line
output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq
the output will be shortened to a single line. If set to \(aqmixed\(aq, the output
will be terse unless a state failed, in which case that output will be full.
If set to \(aqchanges\(aq, the output will be full unless the state didn\(aqt change.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_output: full
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fByaml_utf8\fP
.sp
Default: \fBFalse\fP
.sp
Enable extra routines for yaml renderer used states containing UTF characters
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
yaml_utf8: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBtest\fP
.sp
Default: \fBFalse\fP
.sp
Set all state calls to only test if they are going to actually make changes
or just post what changes are going to be made
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
test: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Master File Server Settings
.SS \fBfileserver_backend\fP
.sp
Default: \fB[\(aqroots\(aq]\fP
.sp
Salt supports a modular fileserver backend system, this system allows the salt
master to link directly to third party systems to gather and manage the files
available to minions. Multiple backends can be configured and will be searched
for the requested file in the order in which they are defined here. The default
setting only enables the standard backend \fBroots\fP, which is configured using
the \fI\%file_roots\fP option.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- roots
\- git
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hash_type: md5
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBfile_buffer_size\fP
.sp
Default: \fB1048576\fP
.sp
The buffer size in the file server in bytes
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_buffer_size: 1048576
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBfile_ignore_regex\fP
.sp
Default: \fB\(aq\(aq\fP
.sp
A regular expression (or a list of expressions) that will be matched
against the file path before syncing the modules and states to the minions.
This includes files affected by the file.recurse state.
For example, if you manage your custom modules and states in subversion
and don\(aqt want all the \(aq.svn\(aq folders and content synced to your minions,
you could set this to \(aq/.svn($|/)\(aq. By default nothing is ignored.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_ignore_regex:
\- \(aq/\e.svn($|/)\(aq
\- \(aq/\e.git($|/)\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBfile_ignore_glob\fP
.sp
Default \fB\(aq\(aq\fP
.sp
A file glob (or list of file globs) that will be matched against the file
path before syncing the modules and states to the minions. This is similar
to file_ignore_regex above, but works on globs instead of regex. By default
nothing is ignored.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_ignore_glob:
\- \(aq\e*.pyc\(aq
\- \(aq\e*/somefolder/\e*.bak\(aq
\- \(aq\e*.swp\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS roots: Master\(aqs Local File Server
.SS \fBfile_roots\fP
.sp
Default:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\- /srv/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.sp
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:
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.SS git: Git Remote File Server Backend
.SS \fBgitfs_remotes\fP
.sp
Default: \fB[]\fP
.sp
When using the \fBgit\fP fileserver backend at least one git remote needs to be
defined. The user running the salt master will need read access to the repo.
.sp
The repos will be searched in order to find the file requested by a client and
the first repo to have the file will return it. Branches and tags are
translated into salt environments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- git://github.com/saltstack/salt\-states.git
\- file:///var/git/saltmaster
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBfile://\fP repos will be treated as a remote and copied into the master\(aqs
gitfs cache, so only the \fIlocal\fP refs for those repos will be exposed as
fileserver environments.
.UNINDENT
.UNINDENT
.sp
As of 2014.7.0, it is possible to have per\-repo versions of several of the
gitfs configuration parameters. For more information, see the \fIGitFS
Walkthrough\fP\&.
.SS \fBgitfs_provider\fP
.sp
New in version 2014.7.0.
.sp
Specify the provider to be used for gitfs. More information can be found in the
\fIGitFS Walkthrough\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_provider: dulwich
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_ssl_verify\fP
.sp
Default: \fBTrue\fP
.sp
The \fBgitfs_ssl_verify\fP option specifies whether to ignore SSL certificate
errors when contacting the gitfs backend. You might want to set this to false
if you\(aqre using a git backend that uses a self\-signed certificate but keep in
mind that setting this flag to anything other than the default of \fBTrue\fP is a
security concern, you may want to try using the ssh transport.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_ssl_verify: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_mountpoint\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Specifies a path on the salt fileserver from which gitfs remotes are served.
Can be used in conjunction with \fI\%gitfs_root\fP\&. Can also be
configured on a per\-remote basis, see \fIhere\fP for
more info.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_mountpoint: salt://foo/bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBsalt://\fP protocol designation can be left off (in other words,
\fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent).
.UNINDENT
.UNINDENT
.SS \fBgitfs_root\fP
.sp
Default: \fB\(aq\(aq\fP
.sp
Serve files from a subdirectory within the repository, instead of the root.
This is useful when there are files in the repository that should not be
available to the Salt fileserver. Can be used in conjunction with
\fI\%gitfs_mountpoint\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_root: somefolder/otherfolder
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: Ability to specify gitfs roots on a per\-remote basis was added. See
\fIhere\fP for more info.
.SS \fBgitfs_base\fP
.sp
Default: \fBmaster\fP
.sp
Defines which branch/tag should be used as the \fBbase\fP environment.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_base: salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: Ability to specify the base on a per\-remote basis was added. See \fIhere\fP for more info.
.SS \fBgitfs_env_whitelist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which environments are made available. Can speed up state runs
if the repos in \fI\%gitfs_remotes\fP contain many branches/tags. More
information can be found in the \fIGitFS Walkthrough\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_env_whitelist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_env_blacklist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which environments are made available. Can speed up state runs
if the repos in \fI\%gitfs_remotes\fP contain many branches/tags. More
information can be found in the \fIGitFS Walkthrough\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_env_blacklist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS GitFS Authentication Options
.sp
These parameters only currently apply to the pygit2 gitfs provider. Examples of
how to use these can be found in the \fIGitFS Walkthrough\fP\&.
.SS \fBgitfs_user\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Along with \fI\%gitfs_password\fP, is used to authenticate to HTTPS
remotes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_user: git
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_password\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Along with \fI\%gitfs_user\fP, is used to authenticate to HTTPS remotes.
This parameter is not required if the repository does not use authentication.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_password: mypassword
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_insecure_auth\fP
.sp
New in version 2014.7.0.
.sp
Default: \fBFalse\fP
.sp
By default, Salt will not authenticate to an HTTP (non\-HTTPS) remote. This
parameter enables authentication over HTTP. \fBEnable this at your own risk.\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_insecure_auth: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_pubkey\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Along with \fI\%gitfs_privkey\fP (and optionally
\fI\%gitfs_passphrase\fP), is used to authenticate to SSH remotes. This
parameter (or its \fIper\-remote counterpart\fP) is
required for SSH remotes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_pubkey: /path/to/key.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_privkey\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Along with \fI\%gitfs_pubkey\fP (and optionally
\fI\%gitfs_passphrase\fP), is used to authenticate to SSH remotes. This
parameter (or its \fIper\-remote counterpart\fP) is
required for SSH remotes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_privkey: /path/to/key
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgitfs_passphrase\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
This parameter is optional, required only when the SSH key being used to
authenticate is protected by a passphrase.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_passphrase: mypassphrase
.ft P
.fi
.UNINDENT
.UNINDENT
.SS hg: Mercurial Remote File Server Backend
.SS \fBhgfs_remotes\fP
.sp
New in version 0.17.0.
.sp
Default: \fB[]\fP
.sp
When using the \fBhg\fP fileserver backend at least one mercurial remote needs to
be defined. The user running the salt master will need read access to the repo.
.sp
The repos will be searched in order to find the file requested by a client and
the first repo to have the file will return it. Branches and/or bookmarks are
translated into salt environments, as defined by the
\fI\%hgfs_branch_method\fP parameter.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_remotes:
\- https://username@bitbucket.org/username/reponame
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
As of 2014.7.0, it is possible to have per\-repo versions of the
\fI\%hgfs_root\fP, \fI\%hgfs_mountpoint\fP,
\fI\%hgfs_base\fP, and \fI\%hgfs_branch_method\fP parameters.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_remotes:
\- https://username@bitbucket.org/username/repo1
\- base: saltstates
\- https://username@bitbucket.org/username/repo2:
\- root: salt
\- mountpoint: salt://foo/bar/baz
\- https://username@bitbucket.org/username/repo3:
\- root: salt/states
\- branch_method: mixed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fBhgfs_branch_method\fP
.sp
New in version 0.17.0.
.sp
Default: \fBbranches\fP
.sp
Defines the objects that will be used as fileserver environments.
.INDENT 0.0
.IP \(bu 2
\fBbranches\fP \- Only branches and tags will be used
.IP \(bu 2
\fBbookmarks\fP \- Only bookmarks and tags will be used
.IP \(bu 2
\fBmixed\fP \- Branches, bookmarks, and tags will be used
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_branch_method: mixed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Starting in version 2014.1.0, the value of the \fI\%hgfs_base\fP
parameter defines which branch is used as the \fBbase\fP environment,
allowing for a \fBbase\fP environment to be used with an
\fI\%hgfs_branch_method\fP of \fBbookmarks\fP\&.
.sp
Prior to this release, the \fBdefault\fP branch will be used as the \fBbase\fP
environment.
.UNINDENT
.UNINDENT
.SS \fBhgfs_mountpoint\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Specifies a path on the salt fileserver from which hgfs remotes are served.
Can be used in conjunction with \fI\%hgfs_root\fP\&. Can also be
configured on a per\-remote basis, see \fI\%here\fP for
more info.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_mountpoint: salt://foo/bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBsalt://\fP protocol designation can be left off (in other words,
\fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent).
.UNINDENT
.UNINDENT
.SS \fBhgfs_root\fP
.sp
New in version 0.17.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Serve files from a subdirectory within the repository, instead of the root.
This is useful when there are files in the repository that should not be
available to the Salt fileserver. Can be used in conjunction with
\fI\%hgfs_mountpoint\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_root: somefolder/otherfolder
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: Ability to specify hgfs roots on a per\-remote basis was added. See
\fI\%here\fP for more info.
.SS \fBhgfs_base\fP
.sp
New in version 2014.1.0.
.sp
Default: \fBdefault\fP
.sp
Defines which branch should be used as the \fBbase\fP environment. Change this if
\fI\%hgfs_branch_method\fP is set to \fBbookmarks\fP to specify which
bookmark should be used as the \fBbase\fP environment.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_base: salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBhgfs_env_whitelist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which environments are made available. Can speed up state runs
if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs,
and regular expressions are supported. If using a regular expression, the
expression must match the entire minion ID.
.sp
If used, only branches/bookmarks/tags which match one of the specified
expressions will be exposed as fileserver environments.
.sp
If used in conjunction with \fI\%hgfs_env_blacklist\fP, then the subset
of branches/bookmarks/tags which match the whitelist but do \fInot\fP match the
blacklist will be exposed as fileserver environments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_env_whitelist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBhgfs_env_blacklist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which environments are made available. Can speed up state runs
if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs,
and regular expressions are supported. If using a regular expression, the
expression must match the entire minion ID.
.sp
If used, branches/bookmarks/tags which match one of the specified expressions
will \fInot\fP be exposed as fileserver environments.
.sp
If used in conjunction with \fI\%hgfs_env_whitelist\fP, then the subset
of branches/bookmarks/tags which match the whitelist but do \fInot\fP match the
blacklist will be exposed as fileserver environments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hgfs_env_blacklist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS svn: Subversion Remote File Server Backend
.SS \fBsvnfs_remotes\fP
.sp
New in version 0.17.0.
.sp
Default: \fB[]\fP
.sp
When using the \fBsvn\fP fileserver backend at least one subversion remote needs
to be defined. The user running the salt master will need read access to the
repo.
.sp
The repos will be searched in order to find the file requested by a client and
the first repo to have the file will return it. The trunk, branches, and tags
become environments, with the trunk being the \fBbase\fP environment.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_remotes:
\- svn://foo.com/svn/myproject
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
As of 2014.7.0, it is possible to have per\-repo versions of the following
configuration parameters:
.INDENT 0.0
.IP \(bu 2
\fI\%svnfs_root\fP
.IP \(bu 2
\fI\%svnfs_mountpoint\fP
.IP \(bu 2
\fI\%svnfs_trunk\fP
.IP \(bu 2
\fI\%svnfs_branches\fP
.IP \(bu 2
\fI\%svnfs_tags\fP
.UNINDENT
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_remotes:
\- svn://foo.com/svn/project1
\- svn://foo.com/svn/project2:
\- root: salt
\- mountpoint: salt://foo/bar/baz
\- svn//foo.com/svn/project3:
\- root: salt/states
\- branches: branch
\- tags: tag
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fBsvnfs_mountpoint\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Specifies a path on the salt fileserver from which svnfs remotes are served.
Can be used in conjunction with \fI\%svnfs_root\fP\&. Can also be
configured on a per\-remote basis, see \fI\%here\fP for
more info.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_mountpoint: salt://foo/bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBsalt://\fP protocol designation can be left off (in other words,
\fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent).
.UNINDENT
.UNINDENT
.SS \fBsvnfs_root\fP
.sp
New in version 0.17.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Serve files from a subdirectory within the repository, instead of the root.
This is useful when there are files in the repository that should not be
available to the Salt fileserver. Can be used in conjunction with
\fI\%svnfs_mountpoint\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_root: somefolder/otherfolder
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: Ability to specify svnfs roots on a per\-remote basis was added. See
\fI\%here\fP for more info.
.SS \fBsvnfs_trunk\fP
.sp
New in version 2014.7.0.
.sp
Default: \fBtrunk\fP
.sp
Path relative to the root of the repository where the trunk is located. Can
also be configured on a per\-remote basis, see \fI\%here\fP for more info.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_trunk: trunk
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsvnfs_branches\fP
.sp
New in version 2014.7.0.
.sp
Default: \fBbranches\fP
.sp
Path relative to the root of the repository where the branches are located. Can
also be configured on a per\-remote basis, see \fI\%here\fP for more info.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_branches: branches
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsvnfs_tags\fP
.sp
New in version 2014.7.0.
.sp
Default: \fBtags\fP
.sp
Path relative to the root of the repository where the tags are located. Can
also be configured on a per\-remote basis, see \fI\%here\fP for more info.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_tags: tags
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsvnfs_env_whitelist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which environments are made available. Can speed up state runs
if your svnfs remotes contain many branches/tags. Full names, globs, and
regular expressions are supported. If using a regular expression, the expression
must match the entire minion ID.
.sp
If used, only branches/tags which match one of the specified expressions will
be exposed as fileserver environments.
.sp
If used in conjunction with \fI\%svnfs_env_blacklist\fP, then the subset
of branches/tags which match the whitelist but do \fInot\fP match the blacklist
will be exposed as fileserver environments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_env_whitelist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsvnfs_env_blacklist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which environments are made available. Can speed up state runs
if your svnfs remotes contain many branches/tags. Full names, globs, and
regular expressions are supported. If using a regular expression, the
expression must match the entire minion ID.
.sp
If used, branches/tags which match one of the specified expressions will \fInot\fP
be exposed as fileserver environments.
.sp
If used in conjunction with \fI\%svnfs_env_whitelist\fP, then the subset
of branches/tags which match the whitelist but do \fInot\fP match the blacklist
will be exposed as fileserver environments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
svnfs_env_blacklist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS minion: MinionFS Remote File Server Backend
.SS \fBminionfs_env\fP
.sp
New in version 2014.7.0.
.sp
Default: \fBbase\fP
.sp
Environment from which MinionFS files are made available.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
minionfs_env: minionfs
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBminionfs_mountpoint\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB\(aq\(aq\fP
.sp
Specifies a path on the salt fileserver from which minionfs files are served.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
minionfs_mountpoint: salt://foo/bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBsalt://\fP protocol designation can be left off (in other words,
\fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent).
.UNINDENT
.UNINDENT
.SS \fBminionfs_whitelist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which minions\(aq pushed files are exposed via minionfs. If using
a regular expression, the expression must match the entire minion ID.
.sp
If used, only the pushed files from minions which match one of the specified
expressions will be exposed.
.sp
If used in conjunction with \fI\%minionfs_blacklist\fP, then the subset
of hosts which match the whitelist but do \fInot\fP match the blacklist will be
exposed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
minionfs_whitelist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBminionfs_blacklist\fP
.sp
New in version 2014.7.0.
.sp
Default: \fB[]\fP
.sp
Used to restrict which minions\(aq pushed files are exposed via minionfs. If using
a regular expression, the expression must match the entire minion ID.
.sp
If used, only the pushed files from minions which match one of the specified
expressions will \fInot\fP be exposed.
.sp
If used in conjunction with \fI\%minionfs_whitelist\fP, then the subset
of hosts which match the whitelist but do \fInot\fP match the blacklist will be
exposed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
minionfs_blacklist:
\- base
\- v1.*
\- \(aqmybranch\ed+\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Pillar Configuration
.SS \fBpillar_roots\fP
.sp
Default:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\- /srv/pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Set the environments and directories used to hold pillar sls data. This
configuration is the same as \fI\%file_roots\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pillar_roots:
base:
\- /srv/pillar
dev:
\- /srv/pillar/dev
prod:
\- /srv/pillar/prod
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBext_pillar\fP
.sp
The ext_pillar option allows for any number of external pillar interfaces to be
called when populating pillar data. The configuration is based on ext_pillar
functions. The available ext_pillar functions can be found herein:
.sp
\fI\%https://github.com/saltstack/salt/blob/develop/salt/pillar\fP
.sp
By default, the ext_pillar interface is not configured to run.
.sp
Default: \fBNone\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- hiera: /etc/hiera.yaml
\- cmd_yaml: cat /etc/salt/yaml
\- reclass:
inventory_base_uri: /etc/reclass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There are additional details at \fIsalt\-pillars\fP
.SS \fBpillar_source_merging_strategy\fP
.sp
Default: \fBsmart\fP
.sp
The pillar_source_merging_strategy option allows to configure merging strategy
between different sources. It accepts 3 values:
.INDENT 0.0
.IP \(bu 2
recurse:
.sp
it will merge recursively mapping of data. For example, theses 2 sources:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
foo: 42
bar:
element1: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
bar:
element2: True
baz: quux
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will be merged as:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
foo: 42
bar:
element1: True
element2: True
baz: quux
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
aggregate:
.sp
instructs aggregation of elements between sources that use the #!yamlex rendered.
.sp
For example, these two documents:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!yamlex
foo: 42
bar: !aggregate {
element1: True
}
baz: !aggregate quux
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!yamlex
bar: !aggregate {
element2: True
}
baz: !aggregate quux2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will be merged as:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
foo: 42
bar:
element1: True
element2: True
baz:
\- quux
\- quux2
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
overwrite:
.INDENT 2.0
.INDENT 3.5
Will use the behaviour of the 2014.1 branch and earlier.
.sp
Overwrites elements according the order in which they are processed.
.sp
First pillar processed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A:
first_key: blah
second_key: blah
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Second pillar processed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A:
third_key: blah
fourth_key: blah
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will be merged as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A:
third_key: blah
fourth_key: blah
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
smart (default):
.INDENT 2.0
.INDENT 3.5
Guesses the best strategy based on the "renderer" setting.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Syndic Server Settings
.sp
A Salt syndic is a Salt master used to pass commands from a higher Salt master to
minions below the syndic. Using the syndic is simple. If this is a master that
will have syndic servers(s) below it, set the "order_masters" setting to True. If this
is a master that will be running a syndic daemon for passthrough the
"syndic_master" setting needs to be set to the location of the master server
.sp
Do not not forget that in other word it means that it shares with the local minion it\(aqs ID and PKI_DIR.
.SS \fBorder_masters\fP
.sp
Default: \fBFalse\fP
.sp
Extra data needs to be sent with publications if the master is controlling a
lower level master via a syndic minion. If this is the case the order_masters
value must be set to True
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
order_masters: False
.ft P
.fi
.UNINDENT
.UNINDENT
.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
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
syndic_master: masterofmasters
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsyndic_master_port\fP
.sp
Default: \fB4506\fP
.sp
If this master will be running a salt\-syndic to connect to a higher level
master, specify the higher level master port with this configuration value
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
syndic_master_port: 4506
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsyndic_pidfile\fP
.sp
Default: \fBsalt\-syndic.pid\fP
.sp
If this master will be running a salt\-syndic to connect to a higher level
master, specify the pidfile of the syndic daemon.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
syndic_pidfile: syndic.pid
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsyndic_log_file\fP
.sp
Default: \fBsyndic.log\fP
.sp
If this master will be running a salt\-syndic to connect to a higher level
master, specify the log_file of the syndic daemon.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
syndic_log_file: salt\-syndic.log
.ft P
.fi
.UNINDENT
.UNINDENT
.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
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer:
foo.example.com:
\- test.*
\- pkg.*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will allow all minions to execute all commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer:
.*:
\- .*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is not recommended, since it would allow anyone who gets root on any
single minion to instantly have root on all of the minions!
.sp
By adding an additional layer you can limit the target hosts in addition to the
accessible commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer:
foo.example.com:
\(aqdb*\(aq:
\- test.*
\- pkg.*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBpeer_run\fP
.sp
Default: \fB{}\fP
.sp
The peer_run option is used to open up runners on the master to access from the
minions. The peer_run configuration matches the format of the peer
configuration.
.sp
The following example would allow foo.example.com to execute the manage.up
runner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer_run:
foo.example.com:
\- manage.up
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Master Logging Settings
.SS \fBlog_file\fP
.sp
Default: \fB/var/log/salt/master\fP
.sp
The master log can be sent to a regular file, local path name, or network
location. See also \fBlog_file\fP\&.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: /var/log/salt/master
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: file:///dev/log
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: udp://loghost:10514
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_level\fP
.sp
Default: \fBwarning\fP
.sp
The level of messages to send to the console. See also \fBlog_level\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_level: warning
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_level_logfile\fP
.sp
Default: \fBwarning\fP
.sp
The level of messages to send to the log file. See also
\fBlog_level_logfile\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_level_logfile: warning
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_datefmt\fP
.sp
Default: \fB%H:%M:%S\fP
.sp
The date and time format used in console log messages. See also
\fBlog_datefmt\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_datefmt: \(aq%H:%M:%S\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_datefmt_logfile\fP
.sp
Default: \fB%Y\-%m\-%d %H:%M:%S\fP
.sp
The date and time format used in log file messages. See also
\fBlog_datefmt_logfile\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_fmt_console\fP
.sp
Default: \fB[%(levelname)\-8s] %(message)s\fP
.sp
The format of the console logging messages. See also
\fBlog_fmt_console\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_fmt_logfile\fP
.sp
Default: \fB%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\fP
.sp
The format of the log file logging messages. See also
\fBlog_fmt_logfile\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_granular_levels\fP
.sp
Default: \fB{}\fP
.sp
This can be used to control logging levels more specifically. See also
\fBlog_granular_levels\fP\&.
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nodegroups:
group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com\(aq
group2: \(aqG@os:Debian and foo.domain.com\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Range Cluster Settings
.SS \fBrange_server\fP
.sp
Default: \fB\(aq\(aq\fP
.sp
The range server (and optional port) that serves your cluster information
\fI\%https://github.com/ytoolshed/range/wiki/%22yamlfile%22\-module\-file\-spec\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
range_server: range:80
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Include Configuration
.SS \fBdefault_include\fP
.sp
Default: \fBmaster.d/*.conf\fP
.sp
The master can include configuration from other files. Per default the
master will automatically include all config files from \fBmaster.d/*.conf\fP
where \fBmaster.d\fP is relative to the directory of the master configuration
file.
.SS \fBinclude\fP
.sp
Default: \fBnot defined\fP
.sp
The master can include configuration from other files. To enable this,
pass a list of paths to this option. The paths can be either relative or
absolute; if relative, they are considered to be relative to the directory
the main minion configuration file lives in. Paths can make use of
shell\-style globbing. If no files are matched by a path passed to this
option then the master will log a warning message.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Include files from a master.d directory in the same
# directory as the master config file
include: master.d/*
# Include a single extra file into the configuration
include: /etc/roles/webserver
# Include several files and the master.d directory
include:
\- extra_config
\- master.d/*
\- /etc/roles/webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Windows Software Repo Settings
.SS \fBwin_repo\fP
.sp
Default: \fB/srv/salt/win/repo\fP
.sp
Location of the repo on the master
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
win_repo: \(aq/srv/salt/win/repo\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBwin_repo_mastercachefile\fP
.sp
Default: \fB/srv/salt/win/repo/winrepo.p\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
win_repo_mastercachefile: \(aq/srv/salt/win/repo/winrepo.p\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBwin_gitrepos\fP
.sp
Default: \fB\(aq\(aq\fP
.sp
List of git repositories to include with the local repo
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
win_gitrepos:
\- \(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS 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.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIexample minion configuration file\fP
.UNINDENT
.UNINDENT
.sp
The Salt Minion configuration is very simple. Typically, the only value that
needs to be set is the master value so the minion knows where to locate its master.
.sp
By default, the salt\-minion configuration will be in \fB/etc/salt/minion\fP\&.
A notable exception is FreeBSD, where the configuration will be in
\fB/usr/local/etc/salt/minion\fP\&.
.SS Minion Primary Configuration
.SS \fBmaster\fP
.sp
Default: \fBsalt\fP
.sp
The hostname or ipv4 of the master.
.sp
Default: \fBsalt\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master: salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The option can can also be set to a list of masters, enabling
\fBmulti\-master\fP mode.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master:
\- address1
\- address2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: The master can be dynamically configured. The \fI\%master\fP value
can be set to an module function which will be executed and will assume
that the returning value is the ip or hostname of the desired master. If a
function is being specified, then the \fI\%master_type\fP option
must be set to \fBfunc\fP, to tell the minion that the value is a function to
be run and not a fully\-qualified domain name.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master: module.function
master_type: func
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In addition, instead of using multi\-master mode, the minion can be
configured to use the list of master addresses as a failover list, trying
the first address, then the second, etc. until the minion successfully
connects. To enable this behavior, set \fI\%master_type\fP to
\fBfailover\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master:
\- address1
\- address2
master_type: failover
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_type\fP
.sp
New in version 2014.7.0.
.sp
Default: \fBstr\fP
.sp
The type of the \fI\%master\fP variable. Can be either \fBfunc\fP or
\fBfailover\fP\&.
.sp
If the master needs to be dynamically assigned by executing a function instead
of reading in the static master value, set this to \fBfunc\fP\&. This can be used
to manage the minion\(aqs master setting from an execution module. By simply
changing the algorithm in the module to return a new master ip/fqdn, restart
the minion and it will connect to the new master.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_type: func
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this option is set to \fBfailover\fP, \fI\%master\fP must be a list of
master addresses. The minion will then try each master in the order specified
in the list until it successfully connects.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_type: failover
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmaster_shuffle\fP
.sp
New in version 2014.7.0.
.sp
Default: \fBFalse\fP
.sp
If \fI\%master\fP is a list of addresses, shuffle them before trying to
connect to distribute the minions over all available masters. This uses
Python\(aqs \fI\%random.shuffle\fP method.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_shuffle: True
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_port: 4506
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBuser\fP
.sp
Default: \fBroot\fP
.sp
The user to run the Salt processes
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
user: root
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBpidfile\fP
.sp
Default: \fB/var/run/salt\-minion.pid\fP
.sp
The location of the daemon\(aqs process ID file
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pidfile: /var/run/salt\-minion.pid
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBroot_dir\fP
.sp
Default: \fB/\fP
.sp
This directory is prepended to the following options: \fI\%pki_dir\fP,
\fI\%cachedir\fP, \fI\%log_file\fP, \fI\%sock_dir\fP, and
\fI\%pidfile\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root_dir: /
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBpki_dir\fP
.sp
Default: \fB/etc/salt/pki\fP
.sp
The directory used to store the minion\(aqs public and private keys.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pki_dir: /etc/salt/pki
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBid\fP
.sp
Default: the system\(aqs hostname
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fISalt Walkthrough\fP
.sp
The \fBSetting up a Salt Minion\fP section contains detailed
information on how the hostname is determined.
.UNINDENT
.UNINDENT
.sp
Explicitly declare the id for this minion to use. Since Salt uses detached ids
it is possible to run multiple minions on the same machine but with different
ids.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
id: foo.bar.com
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBappend_domain\fP
.sp
Default: \fBNone\fP
.sp
Append a domain to a hostname in the event that it does not exist. This is
useful for systems where \fBsocket.getfqdn()\fP does not actually result in a
FQDN (for instance, Solaris).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
append_domain: foo.org
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBcachedir\fP
.sp
Default: \fB/var/cache/salt\fP
.sp
The location for minion cache data.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cachedir: /var/cache/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBverify_env\fP
.sp
Default: \fBTrue\fP
.sp
Verify and set permissions on configuration directories at startup.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
verify_env: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When marked as True the verify_env option requires WRITE access to the
configuration directory (/etc/salt/). In certain situations such as
mounting /etc/salt/ as read\-only for templating this will create a
stack trace when state.highstate is called.
.UNINDENT
.UNINDENT
.SS \fBcache_jobs\fP
.sp
Default: \fBFalse\fP
.sp
The minion can locally cache the return data from jobs sent to it, this can be
a good way to keep track of the minion side of the jobs the minion has
executed. By default this feature is disabled, to enable set cache_jobs to
\fBTrue\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cache_jobs: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBsock_dir\fP
.sp
Default: \fB/var/run/salt/minion\fP
.sp
The directory where Unix sockets will be kept.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sock_dir: /var/run/salt/minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBbackup_mode\fP
.sp
Default: \fB[]\fP
.sp
Backup files replaced by file.managed and file.recurse under cachedir.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
backup_mode: minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBacceptance_wait_time\fP
.sp
Default: \fB10\fP
.sp
The number of seconds to wait until attempting to re\-authenticate with the
master.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
acceptance_wait_time: 10
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBrandom_reauth_delay\fP
.sp
When the master key changes, the minion will try to re\-auth itself to
receive the new master key. In larger environments this can cause a syn\-flood
on the master because all minions try to re\-auth immediately. To prevent this
and have a minion wait for a random amount of time, use this optional
parameter. The wait\-time will be a random number of seconds between
0 and the defined value.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
random_reauth_delay: 60
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBacceptance_wait_time_max\fP
.sp
Default: \fBNone\fP
.sp
The maximum number of seconds to wait until attempting to re\-authenticate
with the master. If set, the wait will increase by acceptance_wait_time
seconds each iteration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
acceptance_wait_time_max: None
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBrecon_default\fP
.sp
Default: \fB1000\fP
.sp
The interval in milliseconds that the socket should wait before trying to
reconnect to the master (1000ms = 1 second).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
recon_default: 1000
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBrecon_max\fP
.sp
Default: \fB10000\fP
.sp
The maximum time a socket should wait. Each interval the time to wait is calculated
by doubling the previous time. If recon_max is reached, it starts again at
the recon_default.
.INDENT 0.0
.TP
.B Short example:
.INDENT 7.0
.IP \(bu 2
reconnect 1: the socket will wait \(aqrecon_default\(aq milliseconds
.IP \(bu 2
reconnect 2: \(aqrecon_default\(aq * 2
.IP \(bu 2
reconnect 3: (\(aqrecon_default\(aq * 2) * 2
.IP \(bu 2
reconnect 4: value from previous interval * 2
.IP \(bu 2
reconnect 5: value from previous interval * 2
.IP \(bu 2
reconnect x: if value >= recon_max, it starts again with recon_default
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
recon_max: 10000
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBrecon_randomize\fP
.sp
Default: \fBTrue\fP
.sp
Generate a random wait time on minion start. The wait time will be a random value
between recon_default and recon_default and recon_max. Having all minions reconnect
with the same recon_default and recon_max value kind of defeats the purpose of being
able to change these settings. If all minions have the same values and the setup is
quite large (several thousand minions), they will still flood the master. The desired
behavior is to have time\-frame within all minions try to reconnect.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
recon_randomize: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBdns_check\fP
.sp
Default: \fBTrue\fP
.sp
When healing, a dns_check is run. This is to make sure that the originally
resolved dns has not changed. If this is something that does not happen in your
environment, set this value to \fBFalse\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dns_check: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBipc_mode\fP
.sp
Default: \fBipc\fP
.sp
Windows platforms lack POSIX IPC and must rely on slower TCP based inter\-
process communications. Set ipc_mode to \fBtcp\fP on such systems.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ipc_mode: ipc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBtcp_pub_port\fP
.sp
Default: \fB4510\fP
.sp
Publish port used when \fI\%ipc_mode\fP is set to \fBtcp\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tcp_pub_port: 4510
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBtcp_pull_port\fP
.sp
Default: \fB4511\fP
.sp
Pull port used when \fI\%ipc_mode\fP is set to \fBtcp\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tcp_pull_port: 4511
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
disable_modules:
\- test
\- solr
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBdisable_returners\fP
.sp
Default: \fB[]\fP (all returners are enabled by default)
.sp
If certain returners should be disabled, this is the place
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
disable_returners:
\- mongo_return
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBmodule_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for Salt modules
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
module_dirs:
\- /var/lib/salt/modules
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBreturner_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for Salt returners
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
returners_dirs:
\- /var/lib/salt/returners
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBstates_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for Salt states
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
states_dirs:
\- /var/lib/salt/states
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBgrains_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for Salt grains
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
grains_dirs:
\- /var/lib/salt/grains
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBrender_dirs\fP
.sp
Default: \fB[]\fP
.sp
A list of extra directories to search for Salt renderers
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
render_dirs:
\- /var/lib/salt/renderers
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBcython_enable\fP
.sp
Default: \fBFalse\fP
.sp
Set this value to true to enable auto\-loading and compiling of \fB\&.pyx\fP modules,
This setting requires that \fBgcc\fP and \fBcython\fP are installed on the minion
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cython_enable: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBproviders\fP
.sp
Default: (empty)
.sp
A module provider can be statically overwritten or extended for the minion via
the \fBproviders\fP option. This can be done \fBon an individual basis in an
SLS file\fP, or globally here in the minion config, like
below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
providers:
service: systemd
.ft P
.fi
.UNINDENT
.UNINDENT
.SS State Management Settings
.SS \fBrenderer\fP
.sp
Default: \fByaml_jinja\fP
.sp
The default renderer used for local state executions
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
renderer: yaml_jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBstate_verbose\fP
.sp
Default: \fBFalse\fP
.sp
state_verbose allows for the data returned from the minion to be more
verbose. Normally only states that fail or states that have changes are
returned, but setting state_verbose to \fBTrue\fP will return all states that
were checked
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_verbose: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBstate_output\fP
.sp
Default: \fBfull\fP
.sp
The state_output setting changes if the output is the full multi line
output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq
the output will be shortened to a single line.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_output: full
.ft P
.fi
.UNINDENT
.UNINDENT
.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
auto\-loading modules when states run set this value to \fBFalse\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
autoload_dynamic_modules: True
.ft P
.fi
.UNINDENT
.UNINDENT
.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 \fBFalse\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
clean_dynamic_modules: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBenvironment\fP
.sp
Default: \fBNone\fP
.sp
Normally the minion is not isolated to any single environment on the master
when running states, but the environment can be isolated on the minion side
by statically setting it. Remember that the recommended way to manage
environments is to isolate via the top file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
environment: None
.ft P
.fi
.UNINDENT
.UNINDENT
.SS File Directory Settings
.SS \fBfile_client\fP
.sp
Default: \fBremote\fP
.sp
The client defaults to looking on the master server for files, but can be
directed to look on the minion by setting this parameter to \fBlocal\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_client: remote
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBfile_roots\fP
.sp
Default:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\- /srv/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When using a local \fI\%file_client\fP, this parameter is used to setup
the fileserver\(aqs environments. This parameter operates identically to the
\fBmaster config parameter\fP of the same name.
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.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
local fileserver. The default is md5, but sha1, sha224, sha256, sha384 and
sha512 are also supported.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
hash_type: md5
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBpillar_roots\fP
.sp
Default:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\- /srv/pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When using a local \fI\%file_client\fP, this parameter is used to setup
the pillar environments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pillar_roots:
base:
\- /srv/pillar
dev:
\- /srv/pillar/dev
prod:
\- /srv/pillar/prod
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
open_mode: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBverify_master_pubkey_sign\fP
.sp
Default: \fBFalse\fP
.sp
Enables verification of the master\-public\-signature returned by the master in
auth\-replies. Please see the tutorial on how to configure this properly
\fI\%Multimaster\-PKI with Failover Tutorial\fP
.sp
New in version 2014.7.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
verify_master_pubkey_sign: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this is set to \fBTrue\fP, \fBmaster_sign_pubkey\fP must be also set
to \fBTrue\fP in the master configuration file.
.SS \fBmaster_sign_key_name\fP
.sp
Default: \fBmaster_sign\fP
.sp
The filename without the \fI\&.pub\fP suffix of the public key that should be used
for verifying the signature from the master. The file must be located in the
minion\(aqs pki directory.
.sp
New in version 2014.7.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_sign_key_name: <filename_without_suffix>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBalways_verify_signature\fP
.sp
Default: \fBFalse\fP
.sp
If \fI\%verify_master_pubkey_sign\fP is enabled, the signature is only verified,
if the public\-key of the master changes. If the signature should always be verified,
this can be set to \fBTrue\fP\&.
.sp
New in version 2014.7.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
always_verify_signature: True
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
multiprocessing: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Minion Logging Settings
.SS \fBlog_file\fP
.sp
Default: \fB/var/log/salt/minion\fP
.sp
The minion log can be sent to a regular file, local path name, or network
location. See also \fBlog_file\fP\&.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: /var/log/salt/minion
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: file:///dev/log
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: udp://loghost:10514
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_level\fP
.sp
Default: \fBwarning\fP
.sp
The level of messages to send to the console. See also \fBlog_level\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_level: warning
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_level_logfile\fP
.sp
Default: \fBwarning\fP
.sp
The level of messages to send to the log file. See also
\fBlog_level_logfile\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_level_logfile: warning
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_datefmt\fP
.sp
Default: \fB%H:%M:%S\fP
.sp
The date and time format used in console log messages. See also
\fBlog_datefmt\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_datefmt: \(aq%H:%M:%S\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_datefmt_logfile\fP
.sp
Default: \fB%Y\-%m\-%d %H:%M:%S\fP
.sp
The date and time format used in log file messages. See also
\fBlog_datefmt_logfile\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_fmt_console\fP
.sp
Default: \fB[%(levelname)\-8s] %(message)s\fP
.sp
The format of the console logging messages. See also
\fBlog_fmt_console\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_fmt_logfile\fP
.sp
Default: \fB%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\fP
.sp
The format of the log file logging messages. See also
\fBlog_fmt_logfile\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_granular_levels\fP
.sp
Default: \fB{}\fP
.sp
This can be used to control logging levels more specifically. See also
\fBlog_granular_levels\fP\&.
.SS \fBfailhard\fP
.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
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
failhard: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Include Configuration
.SS \fBdefault_include\fP
.sp
Default: \fBminion.d/*.conf\fP
.sp
The minion can include configuration from other files. Per default the
minion will automatically include all config files from \fIminion.d/*.conf\fP
where minion.d is relative to the directory of the minion configuration
file.
.SS \fBinclude\fP
.sp
Default: \fBnot defined\fP
.sp
The minion can include configuration from other files. To enable this,
pass a list of paths to this option. The paths can be either relative or
absolute; if relative, they are considered to be relative to the directory
the main minion configuration file lives in. Paths can make use of
shell\-style globbing. If no files are matched by a path passed to this
option then the minion will log a warning message.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Include files from a minion.d directory in the same
# directory as the minion config file
include: minion.d/*.conf
# Include a single extra file into the configuration
include: /etc/roles/webserver
# Include several files and the minion.d directory
include:
\- extra_config
\- minion.d/*
\- /etc/roles/webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Frozen Build Update Settings
.sp
These options control how \fBsalt.modules.saltutil.update()\fP works with esky
frozen apps. For more information look at \fI\%https://github.com/cloudmatrix/esky/\fP\&.
.SS \fBupdate_url\fP
.sp
Default: \fBFalse\fP (Update feature is disabled)
.sp
The url to use when looking for application updates. Esky depends on directory
listings to search for new versions. A webserver running on your Master is a
good starting point for most setups.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
update_url: \(aqhttp://salt.example.com/minion\-updates\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBupdate_restart_services\fP
.sp
Default: \fB[]\fP (service restarting on update is disabled)
.sp
A list of services to restart when the minion software is updated. This would
typically just be a list containing the minion\(aqs service name, but you may
have other services that need to go with it.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
update_restart_services: [\(aqsalt\-minion\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Running the Salt Master/Minion as an Unprivileged User
.sp
While the default setup runs the master and minion as the root user, some
may consider it an extra measure of security to run the master as a non\-root
user. Keep in mind that doing so does not change the master\(aqs capability
to access minions as the user they are running as. Due to this many feel that
running the master as a non\-root user does not grant any real security advantage
which is why the master has remained as root by default.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Some of Salt\(aqs operations cannot execute correctly when the master is not
running as root, specifically the pam external auth system, as this system
needs root access to check authentication.
.UNINDENT
.UNINDENT
.sp
As of Salt 0.9.10 it is possible to run Salt as a non\-root user. This can be
done by setting the \fBuser\fP parameter in the master configuration
file. and restarting the \fBsalt\-master\fP service.
.sp
The minion has it\(aqs own \fBuser\fP parameter as well, but running the
minion as an unprivileged user will keep it from making changes to things like
users, installed packages, etc. unless access controls (sudo, etc.) are setup
on the minion to permit the non\-root user to make the needed changes.
.sp
In order to allow Salt to successfully run as a non\-root user, ownership and
permissions need to be set such that the desired user can read from and write
to the following directories (and their subdirectories, where applicable):
.INDENT 0.0
.IP \(bu 2
/etc/salt
.IP \(bu 2
/var/cache/salt
.IP \(bu 2
/var/log/salt
.IP \(bu 2
/var/run/salt
.UNINDENT
.sp
Ownership can be easily changed with \fBchown\fP, like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# chown \-R user /etc/salt /var/cache/salt /var/log/salt /var/run/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Running either the master or minion with the \fBroot_dir\fP
parameter specified will affect these paths, as will setting options like
\fBpki_dir\fP, \fBcachedir\fP, \fBlog_file\fP,
and other options that normally live in the above directories.
.UNINDENT
.UNINDENT
.SS Logging
.sp
The salt project tries to get the logging to work for you and help us solve any
issues you might find along the way.
.sp
If you want to get some more information on the nitty\-gritty of salt\(aqs logging
system, please head over to the \fBlogging development
document\fP, if all you\(aqre after is salt\(aqs logging
configurations, please continue reading.
.SS Available Configuration Settings
.SS \fBlog_file\fP
.sp
The log records can be sent to a regular file, local path name, or network location.
Remote logging works best when configured to use rsyslogd(8) (e.g.: \fBfile:///dev/log\fP),
with rsyslogd(8) configured for network logging. The format for remote addresses is:
\fB<file|udp|tcp>://<host|socketpath>:<port\-if\-required>/<log\-facility>\fP\&.
.sp
Default: Dependent of the binary being executed, for example, for \fBsalt\-master\fP,
\fB/var/log/salt/master\fP\&.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: /var/log/salt/master
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: /var/log/salt/minion
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: file:///dev/log
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_file: udp://loghost:10514
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_level\fP
.sp
Default: \fBwarning\fP
.sp
The level of log record messages to send to the console.
One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP,
\fBerror\fP, \fBcritical\fP, \fBquiet\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_level: warning
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_level_logfile\fP
.sp
Default: \fBwarning\fP
.sp
The level of messages to send to the log file.
One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP,
\fBerror\fP, \fBcritical\fP, \fBquiet\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_level_logfile: warning
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_datefmt\fP
.sp
Default: \fB%H:%M:%S\fP
.sp
The date and time format used in console log messages. Allowed date/time
formatting can be seen on \fI\%time.strftime\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_datefmt: \(aq%H:%M:%S\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_datefmt_logfile\fP
.sp
Default: \fB%Y\-%m\-%d %H:%M:%S\fP
.sp
The date and time format used in log file messages. Allowed date/time
formatting can be seen on \fI\%time.strftime\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_fmt_console\fP
.sp
Default: \fB[%(levelname)\-8s] %(message)s\fP
.sp
The format of the console logging messages. Allowed formatting options can
be seen on the \fI\%LogRecord attributes\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_fmt_logfile\fP
.sp
Default: \fB%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\fP
.sp
The format of the log file logging messages. Allowed formatting options can
be seen on the \fI\%LogRecord attributes\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBlog_granular_levels\fP
.sp
Default: \fB{}\fP
.sp
This can be used to control logging levels more specifically. The example sets
the main salt library at the \(aqwarning\(aq level, but sets \fBsalt.modules\fP to log
at the \fBdebug\fP level:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log_granular_levels:
\(aqsalt\(aq: \(aqwarning\(aq
\(aqsalt.modules\(aq: \(aqdebug\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS External Logging Handlers
.sp
Besides the internal logging handlers used by salt, there are some external
which can be used, see the \fBexternal logging handlers\fP
document.
.SS External Logging Handlers
.TS
center;
|l|l|.
_
T{
\fBlogstash_mod\fP
T} T{
Logstash Logging Handler
T}
_
T{
\fBsentry_mod\fP
T} T{
Sentry Logging Handler
T}
_
.TE
.SS Logstash Logging Handler
.sp
New in version 0.17.0.
.sp
This module provides some \fI\%Logstash\fP logging handlers.
.SS UDP Logging Handler
.sp
For versions of \fI\%Logstash\fP before 1.2.0:
.sp
In the salt configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
logstash_udp_handler:
host: 127.0.0.1
port: 9999
version: 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the \fI\%Logstash\fP configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
input {
udp {
type => "udp\-type"
format => "json_event"
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For version 1.2.0 of \fI\%Logstash\fP and newer:
.sp
In the salt configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
logstash_udp_handler:
host: 127.0.0.1
port: 9999
version: 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the \fI\%Logstash\fP configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
input {
udp {
port => 9999
codec => json
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please read the \fI\%UDP input\fP configuration page for additional information.
.SS ZeroMQ Logging Handler
.sp
For versions of \fI\%Logstash\fP before 1.2.0:
.sp
In the salt configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
logstash_zmq_handler:
address: tcp://127.0.0.1:2021
version: 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the \fI\%Logstash\fP configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
input {
zeromq {
type => "zeromq\-type"
mode => "server"
topology => "pubsub"
address => "tcp://0.0.0.0:2021"
charset => "UTF\-8"
format => "json_event"
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For version 1.2.0 of \fI\%Logstash\fP and newer:
.sp
In the salt configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
logstash_zmq_handler:
address: tcp://127.0.0.1:2021
version: 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the \fI\%Logstash\fP configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
input {
zeromq {
topology => "pubsub"
address => "tcp://0.0.0.0:2021"
codec => json
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please read the \fI\%ZeroMQ input\fP configuration page for additional
information.
.INDENT 0.0
.INDENT 3.5
.IP "Important Logstash Setting"
.sp
One of the most important settings that you should not forget on your
\fI\%Logstash\fP configuration file regarding these logging handlers is
\fBformat\fP\&.
Both the \fIUDP\fP and \fIZeroMQ\fP inputs need to have \fBformat\fP as
\fBjson_event\fP which is what we send over the wire.
.UNINDENT
.UNINDENT
.SS Log Level
.sp
Both the \fBlogstash_udp_handler\fP and the \fBlogstash_zmq_handler\fP
configuration sections accept an additional setting \fBlog_level\fP\&. If not
set, the logging level used will be the one defined for \fBlog_level\fP in
the global configuration file section.
.SS HWM
.sp
The \fI\%high water mark\fP for the ZMQ socket setting. Only applicable for the
\fBlogstash_zmq_handler\fP\&.
.INDENT 0.0
.INDENT 3.5
.IP "Inspiration"
.sp
This work was inspired in \fI\%pylogstash\fP, \fI\%python\-logstash\fP, \fI\%canary\fP
and the \fI\%PyZMQ logging handler\fP\&.
.UNINDENT
.UNINDENT
.SS Sentry Logging Handler
.sp
New in version 0.17.0.
.sp
This module provides a \fI\%Sentry\fP logging handler.
.INDENT 0.0
.INDENT 3.5
.IP "Note"
.sp
The \fI\%Raven\fP library needs to be installed on the system for this
logging handler to be available.
.UNINDENT
.UNINDENT
.sp
Configuring the python \fI\%Sentry\fP client, \fI\%Raven\fP, should be done under the
\fBsentry_handler\fP configuration key.
At the bare minimum, you need to define the \fI\%DSN\fP\&. As an example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sentry_handler:
dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
More complex configurations can be achieved, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sentry_handler:
servers:
\- https://sentry.example.com
\- http://192.168.1.1
project: app\-id
public_key: deadbeefdeadbeefdeadbeefdeadbeef
secret_key: beefdeadbeefdeadbeefdeadbeefdead
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All the client configuration keys are supported, please see the
\fI\%Raven client documentation\fP\&.
.sp
The default logging level for the sentry handler is \fBERROR\fP\&. If you wish
to define a different one, define \fBlog_level\fP under the
\fBsentry_handler\fP configuration key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sentry_handler:
dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id
log_level: warning
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The available log levels are those also available for the salt \fBcli\fP
tools and configuration; \fBsalt \-\-help\fP should give you the required
information.
.SS Threaded Transports
.sp
Raven\(aqs documents rightly suggest using its threaded transport for
critical applications. However, don\(aqt forget that if you start having
troubles with Salt after enabling the threaded transport, please try
switching to a non\-threaded transport to see if that fixes your problem.
.SS 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 to present files for use in the
Salt state system. With this said, the Salt file server can be used for any
general file transfer from the master to the minions.
.SS File Server Backends
.sp
In Salt 0.12.0, the modular fileserver was introduced. This feature added the
ability for the Salt Master to integrate different file server backends. File
server backends allow the Salt file server to act as a transparent bridge to
external resources. A good example of this is the \fBgit\fP backend, which allows Salt to serve files sourced from
one or more git repositories, but there are several others as well. Click
\fIhere\fP for a full list of Salt\(aqs fileserver
backends.
.SS Enabling a Fileserver Backend
.sp
Fileserver backends can be enabled with the \fBfileserver_backend\fP
option.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See the \fIdocumentation\fP for each backend to find the
correct value to add to \fBfileserver_backend\fP in order to enable
them.
.SS Using Multiple Backends
.sp
If \fBfileserver_backend\fP is not defined in the Master config file,
Salt will use the \fBroots\fP backend, but the
\fBfileserver_backend\fP option supports multiple backends. When more
than one backend is in use, the files from the enabled backends are merged into a
single virtual filesystem. When a file is requested, the backends will be
searched in order for that file, and the first backend to match will be the one
which returns the file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- roots
\- git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this configuration, the environments and files defined in the
\fBfile_roots\fP parameter will be searched first, and if the file is
not found then the git repositories defined in \fBgitfs_remotes\fP
will be searched.
.SS Environments
.sp
Just as the order of the values in \fBfileserver_backend\fP matters,
so too does the order in which different sources are defined within a
fileserver environment. For example, given the below \fBfile_roots\fP
configuration, if both \fB/srv/salt/dev/foo.txt\fP and \fB/srv/salt/prod/foo.txt\fP
exist on the Master, then \fBsalt://foo.txt\fP would point to
\fB/srv/salt/dev/foo.txt\fP in the \fBdev\fP environment, but it would point to
\fB/srv/salt/prod/foo.txt\fP in the \fBbase\fP environment.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt/prod
qa:
\- /srv/salt/qa
\- /srv/salt/prod
dev:
\- /srv/salt/dev
\- /srv/salt/qa
\- /srv/salt/prod
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Similarly, when using the \fBgit\fP backend, if both
repositories defined below have a \fBhotfix23\fP branch/tag, and both of them
also contain the file \fBbar.txt\fP in the root of the repository at that
branch/tag, then \fBsalt://bar.txt\fP in the \fBhotfix23\fP environment would be
served from the \fBfirst\fP repository.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- https://mydomain.tld/repos/first.git
\- https://mydomain.tld/repos/second.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Environments map differently based on the fileserver backend. For instance,
the mappings are explicitly defined in \fBroots\fP
backend, while in the VCS backends (\fBgit\fP,
\fBhg\fP, \fBsvn\fP) the
environments are created from branches/tags/bookmarks/etc. For the
\fBminion\fP backend, the files are all in a
single environment, which is specified by the \fBminionfs_env\fP
option.
.sp
See the documentation for each backend for a more detailed explanation of
how environments are mapped.
.UNINDENT
.UNINDENT
.SS Dynamic Module Distribution
.sp
New in version 0.9.5.
.sp
Salt Python modules can be distributed automatically via the Salt file server.
Under the root of any environment defined via the \fBfile_roots\fP
option on the master server directories corresponding to the type of module can
be used.
.sp
The directories are prepended with an underscore:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
\fB_modules\fP
.IP 2. 3
\fB_grains\fP
.IP 3. 3
\fB_renderers\fP
.IP 4. 3
\fB_returners\fP
.IP 5. 3
\fB_states\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The contents of these directories need to be synced over to the minions after
Python modules have been created in them. There are a number of ways to sync
the modules.
.SS Sync Via States
.sp
The minion configuration contains an option \fBautoload_dynamic_modules\fP
which defaults to True. This option makes the state system refresh all
dynamic modules when states are run. To disable this behavior set
\fBautoload_dynamic_modules\fP to False in the minion config.
.sp
When dynamic modules are autoloaded via states, modules only pertinent to
the environments matched in the master\(aqs top file are downloaded.
.sp
This is important to remember, because modules can be manually loaded from
any specific environment that environment specific modules will be loaded
when a state run is executed.
.SS Sync Via the saltutil Module
.sp
The saltutil module has a number of functions that can be used to sync all
or specific dynamic modules. The saltutil module function \fBsaltutil.sync_all\fP
will sync all module types over to a minion. For more information see:
\fBsalt.modules.saltutil\fP
.SS File Server Configuration
.sp
The Salt file server is a high performance file server written in ZeroMQ. It
manages large files quickly and with little overhead, and has been optimized
to handle small files in an extremely efficient manner.
.sp
The Salt file server is an environment aware file server. This means that
files can be allocated within many root directories and accessed by
specifying both the file path and the environment to search. The
individual environments can span across multiple directory roots
to create overlays and to allow for files to be organized in many flexible
ways.
.SS Environments
.sp
The Salt file server defaults to the mandatory \fBbase\fP environment. This
environment \fBMUST\fP be defined and is used to download files when no
environment is specified.
.sp
Environments allow for files and sls data to be logically separated, but
environments are not isolated from each other. This allows for logical
isolation of environments by the engineer using Salt, but also allows
for information to be used in multiple environments.
.SS Directory Overlay
.sp
The \fBenvironment\fP setting is a list of directories to publish files from.
These directories are searched in order to find the specified file and the
first file found is returned.
.sp
This means that directory data is prioritized based on the order in which they
are listed. In the case of this \fBfile_roots\fP configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt/base
\- /srv/salt/failover
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a file\(aqs URI is \fBsalt://httpd/httpd.conf\fP, it will first search for the
file at \fB/srv/salt/base/httpd/httpd.conf\fP\&. If the file is found there it
will be returned. If the file is not found there, then
\fB/srv/salt/failover/httpd/httpd.conf\fP will be used for the source.
.sp
This allows for directories to be overlaid and prioritized based on the order
they are defined in the configuration.
.sp
It is also possible to have \fBfile_roots\fP which supports multiple
environments:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt/base
dev:
\- /srv/salt/dev
\- /srv/salt/base
prod:
\- /srv/salt/prod
\- /srv/salt/base
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example ensures that each environment will check the associated
environment directory for files first. If a file is not found in the
appropriate directory, the system will default to using the base directory.
.SS Local File Server
.sp
New in version 0.9.8.
.sp
The file server can be rerouted to run from the minion. This is primarily to
enable running Salt states without a Salt master. To use the local file server
interface, copy the file server data to the minion and set the file_roots
option on the minion to point to the directories copied from the master.
Once the minion \fBfile_roots\fP option has been set, change the \fBfile_client\fP
option to local to make sure that the local file server interface is used.
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will instruct all Salt minions to download the vimrc file and copy it
to /etc/vimrc
.sp
Template rendering can be enabled on both the source and destination file names
like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aq*\(aq cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example would instruct all Salt minions to download the vimrc from a
directory with the same name as their OS grain and copy it to /etc/vimrc
.sp
For larger files, the cp.get_file module also supports gzip compression.
Because gzip is CPU\-intensive, this should only be used in
scenarios where the compression ratio is very high (e.g. pretty\-printed JSON
or YAML files).
.sp
To use compression, use the \fBgzip\fP named argument. Valid values are integers
from 1 to 9, where 1 is the lightest compression and 9 the heaviest. In other
words, 1 uses the least CPU on the master (and minion), while 9 uses the most.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc gzip=5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, note that by default cp.get_file does \fInot\fP create new destination
directories if they do not exist. To change this, use the \fBmakedirs\fP
argument:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aq*\(aq cp.get_file salt://vimrc /etc/vim/vimrc makedirs=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, /etc/vim/ would be created if it didn\(aqt already exist.
.SS get_dir
.sp
The cp.get_dir function can be used on the minion to download an entire
directory from the master. The syntax is very similar to get_file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aq*\(aq cp.get_dir salt://etc/apache2 /etc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
cp.get_dir supports template rendering and gzip compression arguments just like
get_file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \(aq*\(aq cp.get_dir salt://etc/{{pillar.webserver}} /etc gzip=5 template=jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
Using the FileClient class outside of a minion module where the \fB__opts__\fP
data is not available, it needs to be generated:
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.SS Full list of builtin fileserver modules
.TS
center;
|l|l|.
_
T{
\fBgitfs\fP
T} T{
Git Fileserver Backend
T}
_
T{
\fBhgfs\fP
T} T{
Mercurial Fileserver Backend
T}
_
T{
\fBminionfs\fP
T} T{
Fileserver backend which serves files pushed to the Master
T}
_
T{
\fBroots\fP
T} T{
The default file server backend
T}
_
T{
\fBs3fs\fP
T} T{
Amazon S3 Fileserver Backend
T}
_
T{
\fBsvnfs\fP
T} T{
Subversion Fileserver Backend
T}
_
.TE
.SS salt.fileserver.gitfs
.sp
Git Fileserver Backend
.sp
With this backend, branches and tags in a remote git repository are exposed to
salt as different environments.
.sp
To enable, add \fBgit\fP to the \fBfileserver_backend\fP option in the
Master config file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As of Salt 2014.7.0, the Git fileserver backend supports \fI\%GitPython\fP, \fI\%pygit2\fP,
and \fI\%dulwich\fP to provide the Python interface to git. If more than one of these
are present, the order of preference for which one will be chosen is the same
as the order in which they were listed: pygit2, GitPython, dulwich (keep in
mind, this order is subject to change).
.sp
An optional master config parameter (\fBgitfs_provider\fP) can be used
to specify which provider should be used.
.sp
More detailed information on how to use gitfs can be found in the \fIGitfs
Walkthrough\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Minimum requirements
.sp
To use \fI\%GitPython\fP for gitfs requires a minimum GitPython version of 0.3.0,
as well as the git CLI utility. Instructions for installing GitPython can
be found \fIhere\fP\&.
.sp
To use \fI\%pygit2\fP for gitfs requires a minimum \fI\%pygit2\fP version of 0.20.3.
\fI\%pygit2\fP 0.20.3 requires \fI\%libgit2\fP 0.20.0. \fI\%pygit2\fP and \fI\%libgit2\fP are developed
alongside one another, so it is recommended to keep them both at the same
major release to avoid unexpected behavior. For example, \fI\%pygit2\fP 0.21.x
requires \fI\%libgit2\fP 0.21.x, \fI\%pygit2\fP 0.22.x will require \fI\%libgit2\fP 0.22.x, etc.
.sp
To find stale refs, pygit2 additionally requires the git CLI utility to be
installed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.clear_cache()
Completely clear gitfs cache
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.clear_lock(remote=None)
Clear update.lk
.sp
\fBremote\fP can either be a dictionary containing repo configuration
information, or a pattern. If the latter, then remotes for which the URL
matches the pattern will be locked.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.dir_list(load)
Return a list of all directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.envs(ignore_cache=False, skip_clean=False)
Return a list of refs that can be used as environments
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.file_hash(load, fnd)
Return a file hash, the hash type is set in the master config file
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.file_list(load)
Return a list of all files on the file server in a specified
environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.file_list_emptydirs(load)
Return a list of all empty directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.find_file(path, tgt_env=\(aqbase\(aq, **kwargs)
Find the first file to match the path and ref, read the file out of git
and send the path to the newly cached file
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.init()
Return the git repo object for this session
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.lock(remote=None)
Place an update.lk
.sp
\fBremote\fP can either be a dictionary containing repo configuration
information, or a pattern. If the latter, then remotes for which the URL
matches the pattern will be locked.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.serve_file(load, fnd)
Return a chunk from a file based on the data received
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.symlink_list(load)
Return a dict of all symlinks based on a given path in the repo
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.gitfs.update()
Execute a git fetch on all of the repos
.UNINDENT
.SS salt.fileserver.hgfs
.sp
Mercurial Fileserver Backend
.sp
To enable, add \fBhg\fP to the \fBfileserver_backend\fP option in the
Master config file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- hg
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After enabling this backend, branches, bookmarks, and tags in a remote
mercurial repository are exposed to salt as different environments. This
feature is managed by the \fBfileserver_backend\fP option in the salt
master config file.
.sp
This fileserver has an additional option \fBhgfs_branch_method\fP that
will set the desired branch method. Possible values are: \fBbranches\fP,
\fBbookmarks\fP, or \fBmixed\fP\&. If using \fBbranches\fP or \fBmixed\fP, the
\fBdefault\fP branch will be mapped to \fBbase\fP\&.
.sp
Changed in version 2014.1.0: The \fBhgfs_base\fP master config parameter was added, allowing
for a branch other than \fBdefault\fP to be used for the \fBbase\fP
environment, and allowing for a \fBbase\fP environment to be specified when
using an \fBhgfs_branch_method\fP of \fBbookmarks\fP\&.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
mercurial
.IP \(bu 2
python bindings for mercurial (\fBpython\-hglib\fP)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.clear_cache()
Completely clear hgfs cache
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.clear_lock(remote=None)
Clear update.lk
.sp
\fBremote\fP can either be a dictionary containing repo configuration
information, or a pattern. If the latter, then remotes for which the URL
matches the pattern will be locked.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.dir_list(load)
Return a list of all directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.envs(ignore_cache=False)
Return a list of refs that can be used as environments
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.file_hash(load, fnd)
Return a file hash, the hash type is set in the master config file
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.file_list(load)
Return a list of all files on the file server in a specified environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.file_list_emptydirs(load)
Return a list of all empty directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.find_file(path, tgt_env=\(aqbase\(aq, **kwargs)
Find the first file to match the path and ref, read the file out of hg
and send the path to the newly cached file
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.init()
Return a list of hglib objects for the various hgfs remotes
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.lock(remote=None)
Place an update.lk
.sp
\fBremote\fP can either be a dictionary containing repo configuration
information, or a pattern. If the latter, then remotes for which the URL
matches the pattern will be locked.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.serve_file(load, fnd)
Return a chunk from a file based on the data received
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.hgfs.update()
Execute an hg pull on all of the repos
.UNINDENT
.SS salt.fileserver.minionfs
.sp
Fileserver backend which serves files pushed to the Master
.sp
The \fBcp.push\fP function allows Minions to push files
up to the Master. Using this backend, these pushed files are exposed to other
Minions via the Salt fileserver.
.sp
To enable minionfs, \fBfile_recv\fP needs to be set to \fBTrue\fP in
the master config file (otherwise \fBcp.push\fP will
not be allowed to push files to the Master), and \fBminion\fP must be added to
the \fBfileserver_backends\fP list.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Other minionfs settings include: \fBminionfs_whitelist\fP,
\fBminionfs_blacklist\fP, \fBminionfs_mountpoint\fP, and
\fBminionfs_env\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fItutorial\-minionfs\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.minionfs.dir_list(load)
Return a list of all directories on the master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt \(aqsource\-minion\(aq cp.push /absolute/path/file # Push the file to the master
$ salt \(aqdestination\-minion\(aq cp.list_master_dirs
destination\-minion:
\- source\-minion/absolute
\- source\-minion/absolute/path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.minionfs.envs()
Returns the one environment specified for minionfs in the master
configuration.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.minionfs.file_hash(load, fnd)
Return a file hash, the hash type is set in the master config file
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.minionfs.file_list(load)
Return a list of all files on the file server in a specified environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.minionfs.find_file(path, tgt_env=\(aqbase\(aq, **kwargs)
Search the environment for the relative path
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.minionfs.serve_file(load, fnd)
Return a chunk from a file based on the data received
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Push the file to the master
$ salt \(aqsource\-minion\(aq cp.push /path/to/the/file
$ salt \(aqdestination\-minion\(aq cp.get_file salt://source\-minion/path/to/the/file /destination/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.minionfs.update()
When we are asked to update (regular interval) lets reap the cache
.UNINDENT
.SS salt.fileserver.roots
.sp
The default file server backend
.sp
This fileserver backend serves files from the Master\(aqs local filesystem. If
\fBfileserver_backend\fP is not defined in the Master config file,
then this backend is enabled by default. If it \fIis\fP defined then \fBroots\fP must
be in the \fBfileserver_backend\fP list to enable this backend.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- roots
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Fileserver environments are defined using the \fBfile_roots\fP
configuration option.
.INDENT 0.0
.TP
.B salt.fileserver.roots.dir_list(load)
Return a list of all directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.envs()
Return the file server environments
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.file_hash(load, fnd)
Return a file hash, the hash type is set in the master config file
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.file_list(load)
Return a list of all files on the file server in a specified
environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.file_list_emptydirs(load)
Return a list of all empty directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.find_file(path, saltenv=\(aqbase\(aq, env=None, **kwargs)
Search the environment for the relative path
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.serve_file(load, fnd)
Return a chunk from a file based on the data received
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.symlink_list(load)
Return a dict of all symlinks based on a given path on the Master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.roots.update()
When we are asked to update (regular interval) lets reap the cache
.UNINDENT
.SS salt.fileserver.s3fs
.sp
Amazon S3 Fileserver Backend
.sp
This backend exposes directories in S3 buckets as Salt environments. To enable
this backend, add \fBs3\fP to the \fBfileserver_backend\fP option in the
Master config file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- s3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
S3 credentials must also be set in the master config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
s3.keyid: GKTADJGHEIQSXMKKRBJ08H
s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, if on EC2 these credentials can be automatically loaded from
instance metadata.
.sp
This fileserver supports two modes of operation for the buckets:
.INDENT 0.0
.IP 1. 3
\fBA single bucket per environment\fP
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
s3.buckets:
production:
\- bucket1
\- bucket2
staging:
\- bucket3
\- bucket4
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
\fBMultiple environments per bucket\fP
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
s3.buckets:
\- bucket1
\- bucket2
\- bucket3
\- bucket4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Note that bucket names must be all lowercase both in the AWS console and in
Salt, otherwise you may encounter \fBSignatureDoesNotMatch\fP errors.
.sp
A multiple\-environment bucket must adhere to the following root directory
structure:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
s3://<bucket name>/<environment>/<files>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This fileserver back\-end requires the use of the MD5 hashing algorithm.
MD5 may not be compliant with all security policies.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.dir_list(load)
Return a list of all directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.envs()
Return a list of directories within the bucket that can be
used as environments.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.file_hash(load, fnd)
Return an MD5 file hash
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.file_list(load)
Return a list of all files on the file server in a specified environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.file_list_emptydirs(load)
Return a list of all empty directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.find_file(path, saltenv=\(aqbase\(aq, env=None, **kwargs)
Look through the buckets cache file for a match.
If the field is found, it is retrieved from S3 only if its cached version
is missing, or if the MD5 does not match.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.serve_file(load, fnd)
Return a chunk from a file based on the data received
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.s3fs.update()
Update the cache file for the bucket.
.UNINDENT
.SS salt.fileserver.svnfs
.sp
Subversion Fileserver Backend
.sp
After enabling this backend, branches, and tags in a remote subversion
repository are exposed to salt as different environments. To enable this
backend, add \fBsvn\fP to the \fBfileserver_backend\fP option in the
Master config file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fileserver_backend:
\- svn
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This backend assumes a standard svn layout with directories for \fBbranches\fP,
\fBtags\fP, and \fBtrunk\fP, at the repository root.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
subversion
.IP \(bu 2
pysvn
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: The paths to the trunk, branches, and tags have been made configurable, via
the config options \fBsvnfs_trunk\fP,
\fBsvnfs_branches\fP, and \fBsvnfs_tags\fP\&.
\fBsvnfs_mountpoint\fP was also added. Finally, support for
per\-remote configuration parameters was added. See the
\fBdocumentation\fP for more information.
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.clear_cache()
Completely clear svnfs cache
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.clear_lock(remote=None)
Clear update.lk
.sp
\fBremote\fP can either be a dictionary containing repo configuration
information, or a pattern. If the latter, then remotes for which the URL
matches the pattern will be locked.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.dir_list(load)
Return a list of all directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.envs(ignore_cache=False)
Return a list of refs that can be used as environments
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.file_hash(load, fnd)
Return a file hash, the hash type is set in the master config file
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.file_list(load)
Return a list of all files on the file server in a specified
environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.file_list_emptydirs(load)
Return a list of all empty directories on the master
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.find_file(path, tgt_env=\(aqbase\(aq, **kwargs)
Find the first file to match the path and ref. This operates similarly to
the roots file sever but with assumptions of the directory structure
based on svn standard practices.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.init()
Return the list of svn remotes and their configuration information
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.lock(remote=None)
Place an update.lk
.sp
\fBremote\fP can either be a dictionary containing repo configuration
information, or a pattern. If the latter, then remotes for which the URL
matches the pattern will be locked.
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.serve_file(load, fnd)
Return a chunk from a file based on the data received
.UNINDENT
.INDENT 0.0
.TP
.B salt.fileserver.svnfs.update()
Execute an svn update on all of the repos
.UNINDENT
.SS Salt code and internals
.sp
Reference documentation on Salt\(aqs internal code.
.SS Contents
.SS salt.serializers
.SS salt.utils.aggregation
.sp
This library allows to introspect dataset and aggregate nodes when it is
instructed.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The following examples with be expressed in YAML for convenience sake:
.INDENT 0.0
.IP \(bu 2
!aggr\-scalar will refer to Scalar python function
.IP \(bu 2
!aggr\-map will refer to Map python object
.IP \(bu 2
!aggr\-seq will refer for Sequence python object
.UNINDENT
.UNINDENT
.UNINDENT
.SS How to instructs merging
.sp
This yaml document have duplicate keys:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: !aggr\-scalar first
foo: !aggr\-scalar second
bar: !aggr\-map {first: foo}
bar: !aggr\-map {second: bar}
baz: !aggr\-scalar 42
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
but tagged values instruct salt that overlapping values they can be merged
together:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: !aggr\-seq [first, second]
bar: !aggr\-map {first: foo, second: bar}
baz: !aggr\-seq [42]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Default merge strategy is keep untouched
.sp
For example, this yaml document have still duplicate keys, but does not
instruct aggregation:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: first
foo: second
bar: {first: foo}
bar: {second: bar}
baz: 42
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
So the late found values prevail:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: second
bar: {second: bar}
baz: 42
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Limitations
.sp
Aggregation is permitted between tagged objects that share the same type.
If not, the default merge strategy prevails.
.sp
For example, these examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: {first: value}
foo: !aggr\-map {second: value}
bar: !aggr\-map {first: value}
bar: 42
baz: !aggr\-seq [42]
baz: [fail]
qux: 42
qux: !aggr\-scalar fail
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
are interpreted like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: !aggr\-map{second: value}
bar: 42
baz: [fail]
qux: !aggr\-seq [fail]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Introspection
.sp
TODO: write this part
.INDENT 0.0
.TP
.B salt.utils.aggregation.aggregate(obj_a, obj_b, level=False, map_class=<class \(aqsalt.utils.aggregation.Map\(aq>, sequence_class=<class \(aqsalt.utils.aggregation.Sequence\(aq>)
Merge obj_b into obj_a.
.sp
.nf
.ft C
>>> aggregate(\(aqfirst\(aq, \(aqsecond\(aq, True) == [\(aqfirst\(aq, \(aqsecond\(aq]
True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B class salt.utils.aggregation.Aggregate
Aggregation base.
.UNINDENT
.INDENT 0.0
.TP
.B class salt.utils.aggregation.Map(*args, **kwds)
Map aggregation.
.UNINDENT
.INDENT 0.0
.TP
.B salt.utils.aggregation.Scalar(obj)
Shortcut for Sequence creation
.sp
.nf
.ft C
>>> Scalar(\(aqfoo\(aq) == Sequence([\(aqfoo\(aq])
True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B class salt.utils.aggregation.Sequence
Sequence aggregation.
.UNINDENT
.SS Exceptions
.sp
Salt\-specific exceptions should be thrown as often as possible so the various
interfaces to Salt (CLI, API, etc) can handle those errors appropriately and
display error messages appropriately.
.TS
center;
|l|l|.
_
T{
\fBsalt.exceptions\fP
T} T{
This module is a central location for all salt exceptions
T}
_
.TE
.SS salt.exceptions
.sp
This module is a central location for all salt exceptions
.INDENT 0.0
.TP
.B exception salt.exceptions.AuthenticationError
If sha256 signature fails during decryption
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.AuthorizationError
Thrown when runner or wheel execution fails due to permissions
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.CommandExecutionError
Used when a module runs a command which returns an error and wants
to show the user the output gracefully instead of dying
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.CommandNotFoundError
Used in modules or grains when a required binary is not available
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.EauthAuthenticationError
Thrown when eauth authentication fails
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.FileserverConfigError
Used when invalid fileserver settings are detected
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.LoaderError
Problems loading the right renderer
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.MasterExit
Rise when the master exits
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.MinionError
Minion problems reading uris such as salt:// or http://
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.PkgParseError
Used when of the pkg modules cannot correctly parse the output from
the CLI tool (pacman, yum, apt, aptitude, etc)
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltClientError
Problem reading the master root key
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltClientTimeout(msg, jid=None, *args, **kwargs)
Thrown when a job sent through one of the Client interfaces times out
.sp
Takes the \fBjid\fP as a parameter
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudConfigError
Raised when a configuration setting is not found and should exist.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudException
Generic Salt Cloud Exception
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudExecutionFailure
Raised when too much failures have occurred while querying/waiting for data.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudExecutionTimeout
Raised when too much time has passed while querying/waiting for data.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudNotFound
Raised when some cloud provider function cannot find what\(aqs being searched.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudPasswordError
Raise when virtual terminal password input failed
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudSystemExit(message, exit_code=1)
This exception is raised when the execution should be stopped.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltException
Base exception class; all Salt\-specific exceptions should subclass this
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltInvocationError
Used when the wrong number of arguments are sent to modules or invalid
arguments are specified on the command line
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltMasterError
Problem reading the master root key
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltRenderError(error, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None)
Used when a renderer needs to raise an explicit error. If a line number and
buffer string are passed, get_context will be invoked to get the location
of the error.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltReqTimeoutError
Thrown when a salt master request call fails to return within the timeout
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltRunnerError
Problem in runner
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltSyndicMasterError
Problem while proxying a request in the syndication master
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltSystemExit(code=0, msg=None)
This exception is raised when an unsolvable problem is found. There\(aqs
nothing else to do, salt should just exit.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltWheelError
Problem in wheel
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.TimedProcTimeoutError
Thrown when a timed subprocess does not terminate within the timeout,
or if the specified timeout is not an int or a float
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.TokenAuthenticationError
Thrown when token authentication fails
.UNINDENT
.SS salt.exceptions
.sp
This module is a central location for all salt exceptions
.INDENT 0.0
.TP
.B exception salt.exceptions.AuthenticationError
If sha256 signature fails during decryption
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.AuthorizationError
Thrown when runner or wheel execution fails due to permissions
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.CommandExecutionError
Used when a module runs a command which returns an error and wants
to show the user the output gracefully instead of dying
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.CommandNotFoundError
Used in modules or grains when a required binary is not available
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.EauthAuthenticationError
Thrown when eauth authentication fails
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.FileserverConfigError
Used when invalid fileserver settings are detected
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.LoaderError
Problems loading the right renderer
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.MasterExit
Rise when the master exits
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.MinionError
Minion problems reading uris such as salt:// or http://
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.PkgParseError
Used when of the pkg modules cannot correctly parse the output from
the CLI tool (pacman, yum, apt, aptitude, etc)
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltClientError
Problem reading the master root key
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltClientTimeout(msg, jid=None, *args, **kwargs)
Thrown when a job sent through one of the Client interfaces times out
.sp
Takes the \fBjid\fP as a parameter
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudConfigError
Raised when a configuration setting is not found and should exist.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudException
Generic Salt Cloud Exception
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudExecutionFailure
Raised when too much failures have occurred while querying/waiting for data.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudExecutionTimeout
Raised when too much time has passed while querying/waiting for data.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudNotFound
Raised when some cloud provider function cannot find what\(aqs being searched.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudPasswordError
Raise when virtual terminal password input failed
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltCloudSystemExit(message, exit_code=1)
This exception is raised when the execution should be stopped.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltException
Base exception class; all Salt\-specific exceptions should subclass this
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltInvocationError
Used when the wrong number of arguments are sent to modules or invalid
arguments are specified on the command line
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltMasterError
Problem reading the master root key
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltRenderError(error, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None)
Used when a renderer needs to raise an explicit error. If a line number and
buffer string are passed, get_context will be invoked to get the location
of the error.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltReqTimeoutError
Thrown when a salt master request call fails to return within the timeout
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltRunnerError
Problem in runner
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltSyndicMasterError
Problem while proxying a request in the syndication master
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltSystemExit(code=0, msg=None)
This exception is raised when an unsolvable problem is found. There\(aqs
nothing else to do, salt should just exit.
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.SaltWheelError
Problem in wheel
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.TimedProcTimeoutError
Thrown when a timed subprocess does not terminate within the timeout,
or if the specified timeout is not an int or a float
.UNINDENT
.INDENT 0.0
.TP
.B exception salt.exceptions.TokenAuthenticationError
Thrown when token authentication fails
.UNINDENT
.SS salt.serializers
.SS salt.utils.serializers
.sp
This module implements all the serializers needed by salt.
Each serializer offers the same functions and attributes:
.INDENT 0.0
.TP
.B deserialize
function for deserializing string or stream
.TP
.B serialize
function for serializing a Python object
.TP
.B available
flag that tells if the serializer is available
(all dependencies are met etc.)
.UNINDENT
.SS salt.utils.serializers.json
.sp
Implements JSON serializer.
.sp
It\(aqs just a wrapper around json (or simplejson if available).
.INDENT 0.0
.TP
.B salt.utils.serializers.json.deserialize(stream_or_string, **options)
Deserialize any string of stream like object into a Python data structure.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBstream_or_string\fP \-\- stream or string to deserialize.
.IP \(bu 2
\fBoptions\fP \-\- options given to lower json/simplejson module.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.utils.serializers.json.serialize(obj, **options)
Serialize Python data to JSON.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBobj\fP \-\- the data structure to serialize
.IP \(bu 2
\fBoptions\fP \-\- options given to lower json/simplejson module.
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.utils.serializers.yaml
.sp
Implements YAML serializer.
.sp
Underneath, it is based on pyyaml and use the safe dumper and loader.
It also use C bindings if they are available.
.INDENT 0.0
.TP
.B salt.utils.serializers.yaml.deserialize(stream_or_string, **options)
Deserialize any string of stream like object into a Python data structure.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBstream_or_string\fP \-\- stream or string to deserialize.
.IP \(bu 2
\fBoptions\fP \-\- options given to lower yaml module.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.utils.serializers.yaml.serialize(obj, **options)
Serialize Python data to YAML.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBobj\fP \-\- the data structure to serialize
.IP \(bu 2
\fBoptions\fP \-\- options given to lower yaml module.
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.utils.serializers.msgpack
.sp
Implements MsgPack serializer.
.INDENT 0.0
.TP
.B salt.utils.serializers.msgpack.deserialize(stream_or_string, **options)
Deserialize any string of stream like object into a Python data structure.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBstream_or_string\fP \-\- stream or string to deserialize.
.IP \(bu 2
\fBoptions\fP \-\- options given to lower msgpack module.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.utils.serializers.msgpack.serialize(obj, **options)
Serialize Python data to MsgPack.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBobj\fP \-\- the data structure to serialize
.IP \(bu 2
\fBoptions\fP \-\- options given to lower msgpack module.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Full list of builtin execution modules
.INDENT 0.0
.INDENT 3.5
.IP "Virtual modules"
.SS salt.modules.pkg
.sp
\fBpkg\fP is a virtual module that is fulfilled by one of the following modules:
.INDENT 0.0
.IP \(bu 2
\fBsalt.modules.aptpkg\fP
.IP \(bu 2
\fBsalt.modules.brew\fP
.IP \(bu 2
\fBsalt.modules.ebuild\fP
.IP \(bu 2
\fBsalt.modules.freebsdpkg\fP
.IP \(bu 2
\fBsalt.modules.openbsdpkg\fP
.IP \(bu 2
\fBsalt.modules.pacman\fP
.IP \(bu 2
\fBsalt.modules.pkgin\fP
.IP \(bu 2
\fBsalt.modules.pkgng\fP
.IP \(bu 2
\fBsalt.modules.pkgutil\fP
.IP \(bu 2
\fBsalt.modules.solarispkg\fP
.IP \(bu 2
\fBsalt.modules.win_pkg\fP
.IP \(bu 2
\fBsalt.modules.yumpkg\fP
.IP \(bu 2
\fBsalt.modules.zypper\fP
.UNINDENT
.UNINDENT
.UNINDENT
.TS
center;
|l|l|.
_
T{
\fBaliases\fP
T} T{
Manage the information in the aliases file
T}
_
T{
\fBalternatives\fP
T} T{
Support for Alternatives system
T}
_
T{
\fBapache\fP
T} T{
Support for Apache
T}
_
T{
\fBaptpkg\fP
T} T{
Support for APT (Advanced Packaging Tool)
T}
_
T{
\fBarchive\fP
T} T{
A module to wrap (non\-Windows) archive calls
T}
_
T{
\fBat\fP
T} T{
Wrapper module for at(1)
T}
_
T{
\fBaugeas_cfg\fP
T} T{
Manages configuration files via augeas
T}
_
T{
\fBaws_sqs\fP
T} T{
Support for the Amazon Simple Queue Service.
T}
_
T{
\fBblockdev\fP
T} T{
Module for managing block devices
T}
_
T{
\fBbluez\fP
T} T{
Support for Bluetooth (using BlueZ in Linux).
T}
_
T{
\fBboto_asg\fP
T} T{
Connection module for Amazon Autoscale Groups
T}
_
T{
\fBboto_cloudwatch\fP
T} T{
Connection module for Amazon CloudWatch
T}
_
T{
\fBboto_elasticache\fP
T} T{
Connection module for Amazon Elasticache
T}
_
T{
\fBboto_elb\fP
T} T{
Connection module for Amazon ELB
T}
_
T{
\fBboto_iam\fP
T} T{
Connection module for Amazon IAM
T}
_
T{
\fBboto_route53\fP
T} T{
Connection module for Amazon Route53
T}
_
T{
\fBboto_secgroup\fP
T} T{
Connection module for Amazon Security Groups
T}
_
T{
\fBboto_sqs\fP
T} T{
Connection module for Amazon SQS
T}
_
T{
\fBbrew\fP
T} T{
Homebrew for Mac OS X
T}
_
T{
\fBbridge\fP
T} T{
Module for gathering and managing bridging information
T}
_
T{
\fBbsd_shadow\fP
T} T{
Manage the password database on BSD systems
T}
_
T{
\fBcassandra\fP
T} T{
Cassandra NoSQL Database Module
T}
_
T{
\fBchef\fP
T} T{
Execute chef in server or solo mode
T}
_
T{
\fBchocolatey\fP
T} T{
A dead simple module wrapping calls to the Chocolatey package manager
T}
_
T{
\fBcloud\fP
T} T{
Salt\-specific interface for calling Salt Cloud directly
T}
_
T{
\fBcmdmod\fP
T} T{
A module for shelling out
T}
_
T{
\fBcomposer\fP
T} T{
Use composer to install PHP dependencies for a directory
T}
_
T{
\fBconfig\fP
T} T{
Return config information
T}
_
T{
\fBcp\fP
T} T{
Minion side functions for salt\-cp
T}
_
T{
\fBcron\fP
T} T{
Work with cron
T}
_
T{
\fBdaemontools\fP
T} T{
daemontools service module. This module will create daemontools type
T}
_
T{
\fBdarwin_sysctl\fP
T} T{
Module for viewing and modifying sysctl parameters
T}
_
T{
\fBdata\fP
T} T{
Manage a local persistent data structure that can hold any arbitrary data
T}
_
T{
\fBddns\fP
T} T{
Support for RFC 2136 dynamic DNS updates.
T}
_
T{
\fBdeb_apache\fP
T} T{
Support for Apache
T}
_
T{
\fBdebconfmod\fP
T} T{
Support for Debconf
T}
_
T{
\fBdebian_ip\fP
T} T{
The networking module for Debian based distros
T}
_
T{
\fBdebian_service\fP
T} T{
Service support for Debian systems (uses update\-rc.d and /sbin/service)
T}
_
T{
\fBdefaults\fP
T} T{
T}
_
T{
\fBdig\fP
T} T{
Compendium of generic DNS utilities
T}
_
T{
\fBdisk\fP
T} T{
Module for gathering disk information
T}
_
T{
\fBdjangomod\fP
T} T{
Manage Django sites
T}
_
T{
\fBdnsmasq\fP
T} T{
Module for managing dnsmasq
T}
_
T{
\fBdnsutil\fP
T} T{
Compendium of generic DNS utilities
T}
_
T{
\fBdockerio\fP
T} T{
Management of Dockers
T}
_
T{
\fBdpkg\fP
T} T{
Support for DEB packages
T}
_
T{
\fBebuild\fP
T} T{
Support for Portage
T}
_
T{
\fBeix\fP
T} T{
Support for Eix
T}
_
T{
\fBenviron\fP
T} T{
Support for getting and setting the environment variables of the current salt process.
T}
_
T{
\fBeselect\fP
T} T{
Support for eselect, Gentoo\(aqs configuration and management tool.
T}
_
T{
\fBetcd_mod\fP
T} T{
Execution module to work with etcd
T}
_
T{
\fBevent\fP
T} T{
Use the \fBSalt Event System\fP to fire events from the master to the minion and vice\-versa.
T}
_
T{
\fBextfs\fP
T} T{
Module for managing ext2/3/4 file systems
T}
_
T{
\fBfile\fP
T} T{
Manage information about regular files, directories,
T}
_
T{
\fBfreebsd_sysctl\fP
T} T{
Module for viewing and modifying sysctl parameters
T}
_
T{
\fBfreebsdjail\fP
T} T{
The jail module for FreeBSD
T}
_
T{
\fBfreebsdkmod\fP
T} T{
Module to manage FreeBSD kernel modules
T}
_
T{
\fBfreebsdpkg\fP
T} T{
Remote package support using \fBpkg_add(1)\fP
T}
_
T{
\fBfreebsdports\fP
T} T{
Install software from the FreeBSD \fBports(7)\fP system
T}
_
T{
\fBfreebsdservice\fP
T} T{
The service module for FreeBSD
T}
_
T{
\fBgem\fP
T} T{
Manage ruby gems.
T}
_
T{
\fBgenesis\fP
T} T{
Module for managing container and VM images
T}
_
T{
\fBgentoo_service\fP
T} T{
Top level package command wrapper, used to translate the os detected by grains
T}
_
T{
\fBgentoolkitmod\fP
T} T{
Support for Gentoolkit
T}
_
T{
\fBgit\fP
T} T{
Support for the Git SCM
T}
_
T{
\fBglance\fP
T} T{
Module for handling openstack glance calls.
T}
_
T{
\fBglusterfs\fP
T} T{
Manage a glusterfs pool
T}
_
T{
\fBgnomedesktop\fP
T} T{
GNOME implementations
T}
_
T{
\fBgrains\fP
T} T{
Return/control aspects of the grains data
T}
_
T{
\fBgroupadd\fP
T} T{
Manage groups on Linux and OpenBSD
T}
_
T{
\fBgrub_legacy\fP
T} T{
Support for GRUB Legacy
T}
_
T{
\fBguestfs\fP
T} T{
Interact with virtual machine images via libguestfs
T}
_
T{
\fBhadoop\fP
T} T{
Support for hadoop
T}
_
T{
\fBhaproxyconn\fP
T} T{
Support for haproxy
T}
_
T{
\fBhashutil\fP
T} T{
A collection of hashing and encoding functions
T}
_
T{
\fBhg\fP
T} T{
Support for the Mercurial SCM
T}
_
T{
\fBhosts\fP
T} T{
Manage the information in the hosts file
T}
_
T{
\fBhtpasswd\fP
T} T{
Support for htpasswd command
T}
_
T{
\fBimg\fP
T} T{
Virtual machine image management tools
T}
_
T{
\fBincron\fP
T} T{
Work with incron
T}
_
T{
\fBinflux\fP
T} T{
InfluxDB \- A distributed time series database
T}
_
T{
\fBini_manage\fP
T} T{
Edit ini files
T}
_
T{
\fBintrospect\fP
T} T{
Functions to perform introspection on a minion, and return data in a format
T}
_
T{
\fBipset\fP
T} T{
Support for ipset
T}
_
T{
\fBiptables\fP
T} T{
Support for iptables
T}
_
T{
\fBjunos\fP
T} T{
Module for interfacing to Junos devices
T}
_
T{
\fBkey\fP
T} T{
Functions to view the minion\(aqs public key information
T}
_
T{
\fBkeyboard\fP
T} T{
Module for managing keyboards on supported POSIX\-like systems using systemd, or such as Redhat, Debian and Gentoo.
T}
_
T{
\fBkeystone\fP
T} T{
Module for handling openstack keystone calls.
T}
_
T{
\fBkmod\fP
T} T{
Module to manage Linux kernel modules
T}
_
T{
\fBlaunchctl\fP
T} T{
Module for the management of MacOS systems that use launchd/launchctl
T}
_
T{
\fBlayman\fP
T} T{
Support for Layman
T}
_
T{
\fBldapmod\fP
T} T{
Salt interface to LDAP commands
T}
_
T{
\fBlinux_acl\fP
T} T{
Support for Linux File Access Control Lists
T}
_
T{
\fBlinux_lvm\fP
T} T{
Support for Linux LVM2
T}
_
T{
\fBlinux_sysctl\fP
T} T{
Module for viewing and modifying sysctl parameters
T}
_
T{
\fBlocalemod\fP
T} T{
Module for managing locales on POSIX\-like systems.
T}
_
T{
\fBlocate\fP
T} T{
Module for using the locate utilities
T}
_
T{
\fBlogadm\fP
T} T{
Module for managing Solaris logadm based log rotations.
T}
_
T{
\fBlogrotate\fP
T} T{
Module for managing logrotate.
T}
_
T{
\fBlvs\fP
T} T{
Support for LVS (Linux Virtual Server)
T}
_
T{
\fBlxc\fP
T} T{
Control Linux Containers via Salt
T}
_
T{
\fBmac_group\fP
T} T{
Manage groups on Mac OS 10.7+
T}
_
T{
\fBmac_user\fP
T} T{
Manage users on Mac OS 10.7+
T}
_
T{
\fBmacports\fP
T} T{
Support for MacPorts under Mac OSX.
T}
_
T{
\fBmakeconf\fP
T} T{
Support for modifying make.conf under Gentoo
T}
_
T{
\fBmatch\fP
T} T{
The match module allows for match routines to be run and determine target specs
T}
_
T{
\fBmdadm\fP
T} T{
Salt module to manage RAID arrays with mdadm
T}
_
T{
\fBmemcached\fP
T} T{
Module for Management of Memcached Keys
T}
_
T{
\fBmine\fP
T} T{
The function cache system allows for data to be stored on the master so it can be easily read by other minions
T}
_
T{
\fBmod_random\fP
T} T{
New in version 2014.7.0.
T}
_
T{
\fBmodjk\fP
T} T{
Control Modjk via the Apache Tomcat "Status" worker
T}
_
T{
\fBmongodb\fP
T} T{
Module to provide MongoDB functionality to Salt
T}
_
T{
\fBmonit\fP
T} T{
Monit service module.
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{
\fBmunin\fP
T} T{
Run munin plugins/checks from salt and format the output as data.
T}
_
T{
\fBmysql\fP
T} T{
Module to provide MySQL compatibility to salt.
T}
_
T{
\fBnagios\fP
T} T{
Run nagios plugins/checks from salt and get the return as data.
T}
_
T{
\fBnetbsd_sysctl\fP
T} T{
Module for viewing and modifying sysctl parameters
T}
_
T{
\fBnetbsdservice\fP
T} T{
The service module for NetBSD
T}
_
T{
\fBnetwork\fP
T} T{
Module for gathering and managing network information
T}
_
T{
\fBnfs3\fP
T} T{
Module for managing NFS version 3.
T}
_
T{
\fBnftables\fP
T} T{
Support for nftables
T}
_
T{
\fBnginx\fP
T} T{
Support for nginx
T}
_
T{
\fBnova\fP
T} T{
Module for handling OpenStack Nova calls
T}
_
T{
\fBnpm\fP
T} T{
Manage and query NPM packages.
T}
_
T{
\fBomapi\fP
T} T{
This module interacts with an ISC DHCP Server via OMAPI.
T}
_
T{
\fBopenbsdpkg\fP
T} T{
Package support for OpenBSD
T}
_
T{
\fBopenbsdservice\fP
T} T{
The service module for OpenBSD
T}
_
T{
\fBopenstack_config\fP
T} T{
Modify, retrieve, or delete values from OpenStack configuration files.
T}
_
T{
\fBoracle\fP
T} T{
Oracle DataBase connection module
T}
_
T{
\fBosxdesktop\fP
T} T{
Mac OS X implementations of various commands in the "desktop" interface
T}
_
T{
\fBpacman\fP
T} T{
A module to wrap pacman calls, since Arch is the best
T}
_
T{
\fBpagerduty\fP
T} T{
Module for Firing Events via PagerDuty
T}
_
T{
\fBpam\fP
T} T{
Support for pam
T}
_
T{
\fBparted\fP
T} T{
Module for managing partitions on POSIX\-like systems.
T}
_
T{
\fBpecl\fP
T} T{
Manage PHP pecl extensions.
T}
_
T{
\fBpillar\fP
T} T{
Extract the pillar data for this minion
T}
_
T{
\fBpip\fP
T} T{
Install Python packages with pip to either the system or a virtualenv
T}
_
T{
\fBpkg_resource\fP
T} T{
Resources needed by pkg providers
T}
_
T{
\fBpkgin\fP
T} T{
Package support for pkgin based systems, inspired from freebsdpkg module
T}
_
T{
\fBpkgng\fP
T} T{
Support for \fBpkgng\fP, the new package manager for FreeBSD
T}
_
T{
\fBpkgutil\fP
T} T{
Pkgutil support for Solaris
T}
_
T{
\fBportage_config\fP
T} T{
Configure \fBportage(5)\fP
T}
_
T{
\fBpostfix\fP
T} T{
Support for Postfix
T}
_
T{
\fBpostgres\fP
T} T{
Module to provide Postgres compatibility to salt.
T}
_
T{
\fBpoudriere\fP
T} T{
Support for poudriere
T}
_
T{
\fBpowerpath\fP
T} T{
powerpath support.
T}
_
T{
\fBps\fP
T} T{
A salt interface to psutil, a system and process library.
T}
_
T{
\fBpublish\fP
T} T{
Publish a command from a minion to a target
T}
_
T{
\fBpuppet\fP
T} T{
Execute puppet routines
T}
_
T{
\fBpw_group\fP
T} T{
Manage groups on FreeBSD
T}
_
T{
\fBpw_user\fP
T} T{
Manage users with the useradd command
T}
_
T{
\fBpyenv\fP
T} T{
Manage python installations with pyenv.
T}
_
T{
\fBqemu_img\fP
T} T{
Qemu\-img Command Wrapper
T}
_
T{
\fBqemu_nbd\fP
T} T{
Qemu Command Wrapper
T}
_
T{
\fBquota\fP
T} T{
Module for managing quotas on POSIX\-like systems.
T}
_
T{
\fBrabbitmq\fP
T} T{
Module to provide RabbitMQ compatibility to Salt.
T}
_
T{
\fBraet_publish\fP
T} T{
Publish a command from a minion to a target
T}
_
T{
\fBrbenv\fP
T} T{
Manage ruby installations with rbenv.
T}
_
T{
\fBrdp\fP
T} T{
Manage RDP Service on Windows servers
T}
_
T{
\fBredismod\fP
T} T{
Module to provide redis functionality to Salt
T}
_
T{
\fBreg\fP
T} T{
Manage the registry on Windows
T}
_
T{
\fBrest_package\fP
T} T{
Service support for the REST example
T}
_
T{
\fBrest_sample\fP
T} T{
Module for interfacing to the REST example
T}
_
T{
\fBrest_service\fP
T} T{
Service support for the REST example
T}
_
T{
\fBret\fP
T} T{
Module to integrate with the returner system and retrieve data sent to a salt returner
T}
_
T{
\fBrh_ip\fP
T} T{
The networking module for RHEL/Fedora based distros
T}
_
T{
\fBrh_service\fP
T} T{
Service support for RHEL\-based systems, including support for both upstart and sysvinit
T}
_
T{
\fBriak\fP
T} T{
Riak Salt Module
T}
_
T{
\fBrpm\fP
T} T{
Support for rpm
T}
_
T{
\fBrsync\fP
T} T{
Wrapper for rsync
T}
_
T{
\fBrvm\fP
T} T{
Manage ruby installations and gemsets with RVM, the Ruby Version Manager.
T}
_
T{
\fBs3\fP
T} T{
Connection module for Amazon S3
T}
_
T{
\fBsaltcloudmod\fP
T} T{
Control a salt cloud system
T}
_
T{
\fBsaltutil\fP
T} T{
The Saltutil module is used to manage the state of the salt minion itself.
T}
_
T{
\fBschedule\fP
T} T{
Module for manging the Salt schedule on a minion
T}
_
T{
\fBseed\fP
T} T{
Virtual machine image management tools
T}
_
T{
\fBselinux\fP
T} T{
Execute calls on selinux
T}
_
T{
\fBsensors\fP
T} T{
Read lm\-sensors
T}
_
T{
\fBserverdensity_device\fP
T} T{
Wrapper around Server Density API
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{
\fBsmartos_imgadm\fP
T} T{
Module for running imgadm command on SmartOS
T}
_
T{
\fBsmartos_vmadm\fP
T} T{
Module for managing VMs on SmartOS
T}
_
T{
\fBsmf\fP
T} T{
Service support for Solaris 10 and 11, should work with other systems that use SMF also.
T}
_
T{
\fBsmtp\fP
T} T{
Module for Sending Messages via SMTP
T}
_
T{
\fBsoftwareupdate\fP
T} T{
Support for the softwareupdate command on MacOS.
T}
_
T{
\fBsolaris_group\fP
T} T{
Manage groups on Solaris
T}
_
T{
\fBsolaris_shadow\fP
T} T{
Manage the password database on Solaris systems
T}
_
T{
\fBsolaris_user\fP
T} T{
Manage users with the useradd command
T}
_
T{
\fBsolarispkg\fP
T} T{
Package support for Solaris
T}
_
T{
\fBsolr\fP
T} T{
Apache Solr Salt Module
T}
_
T{
\fBsqlite3\fP
T} T{
Support for SQLite3
T}
_
T{
\fBssh\fP
T} T{
Manage client ssh components
T}
_
T{
\fBstate\fP
T} T{
Control the state system on the minion
T}
_
T{
\fBstatus\fP
T} T{
Module for returning various status data about a minion.
T}
_
T{
\fBsupervisord\fP
T} T{
Provide the service module for system supervisord or supervisord in a
T}
_
T{
\fBsvn\fP
T} T{
Subversion SCM
T}
_
T{
\fBswift\fP
T} T{
Module for handling OpenStack Swift calls
T}
_
T{
\fBsysbench\fP
T} T{
The \(aqsysbench\(aq module is used to analyze the performance of the minions, right from the master! It measures various system parameters such as CPU, Memory, File I/O, Threads and Mutex.
T}
_
T{
\fBsysmod\fP
T} T{
The sys module provides information about the available functions on the minion
T}
_
T{
\fBsystem\fP
T} T{
Support for reboot, shutdown, etc
T}
_
T{
\fBsystemd\fP
T} T{
Provide the service module for systemd
T}
_
T{
\fBtest\fP
T} T{
Module for running arbitrary tests
T}
_
T{
\fBtimezone\fP
T} T{
Module for managing timezone on POSIX\-like systems.
T}
_
T{
\fBtls\fP
T} T{
A salt module for SSL/TLS.
T}
_
T{
\fBtomcat\fP
T} T{
Support for Tomcat
T}
_
T{
\fBtwilio_notify\fP
T} T{
Module for notifications via Twilio
T}
_
T{
\fBupstart\fP
T} T{
Module for the management of upstart systems.
T}
_
T{
\fBuseradd\fP
T} T{
Manage users with the useradd command
T}
_
T{
\fBuwsgi\fP
T} T{
uWSGI stats server \fI\%http://uwsgi\-docs.readthedocs.org/en/latest/StatsServer.html\fP
T}
_
T{
\fBvarnish\fP
T} T{
Support for Varnish
T}
_
T{
\fBvirt\fP
T} T{
Work with virtual machines managed by libvirt
T}
_
T{
\fBvirtualenv_mod\fP
T} T{
Create virtualenv environments
T}
_
T{
\fBwin_autoruns\fP
T} T{
Module for listing programs that automatically run on startup
T}
_
T{
\fBwin_disk\fP
T} T{
Module for gathering disk information on Windows
T}
_
T{
\fBwin_dns_client\fP
T} T{
Module for configuring DNS Client on Windows systems
T}
_
T{
\fBwin_file\fP
T} T{
Manage information about files on the minion, set/read user, group
T}
_
T{
\fBwin_firewall\fP
T} T{
Module for configuring Windows Firewall
T}
_
T{
\fBwin_groupadd\fP
T} T{
Manage groups on Windows
T}
_
T{
\fBwin_ip\fP
T} T{
The networking module for Windows based systems
T}
_
T{
\fBwin_network\fP
T} T{
Module for gathering and managing network information
T}
_
T{
\fBwin_ntp\fP
T} T{
Management of NTP servers on Windows
T}
_
T{
\fBwin_path\fP
T} T{
Manage the Windows System PATH
T}
_
T{
\fBwin_pkg\fP
T} T{
A module to manage software on Windows
T}
_
T{
\fBwin_repo\fP
T} T{
Module to manage Windows software repo on a Standalone Minion
T}
_
T{
\fBwin_servermanager\fP
T} T{
Manage Windows features via the ServerManager powershell module
T}
_
T{
\fBwin_service\fP
T} T{
Windows Service module.
T}
_
T{
\fBwin_shadow\fP
T} T{
Manage the shadow file
T}
_
T{
\fBwin_status\fP
T} T{
Module for returning various status data about a minion.
T}
_
T{
\fBwin_system\fP
T} T{
Support for reboot, shutdown, etc
T}
_
T{
\fBwin_timezone\fP
T} T{
Module for managing timezone on Windows systems.
T}
_
T{
\fBwin_update\fP
T} T{
Module for running windows updates.
T}
_
T{
\fBwin_useradd\fP
T} T{
Manage Windows users with the net user command
T}
_
T{
\fBxapi\fP
T} T{
This module (mostly) uses the XenAPI to manage Xen virtual machines.
T}
_
T{
\fBxmpp\fP
T} T{
Module for Sending Messages via XMPP (a.k.a.
T}
_
T{
\fByumpkg\fP
T} T{
Support for YUM
T}
_
T{
\fBzcbuildout\fP
T} T{
Management of zc.buildout
T}
_
T{
\fBzfs\fP
T} T{
Salt interface to ZFS commands
T}
_
T{
\fBznc\fP
T} T{
znc \- An advanced IRC bouncer
T}
_
T{
\fBzpool\fP
T} T{
Module for running ZFS zpool command
T}
_
T{
\fBzypper\fP
T} T{
Package support for openSUSE via the zypper package manager
T}
_
.TE
.SS salt.modules.aliases
.sp
Manage the information in the aliases file
.INDENT 0.0
.TP
.B salt.modules.aliases.get_target(alias)
Return the target associated with an alias
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq aliases.get_target alias
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aliases.has_target(alias, target)
Return true if the alias/target is set
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq aliases.has_target alias target
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aliases.list_aliases()
Return the aliases found in the aliases file in this format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqalias\(aq: \(aqtarget\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq aliases.list_aliases
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aliases.rm_alias(alias)
Remove an entry from the aliases file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq aliases.rm_alias alias
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aliases.set_target(alias, target)
Set the entry in the aliases file for the given alias, this will overwrite
any previous entry for the given alias or create a new one if it does not
exist.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq aliases.set_target alias target
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.alternatives
.sp
Support for Alternatives system
.INDENT 0.0
.TP
.B codeauthor
Radek Rada <\fI\%radek.rada@gmail.com\fP>
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.alternatives.auto(name)
Trigger alternatives to set the path for <name> as
specified by priority.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq alternatives.auto name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.alternatives.check_installed(name, path)
Check if the current highest\-priority match for a given alternatives link
is set to the desired path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq alternatives.check_installed name path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.alternatives.display(name)
Display alternatives settings for defined command name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq alternatives.display editor
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.alternatives.install(name, link, path, priority)
Install symbolic links determining default commands
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq alternatives.install editor /usr/bin/editor /usr/bin/emacs23 50
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.alternatives.remove(name, path)
Remove symbolic links determining the default commands.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq alternatives.remove name path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.alternatives.set_(name, path)
Manually set the alternative <path> for <name>.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq alternatives.set name path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.alternatives.show_current(name)
Display the current highest\-priority alternative for a given alternatives
link
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq alternatives.show_current editor
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.apache
.sp
Support for Apache
.sp
Please note: The functions in here are generic functions designed to work with
all implementations of Apache. Debian\-specific functions have been moved into
deb_apache.py, but will still load under the \fBapache\fP namespace when a
Debian\-based system is detected.
.INDENT 0.0
.TP
.B salt.modules.apache.config(name, config, edit=True)
Create VirtualHost configuration files
.INDENT 7.0
.TP
.B name
File for the virtual host
.TP
.B config
VirtualHost configurations
.UNINDENT
.sp
Note: This function is not meant to be used from the command line.
Config is meant to be an ordered dict of all of the apache configs.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.config /etc/httpd/conf.d/ports.conf config="[{\(aqListen\(aq: \(aq22\(aq}]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.directives
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.fullversion()
Return server version from apachectl \-V
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.fullversion
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.modules()
Return list of static and shared modules from apachectl \-M
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.modules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.server_status(profile=\(aqdefault\(aq)
Get Information from the Apache server\-status handler
.sp
NOTE:
the server\-status handler is disabled by default.
in order for this function to work it needs to be enabled.
\fI\%http://httpd.apache.org/docs/2.2/mod/mod_status.html\fP
.sp
The following configuration needs to exists in pillar/grains
each entry nested in apache.server\-status is a profile of a vhost/server
this would give support for multiple apache servers/vhosts
.INDENT 7.0
.TP
.B apache.server\-status:
.INDENT 7.0
.TP
.B \(aqdefault\(aq:
\(aqurl\(aq: \fI\%http://localhost/server\-status\fP
\(aquser\(aq: someuser
\(aqpass\(aq: password
\(aqrealm\(aq: \(aqauthentication realm for digest passwords\(aq
\(aqtimeout\(aq: 5
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.server_status
salt \(aq*\(aq apache.server_status other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.servermods()
Return list of modules compiled into the server (apachectl \-l)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.servermods
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.signal(signal=None)
Signals httpd to start, restart, or stop.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.signal restart
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.useradd(pwfile, user, password, opts=\(aq\(aq)
Add an HTTP user using the htpasswd command. If the htpasswd file does not
exist, it will be created. Valid options that can be passed are:
.INDENT 7.0
.INDENT 3.5
n Don\(aqt update file; display results on stdout.
m Force MD5 encryption of the password (default).
d Force CRYPT encryption of the password.
p Do not encrypt the password (plaintext).
s Force SHA encryption of the password.
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.useradd /etc/httpd/htpasswd larry badpassword
salt \(aq*\(aq apache.useradd /etc/httpd/htpasswd larry badpass opts=ns
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.userdel(pwfile, user)
Delete an HTTP user from the specified htpasswd file.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.userdel /etc/httpd/htpasswd larry
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.apache.version()
Return server version from apachectl \-v
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.version
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-t 10 \(aq*\(aq apache.vhosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.aptpkg
.sp
Support for APT (Advanced Packaging Tool)
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For virtual package support, either the \fBpython\-apt\fP or \fBdctrl\-tools\fP
package must be installed.
.sp
For repository management, the \fBpython\-apt\fP package must be installed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.del_repo(repo, **kwargs)
Delete a repo from the sources.list / sources.list.d
.sp
If the .list file is in the sources.list.d directory
and the file that the repo exists in does not contain any other
repo configuration, the file itself will be deleted.
.sp
The repo passed in must be a fully formed repository definition
string.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.del_repo "myrepo definition"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.expand_repo_def(repokwargs)
Take a repository definition and expand it to the full pkg repository dict
that can be used for comparison. This is a helper function to make
the Debian/Ubuntu apt sources sane for comparison in the pkgrepo states.
.sp
There is no use to calling this function via the CLI.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.file_dict(*packages)
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of _every_ file on the system\(aqs
package database (not generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.file_list(*packages)
List the files that belong to a package. Not specifying any packages will
return a list of _every_ file on the system\(aqs package database (not
generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.get_repo(repo, **kwargs)
Display a repo from the sources.list / sources.list.d
.sp
The repo passed in needs to be a complete repo entry.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.get_repo "myrepo definition"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.get_selections(pattern=None, state=None)
View package state from the dpkg database.
.sp
Returns a dict of dicts containing the state, and package names:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<host>\(aq:
{\(aq<state>\(aq: [\(aqpkg1\(aq,
...
]
},
...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.get_selections
salt \(aq*\(aq pkg.get_selections \(aqpython\-*\(aq
salt \(aq*\(aq pkg.get_selections state=hold
salt \(aq*\(aq pkg.get_selections \(aqopenssh*\(aq state=hold
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.hold(name=None, pkgs=None, sources=None, **kwargs)
New in version 2014.7.0.
.sp
Set package in \(aqhold\(aq state, meaning it will not be upgraded.
.INDENT 7.0
.TP
.B name
The name of the package, e.g., \(aqtmux\(aq
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.hold <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B pkgs
A list of packages to hold. Must be passed as a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.hold pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.install(name=None, refresh=False, fromrepo=None, skip_verify=False, debconf=None, pkgs=None, sources=None, **kwargs)
Install the passed package, add refresh=True to update the dpkg database.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Note that this parameter is
ignored if either "pkgs" or "sources" is passed. Additionally, please
note that this option can only be used to install packages from a
software repository. To install a package file manually, use the
"sources" option.
.sp
32\-bit packages can be installed on 64\-bit systems by appending the
architecture designation (\fB:i386\fP, etc.) to the end of the package
name.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B refresh
Whether or not to refresh the package database before installing.
.TP
.B fromrepo
Specify a package repository to install from
(e.g., \fBapt\-get \-t unstable install somepackage\fP)
.TP
.B skip_verify
Skip the GPG verification check (e.g., \fB\-\-allow\-unauthenticated\fP, or
\fB\-\-force\-bad\-verify\fP for install from package file).
.TP
.B debconf
Provide the path to a debconf answers file, processed before
installation.
.TP
.B version
Install a specific version of the package, e.g. 1.2.3~0ubuntu0. Ignored
if "pkgs" or "sources" is passed.
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from a software repository. Must be
passed as a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-0ubuntu0"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B sources
A list of DEB packages to install. Must be passed as a list of dicts,
with the keys being package names, and the values being the source URI
or local path to the package. Dependencies are automatically resolved
and marked as auto\-installed.
.sp
32\-bit packages can be installed on 64\-bit systems by appending the
architecture designation (\fB:i386\fP, etc.) to the end of the package
name.
.sp
Changed in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B force_yes
Passes \fB\-\-force\-yes\fP to the apt\-get command. Don\(aqt use this unless
you know what you\(aqre doing.
.sp
New in version 0.17.4.
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
A specific repo can be requested using the \fBfromrepo\fP keyword argument.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package name> fromrepo=unstable
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.list_pkgs(versions_as_list=False, removed=False, purge_desired=False, **kwargs)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B removed
If \fBTrue\fP, then only packages which have been removed (but not
purged) will be returned.
.TP
.B purge_desired
If \fBTrue\fP, then only packages which have been marked to be purged,
but can\(aqt be purged due to their status as dependencies for other
installed packages, will be returned. Note that these packages will
appear in installed
.sp
Changed in version 2014.1.1: Packages in this state now correctly show up in the output of this
function.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
External dependencies
.sp
Virtual package resolution requires the \fBdctrl\-tools\fP package to be
installed. Virtual packages will show a version of \fB1\fP\&.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
salt \(aq*\(aq pkg.list_pkgs versions_as_list=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.list_repos()
Lists all repos in the sources.list (and sources.lists.d) files
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_repos
salt \(aq*\(aq pkg.list_repos disabled=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.list_upgrades(refresh=True)
List all available package upgrades.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.mod_repo(repo, saltenv=\(aqbase\(aq, **kwargs)
Modify one or more values for a repo. If the repo does not exist, it will
be created, so long as the definition is well formed. For Ubuntu the
"ppa:<project>/repo" format is acceptable. "ppa:" format can only be
used to create a new repository.
.sp
The following options are available to modify a repo definition:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
comps (a comma separated list of components for the repo, e.g. "main")
file (a file name to be used)
keyserver (keyserver to get gpg key from)
keyid (key id to load with the keyserver argument)
key_url (URL to a gpg key to add to the apt gpg keyring)
consolidate (if true, will attempt to de\-dup and consolidate sources)
* Note: Due to the way keys are stored for apt, there is a known issue
where the key wont be updated unless another change is made
at the same time. Keys should be properly added on initial
configuration.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.mod_repo \(aqmyrepo definition\(aq uri=http://new/uri
salt \(aq*\(aq pkg.mod_repo \(aqmyrepo definition\(aq comps=main,universe
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.owner(*paths)
New in version 2014.7.0.
.sp
Return the name of the package that owns the file. Multiple file paths can
be passed. Like \fBpkg.version <salt.modules.aptpkg.version\fP, if a
single path is passed, a string will be returned, and if multiple paths are
passed, a dictionary of file/package name pairs will be returned.
.sp
If the file is not owned by a package, or is not present on the minion,
then an empty string will be returned for that path.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq pkg.owner /usr/bin/apachectl
salt \(aq*\(aq pkg.owner /usr/bin/apachectl /usr/bin/basename
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.purge(name=None, pkgs=None, **kwargs)
Remove packages via \fBapt\-get purge\fP along with all configuration files.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.refresh_db()
Updates the APT database to latest packages based upon repositories
.sp
Returns a dict, with the keys being package databases and the values being
the result of the update attempt. Values can be one of the following:
.INDENT 7.0
.IP \(bu 2
\fBTrue\fP: Database updated successfully
.IP \(bu 2
\fBFalse\fP: Problem updating database
.IP \(bu 2
\fBNone\fP: Database already up\-to\-date
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.remove(name=None, pkgs=None, **kwargs)
Remove packages using \fBapt\-get remove\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.set_selections(path=None, selection=None, clear=False, saltenv=\(aqbase\(aq)
Change package state in the dpkg database.
.sp
The state can be any one of, documented in \fBdpkg(1)\fP:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
install
.IP \(bu 2
hold
.IP \(bu 2
deinstall
.IP \(bu 2
purge
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This command is commonly used to mark specific packages to be held from
being upgraded, that is, to be kept at a certain version. When a state is
changed to anything but being held, then it is typically followed by
\fBapt\-get \-u dselect\-upgrade\fP\&.
.sp
Note: Be careful with the \fBclear\fP argument, since it will start
with setting all packages to deinstall state.
.sp
Returns a dict of dicts containing the package names, and the new and old
versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<host>\(aq:
{\(aq<package>\(aq: {\(aqnew\(aq: \(aq<new\-state>\(aq,
\(aqold\(aq: \(aq<old\-state>\(aq}
},
...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.set_selections selection=\(aq{"install": ["netcat"]}\(aq
salt \(aq*\(aq pkg.set_selections selection=\(aq{"hold": ["openssh\-server", "openssh\-client"]}\(aq
salt \(aq*\(aq pkg.set_selections salt://path/to/file
salt \(aq*\(aq pkg.set_selections salt://path/to/file clear=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.unhold(name=None, pkgs=None, sources=None, **kwargs)
New in version 2014.7.0.
.sp
Set package current in \(aqhold\(aq state to install state,
meaning it will be upgraded.
.INDENT 7.0
.TP
.B name
The name of the package, e.g., \(aqtmux\(aq
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.unhold <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B pkgs
A list of packages to hold. Must be passed as a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.unhold pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.upgrade(refresh=True, dist_upgrade=True)
Upgrades all packages via \fBapt\-get dist\-upgrade\fP
.sp
Returns a dict containing the changes.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B dist_upgrade
Whether to perform the upgrade using dist\-upgrade vs upgrade. Default
is to use dist\-upgrade.
.UNINDENT
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.upgrade_available(name)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aptpkg.version_cmp(pkg1, pkg2)
Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if
pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem
making the comparison.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version_cmp \(aq0.2.4\-0ubuntu1\(aq \(aq0.2.4.1\-0ubuntu1\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.archive
.sp
A module to wrap (non\-Windows) archive calls
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B salt.modules.archive.gunzip(gzipfile, template=None)
Uses the gunzip command to unpack gzip files
.INDENT 7.0
.TP
.B template
None
Can be set to \(aqjinja\(aq or another supported template engine to render
the command arguments before execution:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.gunzip template=jinja /tmp/{{grains.id}}.txt.gz
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Create /tmp/sourcefile.txt
salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt.gz
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.gzip(sourcefile, template=None)
Uses the gzip command to create gzip files
.INDENT 7.0
.TP
.B template
None
Can be set to \(aqjinja\(aq or another supported template engine to render
the command arguments before execution:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.gzip template=jinja /tmp/{{grains.id}}.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Create /tmp/sourcefile.txt.gz
salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.rar(rarfile, sources, template=None, cwd=None)
Uses \fI\%rar for Linux\fP to create rar files
.INDENT 7.0
.TP
.B rarfile
Path of rar file to be created
.TP
.B sources
Comma\-separated list of sources to include in the rar file. Sources can
also be passed in a python list.
.TP
.B cwd
None
Run the rar command from the specified directory. Use this argument
along with relative file paths to create rar files which do not
contain the leading directories. If not specified, this will default
to the home directory of the user under which the salt minion process
is running.
.sp
New in version 2014.7.1.
.TP
.B template
None
Can be set to \(aqjinja\(aq or another supported template engine to render
the command arguments before execution:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.rar template=jinja /tmp/rarfile.rar \(aq/tmp/sourcefile1,/tmp/{{grains.id}}.txt\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.rar /tmp/rarfile.rar /tmp/sourcefile1,/tmp/sourcefile2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.tar(options, tarfile, sources=None, dest=None, cwd=None, template=None)
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function has changed for version 0.17.0. In prior versions, the
\fBcwd\fP and \fBtemplate\fP arguments must be specified, with the source
directories/files coming as a space\-separated list at the end of the
command. Beginning with 0.17.0, \fBsources\fP must be a comma\-separated
list, and the \fBcwd\fP and \fBtemplate\fP arguments are optional.
.UNINDENT
.UNINDENT
.sp
Uses the tar command to pack, unpack, etc. tar files
.INDENT 7.0
.TP
.B options
Options to pass to the tar command
.TP
.B tarfile
The filename of the tar archive to pack/unpack
.TP
.B sources
Comma delimited list of files to \fBpack\fP into the tarfile. Can also be
passed as a python list.
.TP
.B dest
The destination directory into which to \fBunpack\fP the tarfile
.TP
.B cwd
None
The directory in which the tar command should be executed. If not
specified, will default to the home directory of the user under which
the salt minion process is running.
.TP
.B template
None
Can be set to \(aqjinja\(aq or another supported template engine to render
the command arguments before execution:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.tar cjvf /tmp/salt.tar.bz2 {{grains.saltpath}} template=jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Create a tarfile
salt \(aq*\(aq archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file_1,/tmp/file_2
# Unpack a tarfile
salt \(aq*\(aq archive.tar xf foo.tar dest=/target/directory
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.unrar(rarfile, dest, excludes=None, template=None)
Uses \fI\%rar for Linux\fP to unpack rar files
.INDENT 7.0
.TP
.B rarfile
Name of rar file to be unpacked
.TP
.B dest
The destination directory into which to \fBunpack\fP the rar file
.TP
.B template
None
Can be set to \(aqjinja\(aq or another supported template engine to render
the command arguments before execution:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.unrar template=jinja /tmp/rarfile.rar /tmp/{{grains.id}}/ excludes=file_1,file_2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.unrar /tmp/rarfile.rar /home/strongbad/ excludes=file_1,file_2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.unzip(zipfile, dest, excludes=None, template=None, options=None)
.INDENT 7.0
.TP
.B Uses the \fBunzip\fP command to unpack zip files. This command is part of the
\fI\%Info\-ZIP\fP suite of tools, and is typically packaged as simply \fBunzip\fP\&.
.INDENT 7.0
.TP
.B zipfile
Path of zip file to be unpacked
.TP
.B dest
The destination directory into which the file should be unpacked
.TP
.B excludes
None
Comma\-separated list of files not to unpack. Can also be passed in a
Python list.
.TP
.B template
None
Can be set to \(aqjinja\(aq or another supported template engine to render
the command arguments before execution:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.unzip template=jinja /tmp/zipfile.zip /tmp/{{grains.id}}/ excludes=file_1,file_2
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B options
None
Additional command\-line options to pass to the \fBunzip\fP binary.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.archive.zip_(zipfile, sources, template=None, cwd=None)
Uses the \fBzip\fP command to create zip files. This command is part of the
\fI\%Info\-ZIP\fP suite of tools, and is typically packaged as simply \fBzip\fP\&.
.INDENT 7.0
.TP
.B zipfile
Path of zip file to be created
.TP
.B sources
Comma\-separated list of sources to include in the zip file. Sources can
also be passed in a Python list.
.TP
.B template
None
Can be set to \(aqjinja\(aq or another supported template engine to render
the command arguments before execution:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1,/tmp/{{grains.id}}.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B cwd
None
Use this argument along with relative paths in \fBsources\fP to create
zip files which do not contain the leading directories. If not
specified, the zip file will be created as if the cwd was \fB/\fP, and
creating a zip file of \fB/foo/bar/baz.txt\fP will contain the parent
directories \fBfoo\fP and \fBbar\fP\&. To create a zip file containing just
\fBbaz.txt\fP, the following command would be used:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.zip /tmp/baz.zip baz.txt cwd=/foo/bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 2014.7.1.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq archive.zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.at
.sp
Wrapper module for at(1)
.sp
Also, a \(aqtag\(aq feature has been added to more
easily tag jobs.
.INDENT 0.0
.TP
.B salt.modules.at.at(*args, **kwargs)
Add a job to the queue.
.sp
The \(aqtimespec\(aq follows the format documented in the
at(1) manpage.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq at.at <timespec> <cmd> [tag=<tag>] [runas=<user>]
salt \(aq*\(aq at.at 12:05am \(aq/sbin/reboot\(aq tag=reboot
salt \(aq*\(aq at.at \(aq3:05am +3 days\(aq \(aqbin/myscript\(aq tag=nightly runas=jim
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.at.atc(jobid)
Print the at(1) script that will run for the passed job
id. This is mostly for debugging so the output will
just be text.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq at.atc <jobid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.at.atq(tag=None)
List all queued and running jobs or only those with
an optional \(aqtag\(aq.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq at.atq
salt \(aq*\(aq at.atq [tag]
salt \(aq*\(aq at.atq [job number]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.at.atrm(*args)
Remove jobs from the queue.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq at.atrm <jobid> <jobid> .. <jobid>
salt \(aq*\(aq at.atrm all
salt \(aq*\(aq at.atrm all [tag]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.at.jobcheck(**kwargs)
Check the job from queue.
The kwargs dict include \(aqhour minute day month year tag runas\(aq
Other parameters will be ignored.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq at.jobcheck runas=jam day=13
salt \(aq*\(aq at.jobcheck day=13 month=12 year=13 tag=rose
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.augeas_cfg
.sp
Manages configuration files via augeas
.sp
This module requires the \fBaugeas\fP Python module.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Minimal installations of Debian and Ubuntu have been seen to have packaging
bugs with python\-augeas, causing the augeas module to fail to import. If
the minion has the augeas module installed, but the functions in this
execution module fail to run due to being unavailable, first restart the
salt\-minion service. If the problem persists past that, the following
command can be run from the master to determine what is causing the import
to fail:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt minion\-id cmd.run \(aqpython \-c "from augeas import Augeas"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For affected Debian/Ubuntu hosts, installing \fBlibpython2.7\fP has been
known to resolve the issue.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.augeas_cfg.execute(context=None, lens=None, commands=())
Execute Augeas commands
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.execute /files/etc/redis/redis.conf commands=\(aq["set bind 0.0.0.0", "set maxmemory 1G"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.augeas_cfg.get(path, value=\(aq\(aq)
Get a value for a specific augeas path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.get /files/etc/hosts/1/ ipaddr
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.augeas_cfg.ls(path)
List the direct children of a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.ls /files/etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.augeas_cfg.match(path, value=\(aq\(aq)
Get matches for path expression
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.match /files/etc/services/service\-name ssh
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.augeas_cfg.remove(path)
Get matches for path expression
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.remove /files/etc/sysctl.conf/net.ipv4.conf.all.log_martians
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.augeas_cfg.setvalue(*args)
Set a value for a specific augeas path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.setvalue /files/etc/hosts/1/canonical localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will set the first entry in /etc/hosts to localhost
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.setvalue /files/etc/hosts/01/ipaddr 192.168.1.1 \e
/files/etc/hosts/01/canonical test
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Adds a new host to /etc/hosts the ip address 192.168.1.1 and hostname test
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.setvalue prefix=/files/etc/sudoers/ \e
"spec[user = \(aq%wheel\(aq]/user" "%wheel" \e
"spec[user = \(aq%wheel\(aq]/host_group/host" \(aqALL\(aq \e
"spec[user = \(aq%wheel\(aq]/host_group/command[1]" \(aqALL\(aq \e
"spec[user = \(aq%wheel\(aq]/host_group/command[1]/tag" \(aqPASSWD\(aq \e
"spec[user = \(aq%wheel\(aq]/host_group/command[2]" \(aq/usr/bin/apt\-get\(aq \e
"spec[user = \(aq%wheel\(aq]/host_group/command[2]/tag" NOPASSWD
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Ensures that the following line is present in /etc/sudoers:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
%wheel ALL = PASSWD : ALL , NOPASSWD : /usr/bin/apt\-get , /usr/bin/aptitude
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.augeas_cfg.tree(path)
Returns recursively the complete tree of a node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq augeas.tree /files/etc/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.aws_sqs
.sp
Support for the Amazon Simple Queue Service.
.INDENT 0.0
.TP
.B salt.modules.aws_sqs.create_queue(name, region, opts=None, user=None)
Creates a queue with the correct name.
.INDENT 7.0
.TP
.B name
Name of the SQS queue to create
.TP
.B region
Region to create the SQS queue in
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aws_sqs.delete_message(queue, region, receipthandle, opts=None, user=None)
Delete one or more messages from a queue in a region
.INDENT 7.0
.TP
.B queue
The name of the queue to delete messages from
.TP
.B region
Region where SQS queues exists
.TP
.B receipthandle
The ReceiptHandle of the message to delete. The ReceiptHandle
is obtained in the return from receive_message
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq aws_sqs.delete_message <sqs queue> <region> receipthandle=\(aq<sqs ReceiptHandle>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 2014.7.0.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aws_sqs.delete_queue(name, region, opts=None, user=None)
Deletes a queue in the region.
.INDENT 7.0
.TP
.B name
Name of the SQS queue to deletes
.TP
.B region
Name of the region to delete the queue from
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aws_sqs.list_queues(region, opts=None, user=None)
List the queues in the selected region.
.INDENT 7.0
.TP
.B region
Region to list SQS queues for
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aws_sqs.queue_exists(name, region, opts=None, user=None)
Returns True or False on whether the queue exists in the region
.INDENT 7.0
.TP
.B name
Name of the SQS queue to search for
.TP
.B region
Name of the region to search for the queue in
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.aws_sqs.receive_message(queue, region, num=1, opts=None, user=None)
Receive one or more messages from a queue in a region
.INDENT 7.0
.TP
.B queue
The name of the queue to receive messages from
.TP
.B region
Region where SQS queues exists
.TP
.B num
1
The max number of messages to receive
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq aws_sqs.receive_message <sqs queue> <region>
salt \(aq*\(aq aws_sqs.receive_message <sqs queue> <region> num=10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 2014.7.0.
.UNINDENT
.SS salt.modules.blockdev
.sp
Module for managing block devices
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B salt.modules.blockdev.dump(device, args=None)
Return all contents of dumpe2fs for a specified device
.sp
CLI Example:
.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq extfs.dump /dev/sda1
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.blockdev.tune(device, **kwargs)
Set attributes for the specified device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq blockdev.tune /dev/sda1 read\-ahead=1024 read\-write=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Valid options are: \fBread\-ahead\fP, \fBfilesystem\-read\-ahead\fP,
\fBread\-only\fP, \fBread\-write\fP\&.
.sp
See the \fBblockdev(8)\fP manpage for a more complete description of these
options.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.blockdev.wipe(device)
Remove the filesystem information
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq blockdev.wipe /dev/sda1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.bluez
.sp
Support for Bluetooth (using BlueZ in Linux).
.sp
The following packages are required packages for this module:
.INDENT 0.0
.INDENT 3.5
bluez >= 5.7
bluez\-libs >= 5.7
bluez\-utils >= 5.7
pybluez >= 0.18
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.address_()
Get the many addresses of the Bluetooth adapter
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.address
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.block(bdaddr)
Block a specific bluetooth device by BD Address
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.block DE:AD:BE:EF:CA:FE
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.discoverable(dev)
Enable this bluetooth device to be discoverable.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.discoverable hci0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.noscan(dev)
Turn off scanning modes on this device.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.noscan hci0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.pair(address, key)
Pair the bluetooth adapter with a device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.pair DE:AD:BE:EF:CA:FE 1234
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where DE:AD:BE:EF:CA:FE is the address of the device to pair with, and 1234
is the passphrase.
.sp
TODO: This function is currently broken, as the bluez\-simple\-agent program
no longer ships with BlueZ >= 5.0. It needs to be refactored.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.power(dev, mode)
Power a bluetooth device on or off
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.power hci0 on
salt \(aq*\(aq bluetooth.power hci0 off
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.scan()
Scan for bluetooth devices in the area
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.scan
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.start()
Start the bluetooth service.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.start
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.stop()
Stop the bluetooth service.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.stop
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.unblock(bdaddr)
Unblock a specific bluetooth device by BD Address
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.unblock DE:AD:BE:EF:CA:FE
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.unpair(address)
Unpair the bluetooth adapter from a device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetooth.unpair DE:AD:BE:EF:CA:FE
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where DE:AD:BE:EF:CA:FE is the address of the device to unpair.
.sp
TODO: This function is currently broken, as the bluez\-simple\-agent program
no longer ships with BlueZ >= 5.0. It needs to be refactored.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bluez.version()
Return Bluez version from bluetoothd \-v
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bluetoothd.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_asg
.sp
Connection module for Amazon Autoscale Groups
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit autoscale credentials but can also
utilize IAM roles assigned to the instance trough Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
further configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
asg.keyid: GKTADJGHEIQSXMKKRBJ08H
asg.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A region may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
asg.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.create(name, launch_config_name, availability_zones, min_size, max_size, desired_capacity=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, tags=None, termination_policies=None, suspended_processes=None, scaling_policies=None, region=None, key=None, keyid=None, profile=None)
Create an autoscale group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.create myasg mylc \(aq["us\-east\-1a", "us\-east\-1e"]\(aq 1 10 load_balancers=\(aq["myelb", "myelb2"]\(aq tags=\(aq[{"key": "Name", value="myasg", "propagate_at_launch": True}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.create_launch_configuration(name, image_id, key_name=None, security_groups=None, user_data=None, instance_type=\(aqm1.small\(aq, kernel_id=None, ramdisk_id=None, block_device_mappings=None, instance_monitoring=False, spot_price=None, instance_profile_name=None, ebs_optimized=False, associate_public_ip_address=None, volume_type=None, delete_on_termination=True, iops=None, use_block_device_types=False, region=None, key=None, keyid=None, profile=None)
Create a launch configuration.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.create_launch_configuration mylc image_id=ami\-0b9c9f62 key_name=\(aqmykey\(aq security_groups=\(aq["mygroup"]\(aq instance_type=\(aqc3.2xlarge\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.delete(name, force=False, region=None, key=None, keyid=None, profile=None)
Delete an autoscale group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.delete myasg region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.delete_launch_configuration(name, region=None, key=None, keyid=None, profile=None)
Delete a launch configuration.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.delete_launch_configuration mylc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.exists(name, region=None, key=None, keyid=None, profile=None)
Check to see if an autoscale group exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.exists myasg region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.get_cloud_init_mime(cloud_init)
Get a mime multipart encoded string from a cloud\-init dict. Currently
supports scripts and cloud\-config.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto.get_cloud_init_mime <cloud init>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.get_config(name, region=None, key=None, keyid=None, profile=None)
Get the configuration for an autoscale group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.get_config myasg region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.get_scaling_policy_arn(as_group, scaling_policy_name, region=None, key=None, keyid=None, profile=None)
Return the arn for a scaling policy in a specific autoscale group or None
if not found. Mainly used as a helper method for boto_cloudwatch_alarm, for
linking alarms to scaling policies.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq boto_asg.get_scaling_policy_arn mygroup mypolicy
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.launch_configuration_exists(name, region=None, key=None, keyid=None, profile=None)
Check for a launch configuration\(aqs existence.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.launch_configuration_exists mylc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_asg.update(name, launch_config_name, availability_zones, min_size, max_size, desired_capacity=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, tags=None, termination_policies=None, suspended_processes=None, scaling_policies=None, region=None, key=None, keyid=None, profile=None)
Update an autoscale group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_asg.update myasg mylc \(aq["us\-east\-1a", "us\-east\-1e"]\(aq 1 10 load_balancers=\(aq["myelb", "myelb2"]\(aq tags=\(aq[{"key": "Name", value="myasg", "propagate_at_launch": True}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_cloudwatch
.sp
Connection module for Amazon CloudWatch
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit credentials but can also utilize
IAM roles assigned to the instance trough Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
cloudwatch.keyid: GKTADJGHEIQSXMKKRBJ08H
cloudwatch.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A region may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
cloudwatch.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_cloudwatch.convert_to_arn(arns, region=None, key=None, keyid=None, profile=None)
Convert a list of strings into actual arns. Converts convenience names such
as \(aqscaling_policy:...\(aq
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq convert_to_arn \(aqscaling_policy:\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_cloudwatch.create_or_update_alarm(connection=None, name=None, metric=None, namespace=None, statistic=None, comparison=None, threshold=None, period=None, evaluation_periods=None, unit=None, description=\(aq\(aq, dimensions=None, alarm_actions=None, insufficient_data_actions=None, ok_actions=None, region=None, key=None, keyid=None, profile=None)
Create or update a cloudwatch alarm.
.INDENT 7.0
.TP
.B Params are the same as:
\fI\%http://boto.readthedocs.org/en/latest/ref/cloudwatch.html#boto.ec2.cloudwatch.alarm.MetricAlarm\fP\&.
.UNINDENT
.sp
Dimensions must be a dict. If the value of Dimensions is a string, it will
be json decoded to produce a dict. alarm_actions, insufficient_data_actions,
and ok_actions must be lists of string. If the passed\-in value is a string,
it will be split on "," to produce a list. The strings themselves for
alarm_actions, insufficient_data_actions, and ok_actions must be Amazon
resource names (ARN\(aqs); however, this method also supports an arn lookup
notation, as follows:
.INDENT 7.0
.INDENT 3.5
arn:aws:.... ARN as per http://docs.aws.amazon.com/general/latest/gr/aws\-arns\-and\-namespaces.html
scaling_policy:<as_name>:<scaling_policy_name> The named autoscale group scaling policy, for the named group (e.g. scaling_policy:my\-asg:ScaleDown)
.UNINDENT
.UNINDENT
.sp
This is convenient for setting up autoscaling as follows. First specify a
boto_asg.present state for an ASG with scaling_policies, and then set up
boto_cloudwatch_alarm.present states which have alarm_actions that
reference the scaling_policy.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
salt myminion boto_cloudwatch.create_alarm name=myalarm ... region=us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_cloudwatch.delete_alarm(name, region=None, key=None, keyid=None, profile=None)
Delete a cloudwatch alarm
.sp
CLI example to delete a queue:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_cloudwatch.delete_alarm myalarm region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_cloudwatch.get_alarm(name, region=None, key=None, keyid=None, profile=None)
Get alarm details. Also can be used to check to see if an alarm exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_cloudwatch.get_alarm myalarm region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_cloudwatch.get_all_alarms(region=None, prefix=None, key=None, keyid=None, profile=None)
Get all alarm details. Produces results that can be used to create an sls
file.
.sp
If prefix parameter is given, alarm names in the output will be prepended
with the prefix; alarms that have the prefix will be skipped. This can be
used to convert existing alarms to be managed by salt, as follows:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
.INDENT 3.0
.TP
.B Make a "backup" of all existing alarms
$ salt\-call boto_cloudwatch.get_all_alarms \-\-out=txt | sed "s/local: //" > legacy_alarms.sls
.UNINDENT
.IP 2. 3
.INDENT 3.0
.TP
.B Get all alarms with new prefixed names
$ salt\-call boto_cloudwatch.get_all_alarms "prefix=**MANAGED BY SALT** " \-\-out=txt | sed "s/local: //" > managed_alarms.sls
.UNINDENT
.IP 3. 3
.INDENT 3.0
.TP
.B Insert the managed alarms into cloudwatch
$ salt\-call state.template managed_alarms.sls
.UNINDENT
.IP 4. 3
Manually verify that the new alarms look right
.IP 5. 3
Delete the original alarms
$ sed s/present/absent/ legacy_alarms.sls > remove_legacy_alarms.sls
$ salt\-call state.template remove_legacy_alarms.sls
.IP 6. 3
Get all alarms again, verify no changes
$ salt\-call boto_cloudwatch.get_all_alarms \-\-out=txt | sed "s/local: //" > final_alarms.sls
$ diff final_alarms.sls managed_alarms.sls
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_cloudwatch.get_all_alarms region=us\-east\-1 \-\-out=txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_elasticache
.sp
Connection module for Amazon Elasticache
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit elasticache credentials but can
also utilize IAM roles assigned to the instance trough Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
further configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
elasticache.keyid: GKTADJGHEIQSXMKKRBJ08H
elasticache.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A region may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
elasticache.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.authorize_cache_security_group_ingress(name, ec2_security_group_name, ec2_security_group_owner_id, region=None, key=None, keyid=None, profile=None)
Authorize network ingress from an ec2 security group to a cache security
group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.authorize_cache_security_group_ingress myelasticachesg myec2sg 879879
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.create(name, num_cache_nodes, engine, cache_node_type, replication_group_id=None, engine_version=None, cache_parameter_group_name=None, cache_subnet_group_name=None, cache_security_group_names=None, security_group_ids=None, snapshot_arns=None, preferred_availability_zone=None, preferred_maintenance_window=None, port=None, notification_topic_arn=None, auto_minor_version_upgrade=True, wait=False, region=None, key=None, keyid=None, profile=None)
Create a cache cluster.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.create myelasticache 1 redis cache.t1.micro cache_security_group_names=\(aq["myelasticachesg"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.create_cache_security_group(name, description, region=None, key=None, keyid=None, profile=None)
Create a cache security group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.create_cache_security_group myelasticachesg \(aqMy Cache Security Group\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.delete(name, wait=False, region=None, key=None, keyid=None, profile=None)
Delete a cache cluster.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.delete myelasticache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.delete_cache_security_group(name, region=None, key=None, keyid=None, profile=None)
Delete a cache security group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.delete_cache_security_group myelasticachesg \(aqMy Cache Security Group\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.exists(name, region=None, key=None, keyid=None, profile=None)
Check to see if a cache cluster exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.exists myelasticache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.get_cache_subnet_group(name, region=None, key=None, keyid=None, profile=None)
Get information about a cache subnet group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.get_cache_subnet_group mycache_subnet_group
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.get_config(name, region=None, key=None, keyid=None, profile=None)
Get the configuration for a cache cluster.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.get_config myelasticache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elasticache.revoke_cache_security_group_ingress(name, ec2_security_group_name, ec2_security_group_owner_id, region=None, key=None, keyid=None, profile=None)
Revoke network ingress from an ec2 security group to a cache security
group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elasticache.revoke_cache_security_group_ingress myelasticachesg myec2sg 879879
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_elb
.sp
Connection module for Amazon ELB
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit elb credentials but can also utilize
IAM roles assigned to the instance trough Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
elb.keyid: GKTADJGHEIQSXMKKRBJ08H
elb.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A region may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
elb.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.attach_subnets(name, subnets, region=None, key=None, keyid=None, profile=None)
Attach ELB to subnets.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.attach_subnets myelb \(aq["mysubnet"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.create(name, availability_zones, listeners=None, subnets=None, security_groups=None, scheme=\(aqinternet\-facing\(aq, region=None, key=None, keyid=None, profile=None)
Create an ELB
.sp
CLI example to create an ELB:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.create myelb \(aq["us\-east\-1a", "us\-east\-1e"]\(aq listeners=\(aq[["HTTPS", "HTTP", 443, 80, "arn:aws:iam::1111111:server\-certificate/mycert"]]\(aq region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.create_listeners(name, listeners=None, region=None, key=None, keyid=None, profile=None)
Create listeners on an ELB.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.create_listeners myelb listeners=\(aq[["HTTPS", "HTTP", 443, 80, "arn:aws:iam::11 11111:server\-certificate/mycert"]]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.delete(name, region=None, key=None, keyid=None, profile=None)
Delete an ELB.
.sp
CLI example to delete an ELB:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.delete myelb region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.delete_listeners(name, ports, region=None, key=None, keyid=None, profile=None)
Delete listeners on an ELB.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.delete_listeners myelb \(aq[80,443]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.deregister_instances(name, instances, region=None, key=None, keyid=None, profile=None)
Deregister instances with an ELB. Instances is either a string
instance id or a list of string instance id\(aqs.
.sp
Returns:
.INDENT 7.0
.IP \(bu 2
\fBTrue\fP: instance(s) deregistered successfully
.IP \(bu 2
\fBFalse\fP: instance(s) failed to be deregistered
.IP \(bu 2
\fBNone\fP: instance(s) not valid or not registered, no action taken
.UNINDENT
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.deregister_instances myelb instance_id
salt myminion boto_elb.deregister_instances myelb "[instance_id, instance_id]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.detach_subnets(name, subnets, region=None, key=None, keyid=None, profile=None)
Detach ELB from subnets.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.detach_subnets myelb \(aq["mysubnet"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.disable_availability_zones(name, availability_zones, region=None, key=None, keyid=None, profile=None)
Disable availability zones for ELB.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.disable_availability_zones myelb \(aq["us\-east\-1a"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.enable_availability_zones(name, availability_zones, region=None, key=None, keyid=None, profile=None)
Enable availability zones for ELB.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.enable_availability_zones myelb \(aq["us\-east\-1a"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.exists(name, region=None, key=None, keyid=None, profile=None)
Check to see if an ELB exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.exists myelb region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.get_attributes(name, region=None, key=None, keyid=None, profile=None)
Check to see if attributes are set on an ELB.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.get_attributes myelb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.get_elb_config(name, region=None, key=None, keyid=None, profile=None)
Check to see if an ELB exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.exists myelb region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.get_health_check(name, region=None, key=None, keyid=None, profile=None)
Get the health check configured for this ELB.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.get_health_check myelb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.get_instance_health(name, region=None, key=None, keyid=None, profile=None, instances=None)
Get a list of instances and their health state
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.get_instance_health myelb
salt myminion boto_elb.get_instance_health myelb region=us\-east\-1 instances="[instance_id,instance_id]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.register_instances(name, instances, region=None, key=None, keyid=None, profile=None)
Register instances with an ELB. Instances is either a string
instance id or a list of string instance id\(aqs.
.sp
Returns:
.INDENT 7.0
.IP \(bu 2
\fBTrue\fP: instance(s) registered successfully
.IP \(bu 2
\fBFalse\fP: instance(s) failed to be registered
.UNINDENT
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.register_instances myelb instance_id
salt myminion boto_elb.register_instances myelb "[instance_id,instance_id]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.set_attributes(name, attributes, region=None, key=None, keyid=None, profile=None)
Set attributes on an ELB.
.sp
CLI example to set attributes on an ELB:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.set_attributes myelb \(aq{"access_log": {"enabled": "true", "s3_bucket_name": "mybucket", "s3_bucket_prefix": "mylogs/", "emit_interval": "5"}}\(aq region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_elb.set_health_check(name, health_check, region=None, key=None, keyid=None, profile=None)
Set attributes on an ELB.
.sp
CLI example to set attributes on an ELB:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_elb.set_health_check myelb \(aq{"target": "HTTP:80/"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_iam
.sp
Connection module for Amazon IAM
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit iam credentials but can also utilize
IAM roles assigned to the instance trough Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
iam.keyid: GKTADJGHEIQSXMKKRBJ08H
iam.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
iam.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.associate_profile_to_role(profile_name, role_name, region=None, key=None, keyid=None, profile=None)
Associate an instance profile with an IAM role.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.associate_profile_to_role myirole myiprofile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.create_instance_profile(name, region=None, key=None, keyid=None, profile=None)
Create an instance profile.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.create_instance_profile myiprofile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.create_role(name, policy_document=None, path=None, region=None, key=None, keyid=None, profile=None)
Create an instance role.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.create_role myrole
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.create_role_policy(role_name, policy_name, policy, region=None, key=None, keyid=None, profile=None)
Create or modify a role policy.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.create_role_policy myirole mypolicy \(aq{"MyPolicy": "Statement": [{"Action": ["sqs:*"], "Effect": "Allow", "Resource": ["arn:aws:sqs:*:*:*"], "Sid": "MyPolicySqs1"}]}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.delete_instance_profile(name, region=None, key=None, keyid=None, profile=None)
Delete an instance profile.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.delete_instance_profile myiprofile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.delete_role(name, region=None, key=None, keyid=None, profile=None)
Delete an IAM role.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.delete_role myirole
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.delete_role_policy(role_name, policy_name, region=None, key=None, keyid=None, profile=None)
Delete a role policy.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.delete_role_policy myirole mypolicy
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.disassociate_profile_from_role(profile_name, role_name, region=None, key=None, keyid=None, profile=None)
Disassociate an instance profile from an IAM role.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.disassociate_profile_from_role myirole myiprofile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.get_role_policy(role_name, policy_name, region=None, key=None, keyid=None, profile=None)
Get a role policy.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.get_role_policy myirole mypolicy
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.instance_profile_exists(name, region=None, key=None, keyid=None, profile=None)
Check to see if an instance profile exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.instance_profile_exists myiprofile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.list_role_policies(role_name, region=None, key=None, keyid=None, profile=None)
Get a list of policy names from a role.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.list_role_policies myirole
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.profile_associated(role_name, profile_name, region, key, keyid, profile)
Check to see if an instance profile is associated with an IAM role.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.profile_associated myirole myiprofile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_iam.role_exists(name, region=None, key=None, keyid=None, profile=None)
Check to see if an IAM role exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_iam.role_exists myirole
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_route53
.sp
Connection module for Amazon Route53
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit route53 credentials but can also
utilize IAM roles assigned to the instance trough Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
further configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
route53.keyid: GKTADJGHEIQSXMKKRBJ08H
route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A region may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
route53.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_route53.add_record(name, value, zone, record_type, identifier=None, ttl=None, region=None, key=None, keyid=None, profile=None)
Add a record to a zone.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_route53.add_record test.example.org 1.1.1.1 example.org A
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_route53.delete_record(name, zone, record_type, identifier=None, all_records=False, region=None, key=None, keyid=None, profile=None)
Modify a record in a zone.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_route53.delete_record test.example.org example.org A
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_route53.get_record(name, zone, record_type, fetch_all=False, region=None, key=None, keyid=None, profile=None)
Get a record from a zone.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_route53.get_record test.example.org example.org A
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_route53.update_record(name, value, zone, record_type, identifier=None, ttl=None, region=None, key=None, keyid=None, profile=None)
Modify a record in a zone.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_route53.modify_record test.example.org 1.1.1.1 example.org A
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_secgroup
.sp
Connection module for Amazon Security Groups
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit ec2 credentials but can
also utilize IAM roles assigned to the instance trough Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
further configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
secgroup.keyid: GKTADJGHEIQSXMKKRBJ08H
secgroup.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A region may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
secgroup.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.authorize(name=None, source_group_name=None, source_group_owner_id=None, ip_protocol=None, from_port=None, to_port=None, cidr_ip=None, group_id=None, source_group_group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None)
Add a new rule to an existing security group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.authorize mysecgroup ip_protocol=tcp from_port=80 to_port=80 cidr_ip=\(aq[\(aq10.0.0.0/8\(aq, \(aq192.168.0.0/24\(aq]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.convert_to_group_ids(groups, vpc_id, region=None, key=None, keyid=None, profile=None)
Given a list of security groups and a vpc_id, convert_to_group_ids will
convert all list items in the given list to security group ids.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.convert_to_group_ids mysecgroup vpc\-89yhh7h
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.create(name, description, vpc_id=None, region=None, key=None, keyid=None, profile=None)
Create an autoscale group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.create mysecgroup \(aqMy Security Group\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.delete(name=None, group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None)
Delete an autoscale group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.delete mysecgroup
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.exists(name=None, region=None, key=None, keyid=None, profile=None, vpc_id=None, group_id=None)
Check to see if an security group exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.exists mysecgroup
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.get_config(name=None, group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None)
Get the configuration for a security group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.get_config mysecgroup
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.get_group_id(name, vpc_id=None, region=None, key=None, keyid=None, profile=None)
Get a Group ID given a Group Name or Group Name and VPC ID
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.get_group_id mysecgroup
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_secgroup.revoke(name=None, source_group_name=None, source_group_owner_id=None, ip_protocol=None, from_port=None, to_port=None, cidr_ip=None, group_id=None, source_group_group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None)
Remove a rule from an existing security group.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_secgroup.revoke mysecgroup ip_protocol=tcp from_port=80 to_port=80 cidr_ip=\(aq10.0.0.0/8\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.boto_sqs
.sp
Connection module for Amazon SQS
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module accepts explicit sqs credentials but can also utilize
IAM roles assigned to the instance trough Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sqs.keyid: GKTADJGHEIQSXMKKRBJ08H
sqs.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A region may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sqs.region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_sqs.create(name, region=None, key=None, keyid=None, profile=None)
Create an SQS queue.
.sp
CLI example to create a queue:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_sqs.create myqueue region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_sqs.delete(name, region=None, key=None, keyid=None, profile=None)
Delete an SQS queue.
.sp
CLI example to delete a queue:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_sqs.delete myqueue region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_sqs.exists(name, region=None, key=None, keyid=None, profile=None)
Check to see if a queue exists.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_sqs.exists myqueue region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_sqs.get_attributes(name, region=None, key=None, keyid=None, profile=None)
Check to see if attributes are set on an SQS queue.
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_sqs.get_attributes myqueue
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_sqs.set_attributes(name, attributes, region=None, key=None, keyid=None, profile=None)
Set attributes on an SQS queue.
.sp
CLI example to set attributes on a queue:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion boto_sqs.set_attributes myqueue \(aq{ReceiveMessageWaitTimeSeconds: 20}\(aq region=us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.brew
.sp
Homebrew for Mac OS X
.INDENT 0.0
.TP
.B salt.modules.brew.install(name=None, pkgs=None, taps=None, options=None, **kwargs)
Install the passed package(s) with \fBbrew install\fP
.INDENT 7.0
.TP
.B name
The name of the formula to be installed. Note that this parameter is
ignored if "pkgs" is passed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B taps
Unofficial Github repos to use when updating and installing formulas.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> tap=\(aq<tap>\(aq
salt \(aq*\(aq pkg.install zlib taps=\(aqhomebrew/dupes\(aq
salt \(aq*\(aq pkg.install php54 taps=\(aq["josegonzalez/php", "homebrew/dupes"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B options
Options to pass to brew. Only applies to initial install. Due to how brew
works, modifying chosen options requires a full uninstall followed by a
fresh install. Note that if "pkgs" is used, all options will be passed
to all packages. Unrecognized options for a package will be silently
ignored by brew.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> tap=\(aq<tap>\(aq
salt \(aq*\(aq pkg.install php54 taps=\(aq["josegonzalez/php", "homebrew/dupes"]\(aq options=\(aq["\-\-with\-fpm"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of formulas to install. Must be passed as a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install \(aqpackage package package\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation
.sp
Note that this currently not fully implemented but needs to return
something to avoid a traceback when calling pkg.latest.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.list_upgrades()
Check whether or not an upgrade is available for all packages
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.refresh_db()
Update the homebrew package repository.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.remove(name=None, pkgs=None, **kwargs)
Removes packages with \fBbrew uninstall\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.upgrade(refresh=True)
Upgrade outdated, unpinned brews.
.INDENT 7.0
.TP
.B refresh
Fetch the newest version of Homebrew and all formulae from GitHub before installing.
.UNINDENT
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.upgrade_available(pkg)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.brew.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.bridge
.sp
Module for gathering and managing bridging information
.INDENT 0.0
.TP
.B salt.modules.bridge.add(br=None)
Creates a bridge
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.add br0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.addif(br=None, iface=None)
Adds an interface to a bridge
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.addif br0 eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.delete(br=None)
Deletes a bridge
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.delete br0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.delif(br=None, iface=None)
Removes an interface from a bridge
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.delif br0 eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.find_interfaces(*args)
Returns the bridge to which the interfaces are bond to
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.find_interfaces eth0 [eth1...]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.interfaces(br=None)
Returns interfaces attached to a bridge
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.interfaces br0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.list_()
Returns the machine\(aqs bridges list
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.show(br=None)
Returns bridges interfaces along with enslaved physical interfaces. If
no interface is given, all bridges are shown, else only the specified
bridge values are returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.show
salt \(aq*\(aq bridge.show br0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bridge.stp(br=None, state=\(aqdisable\(aq, iface=None)
Sets Spanning Tree Protocol state for a bridge
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.stp br0 enable
salt \(aq*\(aq bridge.stp br0 disable
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For BSD\-like operating systems, it is required to add the interface on
which to enable the STP.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq bridge.stp bridge0 enable fxp0
salt \(aq*\(aq bridge.stp bridge0 disable fxp0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.bsd_shadow
.sp
Manage the password database on BSD systems
.INDENT 0.0
.TP
.B salt.modules.bsd_shadow.default_hash()
Returns the default hash used for unset passwords
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.default_hash
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bsd_shadow.info(name)
Return information for the specified user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.info someuser
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.bsd_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:
.sp
\fBpython \-c "import crypt; print crypt.crypt(\(aqpassword\(aq, ciphersalt)"\fP
.sp
\fBNOTE:\fP When constructing the \fBciphersalt\fP string, you must
escape any dollar signs, to avoid them being interpolated by the shell.
.sp
\fB\(aqpassword\(aq\fP is, of course, the password for which you want to generate
a hash.
.sp
\fBciphersalt\fP is a combination of a cipher identifier, an optional number
of rounds, and the cryptographic salt. The arrangement and format of these
fields depends on the cipher and which flavor of BSD you are using. For
more information on this, see the manpage for \fBcrpyt(3)\fP\&. On NetBSD,
additional information is available in \fBpasswd.conf(5)\fP\&.
.sp
It is important to make sure that a supported cipher is used.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_password someuser \(aq$1$UYCIxa628.9qXjpQCjM4a..\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.cassandra
.sp
Cassandra NoSQL Database Module
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
pycassa Cassandra Python adapter
.UNINDENT
.TP
.B configuration
The location of the \(aqnodetool\(aq command, host, and thrift port needs to be
specified via pillar:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
cassandra.nodetool: /usr/local/bin/nodetool
cassandra.host: localhost
cassandra.thrift_port: 9160
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.column_families(keyspace=None)
Return existing column families for all keyspaces
or just the provided one.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.column_families
salt \(aq*\(aq cassandra.column_families <keyspace>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.column_family_definition(keyspace=None, column_family=None)
Return a dictionary of column family definitions for the given
keyspace/column_family
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.column_family_definition <keyspace> <column_family>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.compactionstats()
Return compactionstats info
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.compactionstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.info()
Return cassandra node info
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.keyspaces()
Return existing keyspaces
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.keyspaces
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.netstats()
Return netstats info
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.netstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.ring()
Return cassandra ring info
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.ring
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.tpstats()
Return tpstats info
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.tpstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cassandra.version()
Return the cassandra version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cassandra.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.chef
.sp
Execute chef in server or solo mode
.INDENT 0.0
.TP
.B salt.modules.chef.client(whyrun=False, localmode=False, logfile=\(aq/var/log/chef\-client.log\(aq, **kwargs)
Execute a chef client run and return a dict with the stderr, stdout,
return code, and pid.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chef.client server=https://localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B server
The chef server URL
.TP
.B client_key
Set the client key file location
.TP
.B config
The configuration file to use
.TP
.B config\-file\-jail
Directory under which config files are allowed to be loaded
(no client.rb or knife.rb outside this path will be loaded).
.TP
.B environment
Set the Chef Environment on the node
.TP
.B group
Group to set privilege to
.TP
.B json\-attributes
Load attributes from a JSON file or URL
.TP
.B localmode
Point chef\-client at local repository if True
.TP
.B log_level
Set the log level (debug, info, warn, error, fatal)
.TP
.B logfile
Set the log file location
.TP
.B node\-name
The node name for this client
.TP
.B override\-runlist
Replace current run list with specified items for a single run
.TP
.B pid
Set the PID file location, defaults to /tmp/chef\-client.pid
.TP
.B run\-lock\-timeout
Set maximum duration to wait for another client run to finish,
default is indefinitely.
.TP
.B runlist
Permanently replace current run list with specified items
.TP
.B user
User to set privilege to
.TP
.B validation_key
Set the validation key file location, used for registering new clients
.TP
.B whyrun
Enable whyrun mode when set to True
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chef.solo(whyrun=False, logfile=\(aq/var/log/chef\-solo.log\(aq, **kwargs)
Execute a chef solo run and return a dict with the stderr, stdout,
return code, and pid.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chef.solo override\-runlist=test
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B config
The configuration file to use
.TP
.B environment
Set the Chef Environment on the node
.TP
.B group
Group to set privilege to
.TP
.B json\-attributes
Load attributes from a JSON file or URL
.TP
.B log_level
Set the log level (debug, info, warn, error, fatal)
.TP
.B logfile
Set the log file location
.TP
.B node\-name
The node name for this client
.TP
.B override\-runlist
Replace current run list with specified items for a single run
.TP
.B recipe\-url
Pull down a remote gzipped tarball of recipes and untar it to
the cookbook cache
.TP
.B run\-lock\-timeout
Set maximum duration to wait for another client run to finish,
default is indefinitely.
.TP
.B user
User to set privilege to
.TP
.B whyrun
Enable whyrun mode when set to True
.UNINDENT
.UNINDENT
.SS salt.modules.chocolatey
.sp
A dead simple module wrapping calls to the Chocolatey package manager
(\fI\%http://chocolatey.org\fP)
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B salt.modules.chocolatey.bootstrap(force=False)
Download and install the latest version of the Chocolatey package manager
via the official bootstrap.
.sp
Chocolatey requires Windows PowerShell and the .NET v4.0 runtime. Depending
on the host\(aqs version of Windows, chocolatey.bootstrap will attempt to
ensure these prerequisites are met by downloading and executing the
appropriate installers from Microsoft.
.sp
Note that if PowerShell is installed, you may have to restart the host
machine for Chocolatey to work.
.INDENT 7.0
.TP
.B force
Run the bootstrap process even if Chocolatey is found in the path.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.bootstrap
salt \(aq*\(aq chocolatey.bootstrap force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.chocolatey_version()
New in version 2014.7.0.
.sp
Returns the version of Chocolatey installed on the minion.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.chocolatey_version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.install(name, version=None, source=None, force=False)
Instructs Chocolatey to install a package.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Only accepts a single argument.
.TP
.B version
Install a specific version of the package. Defaults to latest version.
.TP
.B source
Chocolatey repository (directory, share or remote URL feed) the package
comes from. Defaults to the official Chocolatey feed.
.TP
.B force
Reinstall the current version of an existing package.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.install <package name>
salt \(aq*\(aq chocolatey.install <package name> version=<package version>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.install_cygwin(name)
Instructs Chocolatey to install a package via Cygwin.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Only accepts a single argument.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.install_cygwin <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.install_gem(name, version=None)
Instructs Chocolatey to install a package via Ruby\(aqs Gems.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Only accepts a single argument.
.TP
.B version
Install a specific version of the package. Defaults to latest version
available.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.install_gem <package name>
salt \(aq*\(aq chocolatey.install_gem <package name> version=<package version>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.install_missing(name, version=None, source=None)
Instructs Chocolatey to install a package if it doesn\(aqt already exist.
.sp
Changed in version 2014.7.0: If the minion has Chocolatey >= 0.9.8.24 installed, this function calls
\fI\%chocolatey.install\fP instead, as
\fBinstallmissing\fP is deprecated as of that version and will be removed
in Chocolatey 1.0.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Only accepts a single argument.
.TP
.B version
Install a specific version of the package. Defaults to latest version
available.
.TP
.B source
Chocolatey repository (directory, share or remote URL feed) the package
comes from. Defaults to the official Chocolatey feed.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.install_missing <package name>
salt \(aq*\(aq chocolatey.install_missing <package name> version=<package version>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.install_python(name, version=None)
Instructs Chocolatey to install a package via Python\(aqs easy_install.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Only accepts a single argument.
.TP
.B version
Install a specific version of the package. Defaults to latest version
available.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.install_python <package name>
salt \(aq*\(aq chocolatey.install_python <package name> version=<package version>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.install_webpi(name)
Instructs Chocolatey to install a package via the Microsoft Web PI service.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Only accepts a single argument.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.install_webpi <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.install_windowsfeatures(name)
Instructs Chocolatey to install a Windows Feature via the Deployment Image
Servicing and Management tool.
.INDENT 7.0
.TP
.B name
The name of the feature to be installed. Only accepts a single argument.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.install_windowsfeatures <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.list_(narrow, all_versions=False, pre_versions=False, source=None)
Instructs Chocolatey to pull a vague package list from the repository.
.INDENT 7.0
.TP
.B narrow
Term used to narrow down results. Searches against name/description/tag.
.TP
.B all_versions
Display all available package versions in results. Defaults to False.
.TP
.B pre_versions
Display pre\-release packages in results. Defaults to False.
.TP
.B source
Chocolatey repository (directory, share or remote URL feed) the package
comes from. Defaults to the official Chocolatey feed.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.list <narrow>
salt \(aq*\(aq chocolatey.list <narrow> all_versions=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.list_webpi()
Instructs Chocolatey to pull a full package list from the Microsoft Web PI
repository.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.list_webpi
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.list_windowsfeatures()
Instructs Chocolatey to pull a full package list from the Windows Features
list, via the Deployment Image Servicing and Management tool.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.list_windowsfeatures
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.uninstall(name, version=None)
Instructs Chocolatey to uninstall a package.
.INDENT 7.0
.TP
.B name
The name of the package to be uninstalled. Only accepts a single argument.
.TP
.B version
Uninstalls a specific version of the package. Defaults to latest version
installed.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq chocolatey.uninstall <package name>
salt \(aq*\(aq chocolatey.uninstall <package name> version=<package version>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.update(name, source=None, pre_versions=False)
Instructs Chocolatey to update packages on the system.
.INDENT 7.0
.TP
.B name
The name of the package to update, or "all" to update everything
installed on the system.
.TP
.B source
Chocolatey repository (directory, share or remote URL feed) the package
comes from. Defaults to the official Chocolatey feed.
.TP
.B pre_versions
Include pre\-release packages in comparison. Defaults to False.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt "*" chocolatey.update all
salt "*" chocolatey.update <package name> pre_versions=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.version(name, check_remote=False, source=None, pre_versions=False)
Instructs Chocolatey to check an installed package version, and optionally
compare it to one available from a remote feed.
.INDENT 7.0
.TP
.B name
The name of the package to check.
.TP
.B check_remote
Get the version number of the latest package from the remote feed.
Defaults to False.
.TP
.B source
Chocolatey repository (directory, share or remote URL feed) the package
comes from. Defaults to the official Chocolatey feed.
.TP
.B pre_versions
Include pre\-release packages in comparison. Defaults to False.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt "*" chocolatey.version <package name>
salt "*" chocolatey.version <package name> check_remote=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.cloud
.sp
Salt\-specific interface for calling Salt Cloud directly
.INDENT 0.0
.TP
.B salt.modules.cloud.action(fun=None, cloudmap=None, names=None, provider=None, instance=None, **kwargs)
Execute a single action on the given provider/instance
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.action start instance=myinstance
salt \(aq*\(aq cloud.action stop instance=myinstance
salt \(aq*\(aq cloud.action show_image provider=my\-ec2\-config image=ami\-1624987f
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.create(provider, names, **kwargs)
Create an instance using Salt Cloud
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.create my\-ec2\-config myinstance image=ami\-1624987f size=\(aqMicro Instance\(aq ssh_username=ec2\-user securitygroup=default delvol_on_destroy=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.destroy(names)
Destroy the named VM(s)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.destroy myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.full_query(query_type=\(aqlist_nodes_full\(aq)
List all available cloud provider data
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.full_query
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.list_images(provider=\(aqall\(aq)
List cloud provider images for the given providers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.list_images my\-gce\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.list_locations(provider=\(aqall\(aq)
List cloud provider locations for the given providers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.list_locations my\-gce\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.list_sizes(provider=\(aqall\(aq)
List cloud provider sizes for the given providers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.list_sizes my\-gce\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.network_create(provider, names, **kwargs)
Create private network
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.network_create my\-nova names=[\(aqsalt\(aq] cidr=\(aq192.168.100.0/24\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.network_list(provider)
List private networks
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.network_list my\-nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.profile_(profile, names, vm_overrides=None, **kwargs)
Spin up an instance using Salt Cloud
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.profile my\-gce\-config myinstance
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.query(query_type=\(aqlist_nodes\(aq)
List cloud provider data for all providers
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.query
salt \(aq*\(aq cloud.query list_nodes_full
salt \(aq*\(aq cloud.query list_nodes_select
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.select_query(query_type=\(aqlist_nodes_select\(aq)
List selected nodes
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cloud.select_query
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.virtual_interface_create(provider, names, **kwargs)
Attach private interfaces to a server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.virtual_interface_create my\-nova names=[\(aqsalt\-master\(aq] net_name=\(aqsalt\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.virtual_interface_list(provider, names, **kwargs)
List virtual interfaces on a server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.virtual_interface_list my\-nova names=[\(aqsalt\-master\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.volume_attach(provider, names, **kwargs)
Attach volume to a server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.volume_attach my\-nova myblock server_name=myserver device=\(aq/dev/xvdf\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.volume_create(provider, names, **kwargs)
Create volume
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.volume_create my\-nova myblock size=100 voltype=SSD
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.volume_delete(provider, names, **kwargs)
Delete volume
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.volume_delete my\-nova myblock
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.volume_detach(provider, names, **kwargs)
Detach volume from a server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.volume_detach my\-nova myblock server_name=myserver
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cloud.volume_list(provider)
List block storage volumes
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt minionname cloud.volume_list my\-nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.cmdmod
.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.cmdmod.exec_code(lang, code, cwd=None)
Pass in two strings, the first naming the executable language, aka \-
python2, python3, ruby, perl, lua, etc. the second string containing
the code you wish to execute. The stdout and stderr will be returned
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.exec_code ruby \(aqputs "cheese"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.has_exec(cmd)
Returns true if the executable is available on the minion, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.has_exec cat
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.retcode(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, clean_env=False, template=None, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs)
Execute a shell command and return the command\(aqs return code.
.sp
Note that \fBenv\fP represents the environment variables for the command, and
should be formatted as a dict, or a YAML string which resolves to a dict.
.INDENT 7.0
.TP
.B Return type
\fI\%int\fP
.TP
.B Return type
\fI\%None\fP
.TP
.B Returns
Return Code as an int or None if there was an exception.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.retcode "file /bin/bash"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The template arg can be set to \(aqjinja\(aq or another supported template
engine to render the command arguments before execution.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.retcode template=jinja "file {{grains.pythonpath[0]}}/python"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using
the \fBstdin\fP parameter. This can be useful in cases where sensitive
information must be read from standard input.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.retcode "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.run(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs)
Execute the passed command and return the output as a string
.sp
Note that \fBenv\fP represents the environment variables for the command, and
should be formatted as a dict, or a YAML string which resolves to a dict.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run "ls \-l | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The template arg can be set to \(aqjinja\(aq or another supported template
engine to render the command arguments before execution.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Specify an alternate shell with the shell parameter:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run "Get\-ChildItem C:\e " shell=\(aqpowershell\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using
the \fBstdin\fP parameter. This can be useful in cases where sensitive
information must be read from standard input.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If an equal sign (\fB=\fP) appears in an argument to a Salt command it is
interpreted as a keyword argument in the format \fBkey=val\fP\&. That
processing can be bypassed in order to pass an equal sign through to the
remote shell command by manually specifying the kwarg:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run cmd=\(aqsed \-e s/=/:/g\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.run_all(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs)
Execute the passed command and return a dict of return data
.sp
Note that \fBenv\fP represents the environment variables for the command, and
should be formatted as a dict, or a YAML string which resolves to a dict.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_all "ls \-l | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The template arg can be set to \(aqjinja\(aq or another supported template
engine to render the command arguments before execution.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_all template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using
the \fBstdin\fP parameter. This can be useful in cases where sensitive
information must be read from standard input.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_all "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.run_chroot(root, cmd)
New in version 2014.7.0.
.sp
This function runs \fI\%cmd.run_all\fP wrapped
within a chroot, with dev and proc mounted in the chroot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_chroot /var/lib/lxc/container_name/rootfs \(aqsh /tmp/bootstrap.sh\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.run_stderr(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs)
Execute a command and only return the standard error
.sp
Note that \fBenv\fP represents the environment variables for the command, and
should be formatted as a dict, or a YAML string which resolves to a dict.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stderr "ls \-l | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The template arg can be set to \(aqjinja\(aq or another supported template
engine to render the command arguments before execution.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stderr template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using
the \fBstdin\fP parameter. This can be useful in cases where sensitive
information must be read from standard input.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stderr "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.run_stdout(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, use_vt=False, **kwargs)
Execute a command, and only return the standard out
.sp
Note that \fBenv\fP represents the environment variables for the command, and
should be formatted as a dict, or a YAML string which resolves to a dict.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stdout "ls \-l | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The template arg can be set to \(aqjinja\(aq or another supported template
engine to render the command arguments before execution.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stdout template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using
the \fBstdin\fP parameter. This can be useful in cases where sensitive
information must be read from standard input.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run_stdout "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.script(source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, template=\(aqjinja\(aq, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(aq, use_vt=False, **kwargs)
Download a script from a remote location and execute the script locally.
The script can be located on the salt master file server or on an HTTP/FTP
server.
.sp
The script will be executed directly, so it can be written in any available
programming language.
.sp
The script can also be formatted as a template, the default is jinja.
Arguments for the script can be specified as well.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.script salt://scripts/runme.sh
salt \(aq*\(aq cmd.script salt://scripts/runme.sh \(aqarg1 arg2 "arg 3"\(aq
salt \(aq*\(aq cmd.script salt://scripts/windows_task.ps1 args=\(aq \-Input c:\etmp\einfile.txt\(aq shell=\(aqpowershell\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using
the \fBstdin\fP parameter. This can be useful in cases where sensitive
information must be read from standard input.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.script salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.script_retcode(source, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, python_shell=True, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(aq, output_loglevel=\(aqdebug\(aq, use_vt=False, **kwargs)
Download a script from a remote location and execute the script locally.
The script can be located on the salt master file server or on an HTTP/FTP
server.
.sp
The script will be executed directly, so it can be written in any available
programming language.
.sp
The script can also be formatted as a template, the default is jinja.
.sp
Only evaluate the script return code and do not block for terminal output
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using
the \fBstdin\fP parameter. This can be useful in cases where sensitive
information must be read from standard input.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.tty(device, echo=None)
Echo a string to a specific tty
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.tty tty0 \(aqThis is a test\(aq
salt \(aq*\(aq cmd.tty pts3 \(aqThis is a test\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.which(cmd)
Returns the path of an executable available on the minion, None otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.which cat
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cmdmod.which_bin(cmds)
Returns the first command found in a list of commands
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.which_bin \(aq[pip2, pip, pip\-python]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.composer
.sp
Use composer to install PHP dependencies for a directory
.INDENT 0.0
.TP
.B salt.modules.composer.install(dir, composer=None, php=None, runas=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, quiet=False, composer_home=\(aq/root\(aq)
Install composer dependencies for a directory.
.sp
If composer has not been installed globally making it available in the
system PATH & making it executable, the \fBcomposer\fP and \fBphp\fP parameters
will need to be set to the location of the executables.
.INDENT 7.0
.TP
.B dir
Directory location of the composer.json file.
.TP
.B composer
Location of the composer.phar file. If not set composer will
just execute "composer" as if it is installed globally.
(i.e. /path/to/composer.phar)
.TP
.B php
Location of the php executable to use with composer.
(i.e. /usr/bin/php)
.TP
.B runas
Which system user to run composer as.
.TP
.B prefer_source
\-\-prefer\-source option of composer.
.TP
.B prefer_dist
\-\-prefer\-dist option of composer.
.TP
.B no_scripts
\-\-no\-scripts option of composer.
.TP
.B no_plugins
\-\-no\-plugins option of composer.
.TP
.B optimize
\-\-optimize\-autoloader option of composer. Recommended for production.
.TP
.B no_dev
\-\-no\-dev option for composer. Recommended for production.
.TP
.B quiet
\-\-quiet option for composer. Whether or not to return output from composer.
.TP
.B composer_home
$COMPOSER_HOME environment variable
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq composer.install /var/www/application
salt \(aq*\(aq composer.install /var/www/application no_dev=True optimize=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.config
.sp
Return config information
.INDENT 0.0
.TP
.B salt.modules.config.backup_mode(backup=\(aq\(aq)
Return the backup mode
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.backup_mode
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.config.dot_vals(value)
Pass in a configuration value that should be preceded by the module name
and a dot, this will return a list of all read key/value pairs
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.dot_vals host
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.config.gather_bootstrap_script(bootstrap=None)
Download the salt\-bootstrap script, and return its location
.INDENT 7.0
.TP
.B bootstrap
URL of alternate bootstrap script
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.gather_bootstrap_script
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.config.get(key, default=\(aq\(aq)
Attempt to retrieve the named value from opts, pillar, grains or the master
config, if the named value is not available return the passed default.
The default return is an empty string.
.sp
The value can also represent a value in a nested dict using a ":" delimiter
for the dict. This means that if a dict looks like this:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To retrieve the value associated with the apache key in the pkg dict this
key can be passed:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This routine traverses these data stores in this order:
.INDENT 7.0
.IP \(bu 2
Local minion config (opts)
.IP \(bu 2
Minion\(aqs grains
.IP \(bu 2
Minion\(aqs pillar
.IP \(bu 2
Master config
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.get pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.config.manage_mode(mode)
Return a mode value, normalized to a string
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.manage_mode
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.config.merge(value, default=\(aq\(aq, omit_opts=False, omit_master=False, omit_pillar=False)
Retrieves an option based on key, merging all matches.
.sp
Same as \fBoption()\fP except that it merges all matches, rather than taking
the first match.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.merge schedule
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.config.option(value, default=\(aq\(aq, omit_opts=False, omit_master=False, omit_pillar=False)
Pass in a generic option and receive the value that will be assigned
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.option redis.host
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.config.valid_fileproto(uri)
Returns a boolean value based on whether or not the URI passed has a valid
remote file protocol designation
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq config.valid_fileproto salt://path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.cp
.sp
Minion side functions for salt\-cp
.INDENT 0.0
.TP
.B salt.modules.cp.cache_dir(path, saltenv=\(aqbase\(aq, include_empty=False, include_pat=None, exclude_pat=None, env=None)
Download and cache everything under a directory from the master
.INDENT 7.0
.TP
.B include_pat
None
Glob or regex to narrow down the files cached from the given path. If
matching with a regex, the regex must be prefixed with \fBE@\fP,
otherwise the expression will be interpreted as a glob.
.sp
New in version 2014.7.0.
.TP
.B exclude_pat
None
Glob or regex to exclude certain files from being cached from the given
path. If matching with a regex, the regex must be prefixed with \fBE@\fP,
otherwise the expression will be interpreted as a glob.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If used with \fBinclude_pat\fP, files matching this pattern will be
excluded from the subset of files defined by \fBinclude_pat\fP\&.
.UNINDENT
.UNINDENT
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.cache_dir salt://path/to/dir
salt \(aq*\(aq cp.cache_dir salt://path/to/dir include_pat=\(aqE@*.py$\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.cache_file(path, saltenv=\(aqbase\(aq, env=None)
Used to cache a single file on the salt\-minion
Returns the location of the new cached file on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.cache_file salt://path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.cache_files(paths, saltenv=\(aqbase\(aq, env=None)
Used to gather many files from the master, the gathered files will be
saved in the minion cachedir reflective to the paths retrieved from the
master.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.cache_files salt://pathto/file1,salt://pathto/file1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.cache_local_file(path)
Cache a local file on the minion in the localfiles cache
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.cache_local_file /etc/hosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.cache_master(saltenv=\(aqbase\(aq, env=None)
Retrieve all of the files on the master and cache them locally
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.cache_master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.get_dir(path, dest, saltenv=\(aqbase\(aq, template=None, gzip=None, env=None)
Used to recursively copy a directory from the salt master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.get_dir salt://path/to/dir/ /minion/dest
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
get_dir supports the same template and gzip arguments as get_file.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.get_file(path, dest, saltenv=\(aqbase\(aq, makedirs=False, template=None, gzip=None, env=None)
Used to get a single file from the salt master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.get_file salt://path/to/file /minion/dest
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Template rendering can be enabled on both the source and destination file
names like so:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example would instruct all Salt minions to download the vimrc from a
directory with the same name as their os grain and copy it to /etc/vimrc
.sp
For larger files, the cp.get_file module also supports gzip compression.
Because gzip is CPU\-intensive, this should only be used in scenarios where
the compression ratio is very high (e.g. pretty\-printed JSON or YAML
files).
.sp
Use the \fIgzip\fP named argument to enable it. Valid values are 1..9, where 1
is the lightest compression and 9 the heaviest. 1 uses the least CPU on
the master (and minion), 9 uses the most.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.get_file_str(path, saltenv=\(aqbase\(aq, env=None)
Return the contents of a file from a URL
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.get_file_str salt://my/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.get_template(path, dest, template=\(aqjinja\(aq, saltenv=\(aqbase\(aq, env=None, makedirs=False, **kwargs)
Render a file as a template before setting it down.
Warning, order is not the same as in fileclient.cp for
non breaking old API.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.get_template salt://path/to/template /minion/dest
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.get_url(path, dest, saltenv=\(aqbase\(aq, env=None)
Used to get a single file from a URL.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.get_url salt://my/file /tmp/mine
salt \(aq*\(aq cp.get_url http://www.slashdot.org /tmp/index.html
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.hash_file(path, saltenv=\(aqbase\(aq, env=None)
Return the hash of a file, to get the hash of a file on the
salt master file server prepend the path with salt://<file on server>
otherwise, prepend the file with / for a local file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.hash_file salt://path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.is_cached(path, saltenv=\(aqbase\(aq, env=None)
Return a boolean if the given path on the master has been cached on the
minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.is_cached salt://path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.list_master(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None)
List all of the files stored on the master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.list_master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.list_master_dirs(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None)
List all of the directories stored on the master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.list_master_dirs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.list_master_symlinks(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None)
List all of the symlinks stored on the master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.list_master_symlinks
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.list_minion(saltenv=\(aqbase\(aq, env=None)
List all of the files cached on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.list_minion
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.list_states(saltenv=\(aqbase\(aq, env=None)
List all of the available state modules in an environment
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.list_states
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.push(path)
Push a file from the minion up to the master, the file will be saved to
the salt master in the master\(aqs minion files cachedir
(defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP)
.sp
Since this feature allows a minion to push a file up to the master server
it is disabled by default for security purposes. To enable, set
\fBfile_recv\fP to \fBTrue\fP in the master configuration file, and restart the
master.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.push /etc/fstab
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.push_dir(path, glob=None)
Push a directory from the minion up to the master, the files will be saved
to the salt master in the master\(aqs minion files cachedir (defaults to
\fB/var/cache/salt/master/minions/minion\-id/files\fP). It also has a glob
for matching specific files using globbing.
.sp
New in version 2014.7.0.
.sp
Since this feature allows a minion to push files up to the master server it
is disabled by default for security purposes. To enable, set \fBfile_recv\fP
to \fBTrue\fP in the master configuration file, and restart the master.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.push /usr/lib/mysql
salt \(aq*\(aq cp.push_dir /etc/modprobe.d/ glob=\(aq*.conf\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cp.recv(files, dest)
Used with salt\-cp, pass the files dict, and the destination.
.sp
This function receives small fast copy files from the master via salt\-cp.
It does not work via the CLI.
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.list_tab root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.ls(user)
Return the contents of the specified user\(aqs crontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.list_tab root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.raw_cron(user)
Return the contents of the user\(aqs crontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.raw_cron root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.rm(user, cmd, minute=None, hour=None, daymonth=None, month=None, dayweek=None, identifier=None)
Remove a cron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.rm_job root /usr/local/weekly
salt \(aq*\(aq cron.rm_job root /usr/bin/foo dayweek=1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.rm_env(user, name)
Remove cron environment variable for a specified user.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.rm_env root MAILTO
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.rm_job(user, cmd, minute=None, hour=None, daymonth=None, month=None, dayweek=None, identifier=None)
Remove a cron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.rm_job root /usr/local/weekly
salt \(aq*\(aq cron.rm_job root /usr/bin/foo dayweek=1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.set_env(user, name, value=None)
Set up an environment variable in the crontab.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.set_env root MAILTO user@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.set_job(user, minute, hour, daymonth, month, dayweek, cmd, comment=None, identifier=None)
Sets a cron job up for a specified user.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.set_job root \(aq*\(aq \(aq*\(aq \(aq*\(aq \(aq*\(aq 1 /usr/local/weekly
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.set_special root @hourly \(aqecho foobar\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.write_cron_file(user, path)
Writes the contents of a file to a user\(aqs crontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.write_cron_file root /tmp/new_cron
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cron.write_cron_file_verbose(user, path)
Writes the contents of a file to a user\(aqs crontab and return error message on error
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cron.write_cron_file_verbose root /tmp/new_cron
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.daemontools
.sp
daemontools service module. This module will create daemontools type
service watcher.
.sp
This module is compatible with the \fBservice\fP states,
so it can be used to maintain services using the \fBprovider\fP argument:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myservice:
service.running:
\- provider: daemontools
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.available foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.full_restart(name)
Calls daemontools.restart() function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.full_restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.get_all()
Return a list of all available services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.missing(name)
The inverse of daemontools.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.missing foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.reload_(name)
Wrapper for term()
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.restart(name)
Restart service via daemontools. This will stop/start service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.start(name)
Starts service via daemontools
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.status(name, sig=None)
Return the status for a service via daemontools, return pid if running
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.stop(name)
Stops service via daemontools
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.daemontools.term(name)
Send a TERM to service via daemontools
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq daemontools.term <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.darwin_sysctl
.sp
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
.B salt.modules.darwin_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.INDENT 7.0
.TP
.B name
The name of the sysctl value to edit.
.TP
.B value
The sysctl value to apply.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.darwin_sysctl.get(name)
Return a single sysctl parameter for this minion
.INDENT 7.0
.TP
.B name
The name of the sysctl value to display.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.get hw.physmem
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.darwin_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq, apply_change=False)
Assign and persist a simple sysctl parameter for this minion
.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.
.TP
.B apply_change
Default is False; Default behavior only creates or edits
the sysctl.conf file. If apply is set to True, the changes are
applied to the system.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50
salt \(aq*\(aq sysctl.persist coretemp_load NO config=/etc/sysctl.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.darwin_sysctl.show(config_file=False)
Return a list of sysctl parameters for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.data
.sp
Manage a local persistent data structure that can hold any arbitrary data
specific to the minion
.INDENT 0.0
.TP
.B salt.modules.data.cas(key, value, old_value)
Check and set a value in the minion datastore
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq data.cas <key> <value> <old_value>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.data.clear()
Clear out all of the data in the minion datastore, this function is
destructive!
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq data.clear
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.data.dump(new_data)
Replace the entire datastore with a passed data structure
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq data.dump \(aq{\(aqeggs\(aq: \(aqspam\(aq}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.data.getval(key)
Get a value from the minion datastore
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq data.getval <key>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.data.getvals(*keys)
Get values from the minion datastore
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq data.getvals <key> [<key> ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.data.load()
Return all of the data in the minion datastore
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq data.load
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.data.update(key, value)
Update a key with a value in the minion datastore
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq data.update <key> <value>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.ddns
.sp
Support for RFC 2136 dynamic DNS updates.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
dnspython Python module
.UNINDENT
.TP
.B configuration
If you want to use TSIG authentication for the server, there
are a couple of optional configuration parameters made available to
support this (the keyname is only needed if the keyring contains more
than one key):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
keyring: keyring file (default=None)
keyname: key name in file (default=None)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The keyring file needs to be in json format and the key name needs to end
with an extra period in the file, similar to this:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{"keyname.": "keycontent"}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ddns.add_host(zone, name, ttl, ip, nameserver=\(aq127.0.0.1\(aq, replace=True, **kwargs)
Add, replace, or update the A and PTR (reverse) records for a host.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 ddns.add_host example.com host1 60 10.1.1.1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ddns.delete(zone, name, rdtype=None, data=None, nameserver=\(aq127.0.0.1\(aq, **kwargs)
Delete a DNS record.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 ddns.delete example.com host1 A
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ddns.delete_host(zone, name, nameserver=\(aq127.0.0.1\(aq, **kwargs)
Delete the forward and reverse records for a host.
.sp
Returns true if any records are deleted.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 ddns.delete_host example.com host1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ddns.update(zone, name, ttl, rdtype, data, nameserver=\(aq127.0.0.1\(aq, replace=False, **kwargs)
Add, replace, or update a DNS record.
nameserver must be an IP address and the minion running this module
must have update privileges on that server.
If replace is true, first deletes all records for this name and type.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 ddns.update example.com host1 60 A 10.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.deb_apache
.sp
Support for Apache
.sp
Please note: The functions in here are Debian\-specific. Placing them in this
separate file will allow them to load only on Debian\-based systems, while still
loading under the \fBapache\fP namespace.
.INDENT 0.0
.TP
.B salt.modules.deb_apache.a2dismod(mod)
Runs a2dismod for the given mod.
.sp
This will only be functional on Debian\-based operating systems (Ubuntu,
Mint, etc).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.a2dismod vhost_alias
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.deb_apache.a2dissite(site)
Runs a2dissite for the given site.
.sp
This will only be functional on Debian\-based operating systems (Ubuntu,
Mint, etc).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.a2dissite example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.deb_apache.a2enmod(mod)
Runs a2enmod for the given mod.
.sp
This will only be functional on Debian\-based operating systems (Ubuntu,
Mint, etc).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.a2enmod vhost_alias
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.deb_apache.a2ensite(site)
Runs a2ensite for the given site.
.sp
This will only be functional on Debian\-based operating systems (Ubuntu,
Mint, etc).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.a2ensite example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.deb_apache.check_mod_enabled(mod)
Checks to see if the specific mod symlink is in /etc/apache2/mods\-enabled.
.sp
This will only be functional on Debian\-based operating systems (Ubuntu,
Mint, etc).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.check_mod_enabled status.conf
salt \(aq*\(aq apache.check_mod_enabled status.load
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.deb_apache.check_site_enabled(site)
Checks to see if the specific Site symlink is in /etc/apache2/sites\-enabled.
.sp
This will only be functional on Debian\-based operating systems (Ubuntu,
Mint, etc).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq apache.check_site_enabled example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.debconfmod
.sp
Support for Debconf
.INDENT 0.0
.TP
.B salt.modules.debconfmod.get_selections(fetchempty=True)
Answers to debconf questions for all packages in the following format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqpackage\(aq: [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...]}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq debconf.get_selections
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debconfmod.set_(package, question, type, value, *extra)
Set answers to debconf questions for a package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq debconf.set <package> <question> <type> <value> [<value> ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debconfmod.set_file(path, saltenv=\(aqbase\(aq, **kwargs)
Set answers to debconf questions from a file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq debconf.set_file salt://pathto/pkg.selections
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debconfmod.show(name)
Answers to debconf questions for a package in the following format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If debconf doesn\(aqt know about a package, we return None.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq debconf.show <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.debian_ip
.sp
The networking module for Debian based distros
.sp
References:
.INDENT 0.0
.IP \(bu 2
\fI\%http://www.debian.org/doc/manuals/debian\-reference/ch05.en.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.apply_network_settings(**settings)
Apply global network configuration.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.apply_network_settings
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.build_bond(iface, **settings)
Create a bond script in /etc/modprobe.d with the passed settings
and load the bonding kernel module.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_bond bond0 mode=balance\-alb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.build_interface(iface, iface_type, enabled, **settings)
Build an interface script for a network interface.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_interface eth0 eth <settings>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.build_network_settings(**settings)
Build the global network script.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_network_settings <settings>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.build_routes(iface, **settings)
Add route scripts for a network interface using up commands.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_routes eth0 <settings>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.down(iface, iface_type)
Shutdown a network interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.down eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.get_bond(iface)
Return the content of a bond script
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_bond bond0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.get_interface(iface)
Return the contents of an interface script
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_interface eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.get_network_settings()
Return the contents of the global network script.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_network_settings
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.get_routes(iface)
Return the routes for the interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_interface eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_ip.up(iface, iface_type)
Start up a network interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.up eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.debian_service
.sp
Service support for Debian systems (uses update\-rc.d and /sbin/service)
.INDENT 0.0
.TP
.B salt.modules.debian_service.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.disable(name, **kwargs)
Disable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.disabled(name)
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.enable(name, **kwargs)
Enable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.enabled(name)
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.force_reload(name)
Force\-reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.force_reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.get_all()
Return all available boot services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.get_disabled()
Return a set of services that are installed but disabled
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.get_enabled()
Return a list of service that are enabled on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.reload_(name)
Reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.status(name, sig=None)
Return the status for a service, pass a signature to use to find
the service via ps
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.debian_service.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.defaults
.INDENT 0.0
.TP
.B salt.modules.defaults.get(key, default=\(aq\(aq)
defaults.get is used much like pillar.get except that it will read
a default value for a pillar from defaults.json or defaults.yaml
files that are stored in the root of a salt formula.
.sp
When called from the CLI it works exactly like pillar.get.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq defaults.get core:users:root
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When called from an SLS file, it works by first reading a defaults.json
and second a defaults.yaml file. If the key exists in these files and
does not exist in a pillar named after the formula, the value from the
defaults file is used.
.sp
Example core/defaults.json file for the \(aqcore\(aq formula:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{
"users": {
"root": 0
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this, from a state file you can use salt[\(aqdefaults.get\(aq](\(aqusers:root\(aq)
to read the \(aq0\(aq value from defaults.json if a core:users:root pillar
key is not defined.
.UNINDENT
.SS salt.modules.dig
.sp
Compendium of generic DNS utilities
.INDENT 0.0
.TP
.B salt.modules.dig.A(host, nameserver=None)
Return the A record for \fBhost\fP\&.
.sp
Always returns a list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.A www.google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dig.AAAA(host, nameserver=None)
Return the AAAA record for \fBhost\fP\&.
.sp
Always returns a list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.AAAA www.google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dig.MX(domain, resolve=False, nameserver=None)
Return a list of lists for the MX of \fBdomain\fP\&.
.sp
If the \fBresolve\fP argument is True, resolve IPs for the servers.
.sp
It\(aqs limited to one IP, because although in practice it\(aqs very rarely a
round robin, it is an acceptable configuration and pulling just one IP lets
the data be similar to the non\-resolved version. If you think an MX has
multiple IPs, don\(aqt use the resolver here, resolve them in a separate step.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.MX google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dig.NS(domain, resolve=True, nameserver=None)
Return a list of IPs of the nameservers for \fBdomain\fP
.sp
If \fBresolve\fP is False, don\(aqt resolve names.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.NS google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dig.SPF(domain, record=\(aqSPF\(aq, nameserver=None)
Return the allowed IPv4 ranges in the SPF record for \fBdomain\fP\&.
.sp
If record is \fBSPF\fP and the SPF record is empty, the TXT record will be
searched automatically. If you know the domain uses TXT and not SPF,
specifying that will save a lookup.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.SPF google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dig.TXT(host, nameserver=None)
Return the TXT record for \fBhost\fP\&.
.sp
Always returns a list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.TXT google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dig.check_ip(addr)
Check if address is a valid IP. returns True if valid, otherwise False.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.check_ip 127.0.0.1
salt ns1 dig.check_ip 1111:2222:3333:4444:5555:6666:7777:8888
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.disk
.sp
Module for gathering disk information
.INDENT 0.0
.TP
.B salt.modules.disk.blkid(device=None)
Return block device attributes: UUID, LABEL, etc. This function only works
on systems where blkid is available.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq disk.blkid
salt \(aq*\(aq disk.blkid /dev/sda
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.disk.inodeusage(args=None)
Return inode usage information for volumes mounted on this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq disk.inodeusage
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.disk.percent(args=None)
Return partition information for volumes mounted on this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq disk.percent /var
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.disk.usage(args=None)
Return usage information for volumes mounted on this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq disk.usage
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.djangomod
.sp
Manage Django sites
.INDENT 0.0
.TP
.B salt.modules.djangomod.collectstatic(settings_module, bin_env=None, no_post_process=False, ignore=None, dry_run=False, clear=False, link=False, no_default_ignore=False, pythonpath=None, env=None)
Collect static files from each of your applications into a single location
that can easily be served in production.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq django.collectstatic <settings_module>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.djangomod.command(settings_module, command, bin_env=None, pythonpath=None, env=None, *args, **kwargs)
Run arbitrary django management command
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq django.command <settings_module> <command>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.djangomod.createsuperuser(settings_module, username, email, bin_env=None, database=None, pythonpath=None, env=None)
Create a super user for the database.
This function defaults to use the \fB\-\-noinput\fP flag which prevents the
creation of a password for the superuser.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq django.createsuperuser <settings_module> user user@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.djangomod.loaddata(settings_module, fixtures, bin_env=None, database=None, pythonpath=None, env=None)
Load fixture data
.INDENT 7.0
.TP
.B Fixtures:
comma separated list of fixtures to load
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq django.loaddata <settings_module> <comma delimited list of fixtures>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.djangomod.syncdb(settings_module, bin_env=None, migrate=False, database=None, pythonpath=None, env=None, noinput=True)
Run syncdb
.sp
Execute the Django\-Admin syncdb command, if South is available on the
minion the \fBmigrate\fP option can be passed as \fBTrue\fP calling the
migrations to run after the syncdb completes
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq django.syncdb <settings_module>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.dnsmasq
.sp
Module for managing dnsmasq
.INDENT 0.0
.TP
.B salt.modules.dnsmasq.fullversion()
Shows installed version of dnsmasq and compile options.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq dnsmasq.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsmasq.get_config(config_file=\(aq/etc/dnsmasq.conf\(aq)
Dumps all options from the config file.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq dnsmasq.get_config
salt \(aq*\(aq dnsmasq.get_config file=/etc/dnsmasq.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsmasq.set_config(config_file=\(aq/etc/dnsmasq.conf\(aq, follow=True, **kwargs)
Sets a value or a set of values in the specified file. By default, if
conf\-dir is configured in this file, salt will attempt to set the option
in any file inside the conf\-dir where it has already been enabled. If it
does not find it inside any files, it will append it to the main config
file. Setting follow to False will turn off this behavior.
.sp
If a config option currently appears multiple times (such as dhcp\-host,
which is specified at least once per host), the new option will be added
to the end of the main config file (and not to any includes). If you need
an option added to a specific include file, specify it as the config_file.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq dnsmasq.set_config domain=mydomain.com
salt \(aq*\(aq dnsmasq.set_config follow=False domain=mydomain.com
salt \(aq*\(aq dnsmasq.set_config file=/etc/dnsmasq.conf domain=mydomain.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsmasq.version()
Shows installed version of dnsmasq.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq dnsmasq.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.dnsutil
.sp
Compendium of generic DNS utilities
.INDENT 0.0
.TP
.B salt.modules.dnsutil.A(host, nameserver=None)
Return the A record for \(aqhost\(aq.
.sp
Always returns a list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.A www.google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.MX(domain, resolve=False, nameserver=None)
Return a list of lists for the MX of \fBdomain\fP\&.
.sp
If the \(aqresolve\(aq argument is True, resolve IPs for the servers.
.sp
It\(aqs limited to one IP, because although in practice it\(aqs very rarely a
round robin, it is an acceptable configuration and pulling just one IP lets
the data be similar to the non\-resolved version. If you think an MX has
multiple IPs, don\(aqt use the resolver here, resolve them in a separate step.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.MX google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.NS(domain, resolve=True, nameserver=None)
Return a list of IPs of the nameservers for \fBdomain\fP
.sp
If \(aqresolve\(aq is False, don\(aqt resolve names.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.NS google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.SPF(domain, record=\(aqSPF\(aq, nameserver=None)
Return the allowed IPv4 ranges in the SPF record for \fBdomain\fP\&.
.sp
If record is \fBSPF\fP and the SPF record is empty, the TXT record will be
searched automatically. If you know the domain uses TXT and not SPF,
specifying that will save a lookup.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.SPF google.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.check_ip(ip_addr)
Check that string ip_addr is a valid IP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dig.check_ip 127.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.hosts_append(hostsfile=\(aq/etc/hosts\(aq, ip_addr=None, entries=None)
Append a single line to the /etc/hosts file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq dnsutil.hosts_append /etc/hosts 127.0.0.1 ad1.yuk.co,ad2.yuk.co
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.hosts_remove(hostsfile=\(aq/etc/hosts\(aq, entries=None)
Remove a host from the /etc/hosts file. If doing so will leave a line
containing only an IP address, then the line will be deleted. This function
will leave comments and blank lines intact.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq dnsutil.hosts_remove /etc/hosts ad1.yuk.co
salt \(aq*\(aq dnsutil.hosts_remove /etc/hosts ad2.yuk.co,ad1.yuk.co
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.parse_hosts(hostsfile=\(aq/etc/hosts\(aq, hosts=None)
Parse /etc/hosts file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq dnsutil.parse_hosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dnsutil.parse_zone(zonefile=None, zone=None)
Parses a zone file. Can be passed raw zone data on the API level.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt ns1 dnsutil.parse_zone /var/lib/named/example.com.zone
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.dockerio
.SS Management of Dockers
.sp
New in version 2014.1.0.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The DockerIO integration is still in beta; the API is subject to change
.UNINDENT
.UNINDENT
.SS General Notes
.sp
As we use states, we don\(aqt want to be continuously popping dockers, so we
will map each container id (or image) with a grain whenever it is relevant.
.sp
As a corollary, we will resolve a container id either directly by the id
or try to find a container id matching something stocked in grain.
.SS Installation Prerequisites
.INDENT 0.0
.IP \(bu 2
You will need the \fBdocker\-py\fP python package in your python installation
path that is running salt. Its version should support \fI\%Docker Remote API
v1.12\fP\&.
.sp
Currently, \fBdocker\-py 0.5.0\fP is known to support \fI\%Docker Remote API v1.12\fP
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
pip install docker\-py==0.5.0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Prerequisite Pillar Configuration for Authentication
.INDENT 0.0
.IP \(bu 2
To push or pull you will need to be authenticated as the \fBdocker\-py\fP bindings
require it
.IP \(bu 2
For this to happen, you will need to configure a mapping in the pillar
representing your per URL authentication bits:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
docker\-registries:
registry_url:
email: foo@foo.com
password: s3cr3t
username: foo
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
You need at least an entry to the default docker index:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
docker\-registries:
https://index.docker.io/v1/:
email: foo@foo.com
password: s3cr3t
username: foo
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
You can define multiple registry blocks for them to be aggregated. The only thing to keep
in mind is that their ID must finish with \fB\-docker\-registries\fP:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
ac\-docker\-registries:
https://index.bar.io/v1/:
email: foo@foo.com
password: s3cr3t
username: foo
ab\-docker\-registries:
https://index.foo.io/v1/:
email: foo@foo.com
password: s3cr3t
username: foo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This could be also written as:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
docker\-registries:
https://index.bar.io/v1/:
email: foo@foo.com
password: s3cr3t
username: foo
https://index.foo.io/v1/:
email: foo@foo.com
password: s3cr3t
username: foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Methods
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B Registry Dialog
.INDENT 7.0
.IP \(bu 2
\fI\%login\fP
.IP \(bu 2
\fI\%push\fP
.IP \(bu 2
\fI\%pull\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B Docker Management
.INDENT 7.0
.IP \(bu 2
\fI\%version\fP
.IP \(bu 2
\fI\%info\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B Image Management
.INDENT 7.0
.IP \(bu 2
\fI\%search\fP
.IP \(bu 2
\fI\%inspect_image\fP
.IP \(bu 2
\fI\%get_images\fP
.IP \(bu 2
\fI\%remove_image\fP
.IP \(bu 2
\fI\%import_image\fP
.IP \(bu 2
\fI\%build\fP
.IP \(bu 2
\fI\%tag\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B Container Management
.INDENT 7.0
.IP \(bu 2
\fI\%start\fP
.IP \(bu 2
\fI\%stop\fP
.IP \(bu 2
\fI\%restart\fP
.IP \(bu 2
\fI\%kill\fP
.IP \(bu 2
\fI\%wait\fP
.IP \(bu 2
\fI\%get_containers\fP
.IP \(bu 2
\fI\%inspect_container\fP
.IP \(bu 2
\fI\%remove_container\fP
.IP \(bu 2
\fI\%is_running\fP
.IP \(bu 2
\fI\%top\fP
.IP \(bu 2
\fI\%port\fP
.IP \(bu 2
\fI\%logs\fP
.IP \(bu 2
\fI\%diff\fP
.IP \(bu 2
\fI\%commit\fP
.IP \(bu 2
\fI\%create_container\fP
.IP \(bu 2
\fI\%export\fP
.IP \(bu 2
\fI\%get_container_root\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Runtime Execution within a specific, already existing/running container
.sp
Idea is to use \fI\%lxc\-attach\fP to execute
inside the container context.
We do not want to use \fBdocker run\fP but want to execute something inside a
running container.
.sp
These are the available methods:
.INDENT 0.0
.IP \(bu 2
\fI\%retcode\fP
.IP \(bu 2
\fI\%run\fP
.IP \(bu 2
\fI\%run_all\fP
.IP \(bu 2
\fI\%run_stderr\fP
.IP \(bu 2
\fI\%run_stdout\fP
.IP \(bu 2
\fI\%script\fP
.IP \(bu 2
\fI\%script_retcode\fP
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.build(path=None, tag=None, quiet=False, fileobj=None, nocache=False, rm=True, timeout=None)
Build a docker image from a dockerfile or an URL
.INDENT 7.0
.TP
.B path
url/branch/docker_dir or path on the filesystem to the dockerfile
.TP
.B tag
tag of the image
.TP
.B quiet
quiet mode, Default is \fBFalse\fP
.TP
.B nocache
do not use docker image cache, Default is \fBFalse\fP
.TP
.B rm
remove intermediate commits, Default is \fBTrue\fP
.TP
.B timeout
timeout value before aborting (in seconds)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.build vieux/apache
salt \(aq*\(aq docker.build github.com/creack/docker\-firefox
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.commit(container, repository=None, tag=None, message=None, author=None, conf=None)
Commit a container (promotes it to an image)
.INDENT 7.0
.TP
.B container
container id
.TP
.B repository
repository/image to commit to
.TP
.B tag
tag of the image (Optional)
.TP
.B message
commit message (Optional)
.TP
.B author
author name (Optional)
.TP
.B conf
conf (Optional)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.commit <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.create_container(image, command=None, hostname=None, user=None, detach=True, stdin_open=False, tty=False, mem_limit=0, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, name=None)
Create a new container
.INDENT 7.0
.TP
.B image
image to create the container from
.TP
.B command
command to execute while starting
.TP
.B hostname
hostname of the container
.TP
.B user
user to run docker as
.TP
.B detach
daemon mode, Default is \fBTrue\fP
.TP
.B environment
environment variable mapping \fB({\(aqfoo\(aq:\(aqBAR\(aq})\fP
.TP
.B ports
port redirections \fB({\(aq222\(aq: {}})\fP
.TP
.B volumes
list of volume mappings:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
([\(aq/mountpoint/in/container:/guest/foo\(aq, \(aq/same/path/mounted/point\(aq])
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B tty
attach ttys, Default is \fBFalse\fP
.TP
.B stdin_open
let stdin open, Default is \fBFalse\fP
.TP
.B name
name given to container
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.create_container o/ubuntu volumes="[\(aq/s\(aq,\(aq/m:/f\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.diff(container)
Get container diffs
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.diff <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.exists(container)
Check if a given container exists
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
Returns \fBTrue\fP if container exists otherwise returns \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.exists <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.export(container, path)
Export a container to a file
.INDENT 7.0
.TP
.B container
container id
.TP
.B path
path to which file is to be exported
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.export <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.get_container_root(container)
Get the container rootfs path
.INDENT 7.0
.TP
.B container
container id or grain
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.get_container_root <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.get_containers(all=True, trunc=False, since=None, before=None, limit=\-1, host=False, inspect=False)
Get a list of mappings representing all containers
.INDENT 7.0
.TP
.B all
return all containers, Default is \fBTrue\fP
.TP
.B trunc
set it to True to have the short ID, Default is \fBFalse\fP
.TP
.B host
include the Docker host\(aqs ipv4 and ipv6 address in return, Default is \fBFalse\fP
.TP
.B inspect
Get more granular information about each container by running a docker inspect
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.get_containers
salt \(aq*\(aq docker.get_containers host=True
salt \(aq*\(aq docker.get_containers host=True inspect=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.get_images(name=None, quiet=False, all=True)
List docker images
.INDENT 7.0
.TP
.B name
repository name
.TP
.B quiet
only show image id, Default is \fBFalse\fP
.TP
.B all
show all images, Default is \fBTrue\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.get_images <name> [quiet=True|False] [all=True|False]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.import_image(src, repo, tag=None)
Import content from a local tarball or a URL to a docker image
.INDENT 7.0
.TP
.B src
content to import (URL or absolute path to a tarball)
.TP
.B repo
repository to import to
.TP
.B tag
set tag of the image (Optional)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.import_image <src> <repo> [tag]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.info()
Get the version information about docker. This is similar to \fBdocker info\fP command
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.inspect_container(container)
Get container information. This is similar to \fBdocker inspect\fP command but only for containers
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.inspect_container <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.inspect_image(image)
Inspect the status of an image and return relative data. This is similar to
\fBdocker inspect\fP command but only for images
.INDENT 7.0
.TP
.B image
name of the image
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.inspect_image <image>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.is_running(container)
Check if the specified container is running
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
Returns \fBTrue\fP if container is running otherwise returns \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.is_running <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.kill(container)
Kill a running container
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.kill <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.login(url=None, username=None, password=None, email=None)
Wrapper to the \fBdocker.py\fP login method (does not do much yet)
.INDENT 7.0
.TP
.B url
registry url to authenticate to
.TP
.B username
username to authenticate
.TP
.B password
password to authenticate
.TP
.B email
email to authenticate
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.login <url> <username> <password> <email>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.logs(container)
Return logs for a specified container
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.logs <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.port(container, private_port)
Private port mapping allocation information. This method is broken on docker\-py
side. Just use the result of inspect to mangle port
allocation
.INDENT 7.0
.TP
.B container
container id
.TP
.B private_port
private port on the container to query for
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.port <container id> <private port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.pull(repo, tag=None)
Pulls an image from any registry. See documentation at top of this page to
configure authenticated access
.INDENT 7.0
.TP
.B repo
name of repository
.TP
.B tag
specific tag to pull (Optional)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.pull <repository> [tag]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.push(repo, tag=None, quiet=False)
Pushes an image to any registry. See documentation at top of this page to
configure authenticated access
.INDENT 7.0
.TP
.B repo
name of repository
.TP
.B tag
specific tag to push (Optional)
.TP
.B quiet
set as \fBTrue\fP to quiet output, Default is \fBFalse\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.push <repository> [tag] [quiet=True|False]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.remove_container(container, force=False, v=False)
Remove a container from a docker installation
.INDENT 7.0
.TP
.B container
container id
.TP
.B force
remove a running container, Default is \fBFalse\fP
.TP
.B v
verbose mode, Default is \fBFalse\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.remove_container <container id> [force=True|False] [v=True|False]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.remove_image(image)
Remove an image from a system.
.INDENT 7.0
.TP
.B image
name of image
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.remove_image <image>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.restart(container, timeout=10)
Restart a running container
.INDENT 7.0
.TP
.B container
container id
.TP
.B timeout
timeout for container to exit gracefully before killing it, Default is \fB10\fP seconds
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.restart <container id> [timeout=20]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.retcode(container, cmd)
Wrapper for \fBcmdmod.retcode\fP inside a container context
.INDENT 7.0
.TP
.B container
container id (or grain)
.TP
.B cmd
command to execute
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The return is a bit different as we use the docker struct.
Output of the command is in \(aqout\(aq and result is \fBFalse\fP if
command failed to execute.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Be advised that this function allows for raw shell access to the named
container! If allowing users to execute this directly it may allow more
rights than intended!
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.retcode <container id> \(aqls \-l /etc\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.run(container, cmd)
Wrapper for \fBcmdmod.run\fP inside a container context
.INDENT 7.0
.TP
.B container
container id (or grain)
.TP
.B cmd
command to execute
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The return is a bit different as we use the docker struct.
Output of the command is in \(aqout\(aq and result is always \fBTrue\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Be advised that this function allows for raw shell access to the named
container! If allowing users to execute this directly it may allow more
rights than intended!
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.run <container id> \(aqls \-l /etc\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.run_all(container, cmd)
Wrapper for \fBcmdmod.run_all\fP inside a container context
.INDENT 7.0
.TP
.B container
container id (or grain)
.TP
.B cmd
command to execute
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The return is a bit different as we use the docker struct.
Output of the command is in \(aqout\(aq and result is \fBFalse\fP if
command failed to execute.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Be advised that this function allows for raw shell access to the named
container! If allowing users to execute this directly it may allow more
rights than intended!
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.run_all <container id> \(aqls \-l /etc\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.run_stderr(container, cmd)
Wrapper for \fBcmdmod.run_stderr\fP inside a container context
.INDENT 7.0
.TP
.B container
container id (or grain)
.TP
.B cmd
command to execute
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The return is a bit different as we use the docker struct.
Output of the command is in \(aqout\(aq and result is always \fBTrue\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Be advised that this function allows for raw shell access to the named
container! If allowing users to execute this directly it may allow more
rights than intended!
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.run_stderr <container id> \(aqls \-l /etc\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.run_stdout(container, cmd)
Wrapper for \fBcmdmod.run_stdout\fP inside a container context
.INDENT 7.0
.TP
.B container
container id (or grain)
.TP
.B cmd
command to execute
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The return is a bit different as we use the docker struct.
Output of the command is in \(aqout\(aq and result is always \fBTrue\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Be advised that this function allows for raw shell access to the named
container! If allowing users to execute this directly it may allow more
rights than intended!
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.run_stdout <container id> \(aqls \-l /etc\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.script(container, source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv=\(aqbase\(aq)
Wrapper for \fBcmdmod.script\fP inside a container context
.INDENT 7.0
.TP
.B container
container id (or grain)
.TP
.B additional parameters
See \fBcmd.script\fP
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Be advised that this function allows for raw shell access to the named
container! If allowing users to execute this directly it may allow more
rights than intended!
.UNINDENT
.UNINDENT
.sp
Download a script from a remote location and execute the script in the container.
The script can be located on the salt master file server or on an HTTP/FTP server.
.sp
The script will be executed directly, so it can be written in any available programming
language.
.sp
The script can also be formatted as a template, the default is jinja. Arguments for the
script can be specified as well.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.script <container id> salt://docker_script.py
salt \(aq*\(aq docker.script <container id> salt://scripts/runme.sh \(aqarg1 arg2 "arg 3"\(aq
salt \(aq*\(aq docker.script <container id> salt://scripts/windows_task.ps1 args=\(aq \-Input c:\etmp\einfile.txt\(aq shell=\(aqpowershell\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A string of standard input can be specified for the command to be run using the stdin
parameter. This can be useful in cases where sensitive information must be read from
standard input:
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.script <container id> salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.script_retcode(container, source, cwd=None, stdin=None, runas=None, shell=\(aq/bin/bash\(aq, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv=\(aqbase\(aq)
Wrapper for \fBcmdmod.script_retcode\fP inside a container context
.INDENT 7.0
.TP
.B container
container id (or grain)
.TP
.B additional parameters
See \fBcmd.script_retcode\fP
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Be advised that this function allows for raw shell access to the named
container! If allowing users to execute this directly it may allow more
rights than intended!
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.script_retcode <container id> salt://docker_script.py
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.search(term)
Search for an image on the registry
.INDENT 7.0
.TP
.B term
search keyword
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.search <term>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.start(container, binds=None, port_bindings=None, lxc_conf=None, publish_all_ports=None, links=None, privileged=False, dns=None, volumes_from=None, network_mode=None, restart_policy=None, cap_add=None, cap_drop=None)
Start the specified container
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.start <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.stop(container, timeout=10)
Stop a running container
.INDENT 7.0
.TP
.B container
container id
.TP
.B timeout
timeout for container to exit gracefully before killing it, Default is \fB10\fP seconds
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.stop <container id> [timeout=20]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.tag(image, repository, tag=None, force=False)
Tag an image into a repository
.INDENT 7.0
.TP
.B image
name of image
.TP
.B repository
name of repository
.TP
.B tag
tag to apply (Optional)
.TP
.B force
force apply tag, Default is \fBFalse\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.tag <image> <repository> [tag] [force=True|False]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.top(container)
Run the docker top command on a specific container
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.top <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.version()
Get docker version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dockerio.wait(container)
Wait for a container to exit gracefully
.INDENT 7.0
.TP
.B container
container id
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq docker.wait <container id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.dpkg
.sp
Support for DEB packages
.INDENT 0.0
.TP
.B salt.modules.dpkg.file_dict(*packages)
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of _every_ file on the system\(aqs
package database (not generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.file_list httpd
salt \(aq*\(aq lowpkg.file_list httpd postfix
salt \(aq*\(aq lowpkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dpkg.file_list(*packages)
List the files that belong to a package. Not specifying any packages will
return a list of _every_ file on the system\(aqs package database (not
generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.file_list httpd
salt \(aq*\(aq lowpkg.file_list httpd postfix
salt \(aq*\(aq lowpkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dpkg.list_pkgs(*packages)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
External dependencies:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
Virtual package resolution requires aptitude. Because this function
uses dpkg, virtual packages will be reported as not installed.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.list_pkgs
salt \(aq*\(aq lowpkg.list_pkgs httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.dpkg.unpurge(*packages)
Change package selection for each package specified to \(aqinstall\(aq
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.unpurge curl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.ebuild
.sp
Support for Portage
.INDENT 0.0
.TP
.B optdepends
.INDENT 7.0
.IP \(bu 2
portage Python adapter
.UNINDENT
.UNINDENT
.sp
For now all package names \fIMUST\fP include the package category,
i.e. \fB\(aqvim\(aq\fP will not work, \fB\(aqapp\-editors/vim\(aq\fP will.
.INDENT 0.0
.TP
.B salt.modules.ebuild.check_db(*names, **kwargs)
New in version 0.17.0.
.sp
Returns a dict containing the following information for each specified
package:
.INDENT 7.0
.IP 1. 3
A key \fBfound\fP, which will be a boolean value denoting if a match was
found in the package database.
.IP 2. 3
If \fBfound\fP is \fBFalse\fP, then a second key called \fBsuggestions\fP will
be present, which will contain a list of possible matches. This list
will be empty if the package name was specified in \fBcategory/pkgname\fP
format, since the suggestions are only intended to disambiguate
ambiguous package names (ones submitted without a category).
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check_db <package1> <package2> <package3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.check_extra_requirements(pkgname, pkgver)
Check if the installed package already has the given requirements.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check_extra_requirements \(aqsys\-devel/gcc\(aq \(aq~>4.1.2:4.1::gentoo[nls,fortran]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.depclean(name=None, slot=None, fromrepo=None, pkgs=None)
Portage has a function to remove unused dependencies. If a package
is provided, it will only removed the package if no other package
depends on it.
.INDENT 7.0
.TP
.B name
The name of the package to be cleaned.
.TP
.B slot
Restrict the remove to a specific slot. Ignored if \fBname\fP is None.
.TP
.B fromrepo
Restrict the remove to a specific slot. Ignored if \fBname\fP is None.
.TP
.B pkgs
Clean multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are
ignored if this argument is present. Must be passed as a python list.
.UNINDENT
.sp
Return a list containing the removed packages:
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.depclean <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.ex_mod_init(low)
If the config option \fBebuild.enforce_nice_config\fP is set to True, this
module will enforce a nice tree structure for /etc/portage/package.*
configuration files.
.sp
New in version 0.17.0: Initial automatic enforcement added when pkg is used on a Gentoo system.
.sp
Changed in version 2014.1.0: Configure option added to make this behavior optional, defaulting to
off.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fBebuild.ex_mod_init\fP is called automatically when a state invokes a
pkg state on a Gentoo system.
\fBsalt.states.pkg.mod_init()\fP
.sp
\fBebuild.ex_mod_init\fP uses \fBportage_config.enforce_nice_config\fP to do
the lifting.
\fBsalt.modules.portage_config.enforce_nice_config()\fP
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.ex_mod_init
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.install(name=None, refresh=False, pkgs=None, sources=None, slot=None, fromrepo=None, uses=None, **kwargs)
Install the passed package(s), add refresh=True to sync the portage tree
before package is installed.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Note that this parameter is
ignored if either "pkgs" or "sources" is passed. Additionally, please
note that this option can only be used to emerge a package from the
portage tree. To install a tbz2 package manually, use the "sources"
option described below.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B refresh
Whether or not to sync the portage tree before installing.
.TP
.B version
Install a specific version of the package, e.g. 1.0.9\-r1. Ignored
if "pkgs" or "sources" is passed.
.TP
.B slot
Similar to version, but specifies a valid slot to be installed. It
will install the latest available version in the specified slot.
Ignored if "pkgs" or "sources" or "version" is passed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sys\-devel/gcc slot=\(aq4.4\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B fromrepo
Similar to slot, but specifies the repository from the package will be
installed. It will install the latest available version in the
specified repository.
Ignored if "pkgs" or "sources" or "version" is passed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install salt fromrepo=\(aqgentoo\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B uses
Similar to slot, but specifies a list of use flag.
Ignored if "pkgs" or "sources" or "version" is passed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sys\-devel/gcc uses=\(aq["nptl","\-nossp"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from the portage tree. Must be passed as
a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar","~category/package:slot::repository[use]"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B sources
A list of tbz2 packages to install. Must be passed as a list of dicts,
with the keys being package names, and the values being the source URI
or local path to the package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.tbz2"},{"bar": "salt://bar.tbz2"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.list_upgrades(refresh=True)
List all available package upgrades.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.porttree_matches(name)
Returns a list containing the matches for a given package name from the
portage tree. Note that the specific version of the package will not be
provided for packages that have several versions in the portage tree, but
rather the name of the package (i.e. "dev\-python/paramiko").
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.purge(name=None, slot=None, fromrepo=None, pkgs=None, **kwargs)
Portage does not have a purge, this function calls remove followed
by depclean to emulate a purge process
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.TP
.B slot
Restrict the remove to a specific slot. Ignored if name is None.
.TP
.B fromrepo
Restrict the remove to a specific slot. Ignored if \fBname\fP is None.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
Uninstall multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are
ignored if this argument is present. Must be passed as a python list.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package name> slot=4.4
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.refresh_db()
Updates the portage tree (emerge \-\-sync). Uses eix\-sync if available.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.remove(name=None, slot=None, fromrepo=None, pkgs=None, **kwargs)
Remove packages via emerge \-\-unmerge.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.TP
.B slot
Restrict the remove to a specific slot. Ignored if \fBname\fP is None.
.TP
.B fromrepo
Restrict the remove to a specific slot. Ignored if \fBname\fP is None.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
Uninstall multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are
ignored if this argument is present. Must be passed as a python list.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package name> slot=4.4 fromrepo=gentoo
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.update(pkg, slot=None, fromrepo=None, refresh=False)
Updates the passed package (emerge \-\-update package)
.INDENT 7.0
.TP
.B slot
Restrict the update to a particular slot. It will update to the
latest version within the slot.
.TP
.B fromrepo
Restrict the update to a particular repository. It will update to the
latest version within the repository.
.UNINDENT
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.update <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.upgrade(refresh=True)
Run a full system upgrade (emerge \-\-update world)
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.upgrade_available(name)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.version_clean(version)
Clean the version string removing extra data.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version_clean <version_string>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ebuild.version_cmp(pkg1, pkg2)
Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if
pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem
making the comparison.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.eix
.sp
Support for Eix
.INDENT 0.0
.TP
.B salt.modules.eix.sync()
Sync portage/overlay trees and update the eix database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eix.sync
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.eix.update()
Update the eix database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eix.update
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.environ
.sp
Support for getting and setting the environment variables
of the current salt process.
.INDENT 0.0
.TP
.B salt.modules.environ.get(key, default=\(aq\(aq)
Get a single salt process environment variable.
.INDENT 7.0
.TP
.B key
String used as the key for environment lookup.
.TP
.B default
If the key is not found in the environment, return this value.
Default: \(aq\(aq
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq environ.get foo
salt \(aq*\(aq environ.get baz default=False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.environ.has_value(key, value=None)
Determine whether the key exists in the current salt process
environment dictionary. Optionally compare the current value
of the environment against the supplied value string.
.INDENT 7.0
.TP
.B key
Must be a string. Used as key for environment lookup.
.TP
.B value:
Optional. If key exists in the environment, compare the
current value with this value. Return True if they are equal.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq environ.has_value foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.environ.item(keys, default=\(aq\(aq)
Get one or more salt process environment variables.
Returns a dict.
.INDENT 7.0
.TP
.B keys
Either a string or a list of strings that will be used as the
keys for environment lookup.
.TP
.B default
If the key is not found in the environment, return this value.
Default: \(aq\(aq
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq environ.item foo
salt \(aq*\(aq environ.item \(aq[foo, baz]\(aq default=None
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.environ.items()
Return a dict of the entire environment set for the salt process
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq environ.items
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.environ.setenv(environ, false_unsets=False, clear_all=False, update_minion=False)
Set multiple salt process environment variables from a dict.
Returns a dict.
.INDENT 7.0
.TP
.B environ
Must be a dict. The top\-level keys of the dict are the names
of the environment variables to set. Each key\(aqs value must be
a string or False. Refer to the \(aqfalse_unsets\(aq parameter for
behavior when a value set to False.
.TP
.B false_unsets
If a key\(aqs value is False and false_unsets is True, then the
key will be removed from the salt processes environment dict
entirely. If a key\(aqs value is False and false_unsets is not
True, then the key\(aqs value will be set to an empty string.
Default: False
.TP
.B clear_all
USE WITH CAUTION! This option can unset environment variables
needed for salt to function properly.
If clear_all is True, then any environment variables not
defined in the environ dict will be deleted.
Default: False
.TP
.B update_minion
If True, apply these environ changes to the main salt\-minion
process. If False, the environ changes will only affect the
current salt subprocess.
Default: False
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq environ.setenv \(aq{"foo": "bar", "baz": "quux"}\(aq
salt \(aq*\(aq environ.setenv \(aq{"a": "b", "c": False}\(aq false_unsets=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.environ.setval(key, val, false_unsets=False)
Set a single salt process environment variable. Returns True
on success.
.INDENT 7.0
.TP
.B key
The environment key to set. Must be a string.
.TP
.B val
The value to set. Must be a string or False. Refer to the
\(aqfalse_unsets\(aq parameter for behavior when set to False.
.TP
.B false_unsets
If val is False and false_unsets is True, then the key will be
removed from the salt processes environment dict entirely.
If val is False and false_unsets is not True, then the key\(aqs
value will be set to an empty string.
Default: False.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq environ.setval foo bar
salt \(aq*\(aq environ.setval baz val=False false_unsets=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.eselect
.sp
Support for eselect, Gentoo\(aqs configuration and management tool.
.INDENT 0.0
.TP
.B salt.modules.eselect.exec_action(module, action, module_parameter=None, action_parameter=None, parameter=None, state_only=False)
Execute an arbitrary action on a module.
.INDENT 7.0
.TP
.B module
name of the module to be executed
.TP
.B action
name of the module\(aqs action to be run
.TP
.B module_parameter
additional params passed to the defined module
.TP
.B action_parameter
additional params passed to the defined action
.TP
.B parameter
additional params passed to the defined action
.. deprecated:: Lithium
.TP
.B state_only
don\(aqt return any output but only the success/failure of the operation
.UNINDENT
.sp
CLI Example (updating the \fBphp\fP implementation used for \fBapache2\fP):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eselect.exec_action php update action_parameter=\(aqapache2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.eselect.get_current_target(module, module_parameter=None, action_parameter=None)
Get the currently selected target for the given module.
.INDENT 7.0
.TP
.B module
name of the module to be queried for its current target
.TP
.B module_parameter
additional params passed to the defined module
.TP
.B action_parameter
additional params passed to the \(aqshow\(aq action
.UNINDENT
.sp
CLI Example (current target of system\-wide \fBjava\-vm\fP):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eselect.get_current_target java\-vm action_parameter=\(aqsystem\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example (current target of \fBkernel\fP symlink):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eselect.get_current_target kernel
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.eselect.get_modules()
List available \fBeselect\fP modules.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eselect.get_modules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.eselect.get_target_list(module)
List available targets for the given module.
.INDENT 7.0
.TP
.B module
name of the module to be queried for its targets
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eselect.get_target_list kernel
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.eselect.set_target(module, target, module_parameter=None, action_parameter=None)
Set the target for the given module.
Target can be specified by index or name.
.INDENT 7.0
.TP
.B module
name of the module for which a target should be set
.TP
.B target
name of the target to be set for this module
.TP
.B module_parameter
additional params passed to the defined module
.TP
.B action_parameter
additional params passed to the defined action
.UNINDENT
.sp
CLI Example (setting target of system\-wide \fBjava\-vm\fP):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eselect.set_target java\-vm icedtea\-bin\-7 action_parameter=\(aqsystem\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example (setting target of \fBkernel\fP symlink):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq eselect.set_target kernel linux\-3.17.5\-gentoo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.etcd_mod
.sp
Execution module to work with etcd
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
python\-etcd
.UNINDENT
.UNINDENT
.sp
In order to use an etcd server, a profile should be created in the master
configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_etd_config:
etcd.host: 127.0.0.1
etcd.port: 4001
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is technically possible to configure etcd without using a profile, but this
is not considered to be a best practice, especially when multiple etcd servers
or clusters are available.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
etcd.host: 127.0.0.1
etcd.port: 4001
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.etcd_mod.get_(key, recurse=False, profile=None)
New in version 2014.7.0.
.sp
Get a value from etcd, by direct path
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion etcd.get /path/to/key
salt myminion etcd.get /path/to/key profile=my_etcd_config
salt myminion etcd.get /path/to/key recurse=True profile=my_etcd_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.etcd_mod.ls_(path=\(aq/\(aq, profile=None)
New in version 2014.7.0.
.sp
Return all keys and dirs inside a specific path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion etcd.ls /path/to/dir/
salt myminion etcd.ls /path/to/dir/ profile=my_etcd_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.etcd_mod.rm_(key, recurse=False, profile=None)
New in version 2014.7.0.
.sp
Delete a key from etcd
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion etcd.rm /path/to/key
salt myminion etcd.rm /path/to/key profile=my_etcd_config
salt myminion etcd.rm /path/to/dir recurse=True profile=my_etcd_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.etcd_mod.set_(key, value, profile=None)
New in version 2014.7.0.
.sp
Set a value in etcd, by direct path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion etcd.set /path/to/key value
salt myminion etcd.set /path/to/key value profile=my_etcd_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.etcd_mod.tree(path=\(aq/\(aq, profile=None)
New in version 2014.7.0.
.sp
Recurse through etcd and return all values
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion etcd.tree
salt myminion etcd.tree profile=my_etcd_config
salt myminion etcd.tree /path/to/keys profile=my_etcd_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.event
.sp
Use the \fBSalt Event System\fP to fire events from the
master to the minion and vice\-versa.
.INDENT 0.0
.TP
.B salt.modules.event.fire(data, tag)
Fire an event on the local minion event bus. Data must be formed as a dict.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq event.fire \(aq{"data":"my event data"}\(aq \(aqtag\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.event.fire_master(data, tag, preload=None)
Fire an event off up to the master server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq event.fire_master \(aq{"data":"my event data"}\(aq \(aqtag\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.event.send(tag, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, **kwargs)
Send an event to the Salt Master
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtag\fP \-\- A tag to give the event.
Use slashes to create a namespace for related events. E.g.,
\fBmyco/build/buildserver1/start\fP, \fBmyco/build/buildserver1/success\fP,
\fBmyco/build/buildserver1/failure\fP\&.
.IP \(bu 2
\fBdata\fP \-\- A dictionary of data to send in the event.
This is free\-form. Send any data points that are needed for whoever is
consuming the event. Arguments on the CLI are interpreted as YAML so
complex data structures are possible.
.IP \(bu 2
\fBwith_env\fP (Specify \fBTrue\fP to include all environment variables, or
specify a list of strings of variable names to include.) \-\- Include environment variables from the current shell
environment in the event data as \fBenviron\fP\&.. This is a short\-hand for
working with systems that seed the environment with relevant data such
as Jenkins.
.IP \(bu 2
\fBwith_grains\fP (Specify \fBTrue\fP to include all grains, or specify a
list of strings of grain names to include.) \-\- Include grains from the current minion in the event
data as \fBgrains\fP\&.
.IP \(bu 2
\fBwith_pillar\fP (Specify \fBTrue\fP to include all Pillar values, or
specify a list of strings of Pillar keys to include. It is a
best\-practice to only specify a relevant subset of Pillar data.) \-\- Include Pillar values from the current minion in the
event data as \fBpillar\fP\&. Remember Pillar data is often sensitive data
so be careful. This is useful for passing ephemeral Pillar values
through an event. Such as passing the \fBpillar={}\fP kwarg in
\fBstate.sls\fP from the Master, through
an event on the Minion, then back to the Master.
.IP \(bu 2
\fBkwargs\fP \-\- Any additional keyword arguments passed to this function
will be interpreted as key\-value pairs and included in the event data.
This provides a convenient alternative to YAML for simple values.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call event.send myco/mytag foo=Foo bar=Bar
salt\-call event.send \(aqmyco/mytag\(aq \(aq{foo: Foo, bar: Bar}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A convenient way to allow Jenkins to execute \fBsalt\-call\fP is via sudo. The
following rule in sudoers will allow the \fBjenkins\fP user to run only the
following command.
.sp
\fB/etc/sudoers\fP (allow preserving the environment):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
jenkins ALL=(ALL) NOPASSWD:SETENV: /usr/bin/salt\-call event.send*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Call Jenkins via sudo (preserve the environment):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sudo \-E salt\-call event.send myco/jenkins/build/success with_env=[BUILD_ID, BUILD_URL, GIT_BRANCH, GIT_COMMIT]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.extfs
.sp
Module for managing ext2/3/4 file systems
.INDENT 0.0
.TP
.B salt.modules.extfs.attributes(device, args=None)
Return attributes from dumpe2fs for a specified device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq extfs.attributes /dev/sda1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.extfs.blocks(device, args=None)
Return block and inode info from dumpe2fs for a specified device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq extfs.blocks /dev/sda1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.extfs.dump(device, args=None)
Return all contents of dumpe2fs for a specified device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq extfs.dump /dev/sda1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.extfs.mkfs(device, fs_type, **kwargs)
Create a file system on the specified device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq extfs.mkfs /dev/sda1 fs_type=ext4 opts=\(aqacl,noexec\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Valid options are:
.INDENT 7.0
.IP \(bu 2
\fBblock_size\fP: 1024, 2048 or 4096
.IP \(bu 2
\fBcheck\fP: check for bad blocks
.IP \(bu 2
\fBdirect\fP: use direct IO
.IP \(bu 2
\fBext_opts\fP: extended file system options (comma\-separated)
.IP \(bu 2
\fBfragment_size\fP: size of fragments
.IP \(bu 2
\fBforce\fP: setting force to True will cause mke2fs to specify the \-F
option twice (it is already set once); this is truly dangerous
.IP \(bu 2
\fBblocks_per_group\fP: number of blocks in a block group
.IP \(bu 2
\fBnumber_of_groups\fP: ext4 option for a virtual block group
.IP \(bu 2
\fBbytes_per_inode\fP: set the bytes/inode ratio
.IP \(bu 2
\fBinode_size\fP: size of the inode
.IP \(bu 2
\fBjournal\fP: set to True to create a journal (default on ext3/4)
.IP \(bu 2
\fBjournal_opts\fP: options for the fs journal (comma separated)
.IP \(bu 2
\fBblocks_file\fP: read bad blocks from file
.IP \(bu 2
\fBlabel\fP: label to apply to the file system
.IP \(bu 2
\fBreserved\fP: percentage of blocks reserved for super\-user
.IP \(bu 2
\fBlast_dir\fP: last mounted directory
.IP \(bu 2
\fBtest\fP: set to True to not actually create the file system (mke2fs \-n)
.IP \(bu 2
\fBnumber_of_inodes\fP: override default number of inodes
.IP \(bu 2
\fBcreator_os\fP: override "creator operating system" field
.IP \(bu 2
\fBopts\fP: mount options (comma separated)
.IP \(bu 2
\fBrevision\fP: set the filesystem revision (default 1)
.IP \(bu 2
\fBsuper\fP: write superblock and group descriptors only
.IP \(bu 2
\fBfs_type\fP: set the filesystem type (REQUIRED)
.IP \(bu 2
\fBusage_type\fP: how the filesystem is going to be used
.IP \(bu 2
\fBuuid\fP: set the UUID for the file system
.UNINDENT
.sp
See the \fBmke2fs(8)\fP manpage for a more complete description of these
options.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.extfs.tune(device, **kwargs)
Set attributes for the specified device (using tune2fs)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq extfs.tune /dev/sda1 force=True label=wildstallyns opts=\(aqacl,noexec\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Valid options are:
.INDENT 7.0
.IP \(bu 2
\fBmax\fP: max mount count
.IP \(bu 2
\fBcount\fP: mount count
.IP \(bu 2
\fBerror\fP: error behavior
.IP \(bu 2
\fBextended_opts\fP: extended options (comma separated)
.IP \(bu 2
\fBforce\fP: force, even if there are errors (set to True)
.IP \(bu 2
\fBgroup\fP: group name or gid that can use the reserved blocks
.IP \(bu 2
\fBinterval\fP: interval between checks
.IP \(bu 2
\fBjournal\fP: set to True to create a journal (default on ext3/4)
.IP \(bu 2
\fBjournal_opts\fP: options for the fs journal (comma separated)
.IP \(bu 2
\fBlabel\fP: label to apply to the file system
.IP \(bu 2
\fBreserved\fP: percentage of blocks reserved for super\-user
.IP \(bu 2
\fBlast_dir\fP: last mounted directory
.IP \(bu 2
\fBopts\fP: mount options (comma separated)
.IP \(bu 2
\fBfeature\fP: set or clear a feature (comma separated)
.IP \(bu 2
\fBmmp_check\fP: mmp check interval
.IP \(bu 2
\fBreserved\fP: reserved blocks count
.IP \(bu 2
\fBquota_opts\fP: quota options (comma separated)
.IP \(bu 2
\fBtime\fP: time last checked
.IP \(bu 2
\fBuser\fP: user or uid who can use the reserved blocks
.IP \(bu 2
\fBuuid\fP: set the UUID for the file system
.UNINDENT
.sp
See the \fBmke2fs(8)\fP manpage for a more complete description of these
options.
.UNINDENT
.SS salt.modules.file
.sp
Manage information about regular files, directories,
and special files on the minion, set/read user,
group, mode, and data
.INDENT 0.0
.TP
.B salt.modules.file.access(path, mode)
New in version 2014.1.0.
.sp
Test whether the Salt process has the specified access to the file. One of
the following modes must be specified:
.INDENT 7.0
.INDENT 3.5
f: Test the existence of the path
r: Test the readability of the path
w: Test the writability of the path
x: Test whether the path can be executed
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.access /path/to/file f
salt \(aq*\(aq file.access /path/to/file x
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.append(path, *args, **kwargs)
New in version 0.9.5.
.sp
Append text to the end of a file
.INDENT 7.0
.TP
.B path
path to file
.TP
.B args
strings to append to file
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
If you need to pass a string to append and that string contains
an equal sign, you \fBmust\fP include the argument name, args.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.append /etc/motd args=\(aqcheese=spam\(aq
salt \(aq*\(aq file.append /etc/motd args="[\(aqcheese=spam\(aq,\(aqspam=cheese\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.blockreplace(path, marker_start=\(aq#\-\- start managed zone \-\-\(aq, marker_end=\(aq#\-\- end managed zone \-\-\(aq, content=\(aq\(aq, append_if_not_found=False, prepend_if_not_found=False, backup=\(aq.bak\(aq, dry_run=False, show_changes=True)
New in version 2014.1.0.
.sp
Replace content of a text block in a file, delimited by line markers
.sp
A block of content delimited by comments can help you manage several lines
entries without worrying about old entries removal.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function will store two copies of the file in\-memory (the original
version and the edited version) in order to detect changes and only
edit the targeted file if necessary.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B path
Filesystem path to the file to be edited
.TP
.B marker_start
The line content identifying a line as the start of the content block.
Note that the whole line containing this marker will be considered, so
whitespace or extra content before or after the marker is included in
final output
.TP
.B marker_end
The line content identifying a line as the end of the content block.
Note that the whole line containing this marker will be considered, so
whitespace or extra content before or after the marker is included in
final output
.TP
.B content
The content to be used between the two lines identified by marker_start
and marker_stop.
.TP
.B append_if_not_found
False
If markers are not found and set to \fBTrue\fP then, the markers and
content will be appended to the file.
.TP
.B prepend_if_not_found
False
If markers are not found and set to \fBTrue\fP then, the markers and
content will be prepended to the file.
.TP
.B backup
The file extension to use for a backup of the file if any edit is made.
Set to \fBFalse\fP to skip making a backup.
.TP
.B dry_run
Don\(aqt make any edits to the file.
.TP
.B show_changes
Output a unified diff of the old file and the new file. If \fBFalse\fP,
return a boolean if any changes were made.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.blockreplace /etc/hosts \(aq#\-\- start managed zone foobar : DO NOT EDIT \-\-\(aq \e
\(aq#\-\- end managed zone foobar \-\-\(aq $\(aq10.0.1.1 foo.foobar\en10.0.1.2 bar.foobar\(aq True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, saltenv, template=None, contents=None)
Check for the changes in the file metadata.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.check_file_meta /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root, root, \(aq755\(aq base
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Supported hash types include sha512, sha384, sha256, sha224, sha1, and
md5.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.check_hash(path, file_hash)
Check if a file matches the given hash string
.sp
Returns true if the hash matched, otherwise false. Raises ValueError if
the hash was not formatted correctly.
.INDENT 7.0
.TP
.B path
A file path
.TP
.B hash
A string in the form <hash_type>:<hash_value>. For example:
\fBmd5:e138491e9d5b97023cea823fe17bac22\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.check_hash /etc/fstab md5:<md5sum>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.check_managed(name, source, source_hash, user, group, mode, template, context, defaults, saltenv, contents=None, **kwargs)
Check to see what changes need to be made for a file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.check_managed /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root, root, \(aq755\(aq jinja True None None base
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.check_managed_changes(name, source, source_hash, user, group, mode, template, context, defaults, saltenv, contents=None, **kwargs)
Return a dictionary of what changes need to be made for a file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.check_managed_changes /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root, root, \(aq755\(aq jinja True None None base
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.check_perms(name, ret, user, group, mode, follow_symlinks=False)
Check the permissions on files and chown if needed
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.check_perms /etc/sudoers \(aq{}\(aq root root 400
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.1.3: \fBfollow_symlinks\fP option added
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.chgrp(path, group)
Change the group of a file
.INDENT 7.0
.TP
.B path
path to the file or directory
.TP
.B group
group owner
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.chgrp /etc/passwd root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.chown(path, user, group)
Chown a file, pass the file the desired user and group
.INDENT 7.0
.TP
.B path
path to the file or directory
.TP
.B user
user owner
.TP
.B group
group owner
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.chown /etc/passwd root root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.comment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq)
Deprecated since version 0.17.0: Use \fI\%replace()\fP instead.
.sp
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
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.comment /etc/modules pcspkr
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.contains(path, text)
Deprecated since version 0.17.0: Use \fI\%search()\fP instead.
.sp
Return \fBTrue\fP if the file at \fBpath\fP contains \fBtext\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.contains_glob(path, glob_expr)
Deprecated since version 0.17.0: Use \fI\%search()\fP instead.
.sp
Return \fBTrue\fP if the given glob matches a string in the named file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.contains_glob /etc/foobar \(aq*cheese*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.contains_regex(path, regex, lchar=\(aq\(aq)
Deprecated since version 0.17.0: Use \fI\%search()\fP instead.
.sp
Return True if the given regular expression matches on any line in the text
of a given file.
.sp
If the lchar argument (leading char) is specified, it
will strip \fIlchar\fP from the left side of each line before trying to match
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.contains_regex /etc/crontab
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.contains_regex_multiline(path, regex)
Deprecated since version 0.17.0: Use \fI\%search()\fP instead.
.sp
Return True if the given regular expression matches anything in the text
of a given file
.sp
Traverses multiple lines at a time, via the salt BufferedReader (reads in
chunks)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.contains_regex_multiline /etc/crontab \(aq^maint\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.copy(src, dst, recurse=False, remove_existing=False)
Copy a file or directory from source to dst
.sp
In order to copy a directory, the recurse flag is required, and
will by default overwrite files in the destination with the same path,
and retain all other existing files. (similar to cp \-r on unix)
.sp
remove_existing will remove all files in the target directory,
and then copy files from the source.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.copy /path/to/src /path/to/dst
salt \(aq*\(aq file.copy /path/to/src_dir /path/to/dst_dir recurse=True
salt \(aq*\(aq file.copy /path/to/src_dir /path/to/dst_dir recurse=True remove_existing=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.delete_backup(path, backup_id)
New in version 0.17.0.
.sp
Delete a previous version of a file that was backed up using Salt\(aqs
\fBfile state backup\fP system.
.INDENT 7.0
.TP
.B path
The path on the minion to check for backups
.TP
.B backup_id
The numeric id for the backup you wish to delete, as found using
\fI\%file.list_backups\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.restore_backup /foo/bar/baz.txt 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.directory_exists(path)
Tests to see if path is a valid directory. Returns True/False.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.directory_exists /etc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.extract_hash(hash_fn, hash_type=\(aqsha256\(aq, file_name=\(aq\(aq)
This routine is called from the \fBfile.managed\fP state to pull a hash from a remote file.
Regular expressions are used line by line on the \fBsource_hash\fP file, to
find a potential candidate of the indicated hash type. This avoids many
problems of arbitrary file lay out rules. It specifically permits pulling
hash codes from debian \fB*.dsc\fP files.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
openerp_7.0\-latest\-1.tar.gz:
file.managed:
\- name: /tmp/openerp_7.0\-20121227\-075624\-1_all.deb
\- source: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0\-20121227\-075624\-1.tar.gz
\- source_hash: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0\-20121227\-075624\-1.dsc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.extract_hash /etc/foo sha512 /path/to/hash/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.file_exists(path)
Tests to see if path is a valid file. Returns True/False.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.file_exists /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.find(path, **kwargs)
Approximate the Unix \fBfind(1)\fP command and return a list of paths that
meet the specified criteria.
.sp
The options include match criteria:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
and/or actions:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
The default action is \(aqprint=path\(aq.
.sp
file\-glob:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
path\-regex: a Python re (regular expression) pattern to match pathnames
.sp
file\-types: a string of one or more of the following:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
b: bytes
k: kilobytes
m: megabytes
g: gigabytes
t: terabytes
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
interval:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
print\-opts: a comma and/or space separated list of one or more of the
following:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_devmm(name)
Get major/minor info from a device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_devmm /dev/chr
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_diff(minionfile, masterfile, env=None, saltenv=\(aqbase\(aq)
Return unified diff of file compared to file on master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_gid(path, follow_symlinks=True)
Return the id of the group that owns a given file
.INDENT 7.0
.TP
.B path
file or directory of which to get the gid
.TP
.B follow_symlinks
indicated if symlinks should be followed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_gid /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 0.16.4: \fBfollow_symlinks\fP option added
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_group(path, follow_symlinks=True)
Return the group that owns a given file
.INDENT 7.0
.TP
.B path
file or directory of which to get the group
.TP
.B follow_symlinks
indicated if symlinks should be followed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_group /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 0.16.4: \fBfollow_symlinks\fP option added
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_hash(path, form=\(aqsha256\(aq, chunk_size=4096)
Get the hash sum of a file
.INDENT 7.0
.TP
.B This is better than \fBget_sum\fP for the following reasons:
.INDENT 7.0
.IP \(bu 2
It does not read the entire file into memory.
.IP \(bu 2
.INDENT 2.0
.TP
.B It does not return a string on error. The returned value of
\fBget_sum\fP cannot really be trusted since it is vulnerable to
collisions: \fBget_sum(..., \(aqxyz\(aq) == \(aqHash xyz not supported\(aq\fP
.UNINDENT
.UNINDENT
.TP
.B path
path to the file or directory
.TP
.B form
desired sum format
.TP
.B chunk_size
amount to sum at once
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_hash /etc/shadow
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_managed(name, template, source, source_hash, user, group, mode, saltenv, context, defaults, **kwargs)
Return the managed file data for file.managed
.INDENT 7.0
.TP
.B name
location where the file lives on the server
.TP
.B template
template format
.TP
.B source
managed source file
.TP
.B source_hash
hash of the source file
.TP
.B user
user owner
.TP
.B group
group owner
.TP
.B mode
file mode
.TP
.B context
variables to add to the environment
.TP
.B default
default values of for context_dict
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root root \(aq755\(aq base None None
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_mode(path, follow_symlinks=True)
Return the mode of a file
.INDENT 7.0
.TP
.B path
file or directory of which to get the mode
.TP
.B follow_symlinks
indicated if symlinks should be followed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_mode /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.1.0: \fBfollow_symlinks\fP option added
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_selinux_context(path)
Get an SELinux context from a given path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_selinux_context /etc/hosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_sum(path, form=\(aqsha256\(aq)
Return the sum for the given file, default is md5, sha1, sha224, sha256,
sha384, sha512 are supported
.INDENT 7.0
.TP
.B path
path to the file or directory
.TP
.B form
desired sum format
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_sum /etc/passwd sha512
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_uid(path, follow_symlinks=True)
Return the id of the user that owns a given file
.INDENT 7.0
.TP
.B path
file or directory of which to get the uid
.TP
.B follow_symlinks
indicated if symlinks should be followed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_uid /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 0.16.4: \fBfollow_symlinks\fP option added
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.get_user(path, follow_symlinks=True)
Return the user that owns a given file
.INDENT 7.0
.TP
.B path
file or directory of which to get the user
.TP
.B follow_symlinks
indicated if symlinks should be followed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_user /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 0.16.4: \fBfollow_symlinks\fP option added
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.gid_to_group(gid)
Convert the group id to the group name on this system
.INDENT 7.0
.TP
.B gid
gid to convert to a group name
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.gid_to_group 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.grep(path, pattern, *args)
Grep for a string in the specified file
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function\(aqs return value is slated for refinement in future
versions of Salt
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B path
A file path
.TP
.B pattern
A string. For example:
\fBtest\fP
\fBa[0\-5]\fP
.TP
.B args
grep options. For example:
\fB" \-v"\fP
\fB" \-i \-B2"\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.grep /etc/passwd nobody
salt \(aq*\(aq file.grep /etc/sysconfig/network\-scripts/ifcfg\-eth0 ipaddr " \-i"
salt \(aq*\(aq file.grep /etc/sysconfig/network\-scripts/ifcfg\-eth0 ipaddr " \-i \-B2"
salt \(aq*\(aq file.grep "/etc/sysconfig/network\-scripts/*" ipaddr " \-i \-l"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.group_to_gid(group)
Convert the group to the gid on this system
.INDENT 7.0
.TP
.B group
group to convert to its gid
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.group_to_gid root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.is_blkdev(name)
Check if a file exists and is a block device.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.is_blkdev /dev/blk
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.is_chrdev(name)
Check if a file exists and is a character device.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.is_chrdev /dev/chr
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.is_fifo(name)
Check if a file exists and is a FIFO.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.is_fifo /dev/fifo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.is_link(path)
Check if the path is a symlink
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.is_link /path/to/link
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.join(*args)
Return a normalized file system path for the underlying OS
.sp
New in version 2014.7.0.
.sp
This can be useful at the CLI but is frequently useful when scripting
combining path variables:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% set www_root = \(aq/var\(aq %}
{% set app_dir = \(aqmyapp\(aq %}
myapp_config:
file:
\- managed
\- name: {{ salt[\(aqfile.join\(aq](www_root, app_dir, \(aqconfig.yaml\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.join \(aq/\(aq \(aqusr\(aq \(aqlocal\(aq \(aqbin\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.lchown(path, user, group)
Chown a file, pass the file the desired user and group without following
symlinks.
.INDENT 7.0
.TP
.B path
path to the file or directory
.TP
.B user
user owner
.TP
.B group
group owner
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.chown /etc/passwd root root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.link(src, path)
New in version 2014.1.0.
.sp
Create a hard link to a file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.link /path/to/file /path/to/link
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.list_backups(path, limit=None)
New in version 0.17.0.
.sp
Lists the previous versions of a file backed up using Salt\(aqs \fBfile
state backup\fP system.
.INDENT 7.0
.TP
.B path
The path on the minion to check for backups
.TP
.B limit
Limit the number of results to the most recent N backups
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.list_backups /foo/bar/baz.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.lstat(path)
New in version 2014.1.0.
.sp
Returns the lstat attributes for the given file or dir. Does not support
symbolic links.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.lstat /path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.makedirs_(path, user=None, group=None, mode=None)
Ensure that the directory containing this path is available.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The path must end with a trailing slash otherwise the directory/directories
will be created up to the parent directory. For example if path is
\fB/opt/code\fP, then it would be treated as \fB/opt/\fP but if the path
ends with a trailing slash like \fB/opt/code/\fP, then it would be
treated as \fB/opt/code/\fP\&.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.makedirs /opt/code/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.makedirs_perms(name, user=None, group=None, mode=\(aq0755\(aq)
Taken and modified from os.makedirs to set user, group and mode for each
directory created.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.makedirs_perms /opt/code
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, saltenv, backup, makedirs=False, template=None, show_diff=True, contents=None, dir_mode=None, follow_symlinks=True)
Checks the destination against what was retrieved with get_managed and
makes the appropriate modifications (if necessary).
.INDENT 7.0
.TP
.B name
location to place the file
.TP
.B sfn
location of cached file on the minion
.sp
This is the path to the file stored on the minion. This file is placed on the minion
using cp.cache_file. If the hash sum of that file matches the source_sum, we do not
transfer the file to the minion again.
.sp
This file is then grabbed and if it has template set, it renders the file to be placed
into the correct place on the system using salt.files.utils.copyfile()
.TP
.B source
file reference on the master
.TP
.B source_hash
sum hash for source
.TP
.B user
user owner
.TP
.B group
group owner
.TP
.B backup
backup_mode
.TP
.B makedirs
make directories if they do not exist
.TP
.B template
format of templating
.TP
.B show_diff
Include diff in state return
.TP
.B contents:
contents to be placed in the file
.TP
.B dir_mode
mode for directories created with makedirs
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.manage_file /etc/httpd/conf.d/httpd.conf \(aq\(aq \(aq{}\(aq salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq root root \(aq755\(aq base \(aq\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: \fBfollow_symlinks\fP option added
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.mkdir(dir_path, user=None, group=None, mode=None)
Ensure that a directory is available.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.mkdir /opt/jetty/context
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode=\(aq0600\(aq)
.INDENT 7.0
.INDENT 3.5
New in version 0.17.0.
.sp
Create a block device, character device, or fifo pipe.
Identical to the gnu mknod.
.sp
CLI Examples:
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.mknod /dev/chr c 180 31
salt \(aq*\(aq file.mknod /dev/blk b 8 999
salt \(aq*\(aq file.nknod /dev/fifo p
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.mknod_blkdev(name, major, minor, user=None, group=None, mode=\(aq0660\(aq)
New in version 0.17.0.
.sp
Create a block device.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.mknod_blkdev /dev/blk 8 999
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.mknod_chrdev(name, major, minor, user=None, group=None, mode=\(aq0660\(aq)
New in version 0.17.0.
.sp
Create a character device.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.mknod_chrdev /dev/chr 180 31
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.mknod_fifo(name, user=None, group=None, mode=\(aq0660\(aq)
New in version 0.17.0.
.sp
Create a FIFO pipe.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.mknod_fifo /dev/fifo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.open_files(by_pid=False)
Return a list of all physical open files on the system.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq file.open_files
salt \(aq*\(aq file.open_files by_pid=True
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.pardir()
Return the relative parent directory path symbol for underlying OS
.sp
New in version 2014.7.0.
.sp
This can be useful when constructing Salt Formulas.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% set pardir = salt[\(aqfile.pardir\(aq]() %}
{% set final_path = salt[\(aqfile.join\(aq](\(aqsubdir\(aq, pardir, \(aqconfdir\(aq) %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.pardir
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.patch(originalfile, patchfile, options=\(aq\(aq, dry_run=False)
New in version 0.10.4.
.sp
Apply a patch to a file
.sp
Equivalent to:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
patch <options> <originalfile> <patchfile>
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B originalfile
The full path to the file or directory to be patched
.TP
.B patchfile
A patch file to apply to \fBoriginalfile\fP
.TP
.B options
Options to pass to patch.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.patch /opt/file.txt /tmp/file.txt.patch
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.path_exists_glob(path)
Tests to see if path after expansion is a valid path (file or directory).
Expansion allows usage of ? * and character ranges []. Tilde expansion
is not supported. Returns True/False.
.sp
New in version Hellium.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.path_exists_glob /etc/pam*/pass*
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.prepend(path, *args, **kwargs)
New in version 2014.7.0.
.sp
Prepend text to the beginning of a file
.INDENT 7.0
.TP
.B path
path to file
.TP
.B args
strings to prepend to the file
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.prepend /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
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
If you need to pass a string to append and that string contains
an equal sign, you \fBmust\fP include the argument name, args.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.prepend /etc/motd args=\(aqcheese=spam\(aq
salt \(aq*\(aq file.prepend /etc/motd args="[\(aqcheese=spam\(aq,\(aqspam=cheese\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.psed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, flags=\(aqgMS\(aq, escape_all=False, multi=False)
Deprecated since version 0.17.0: Use \fI\%replace()\fP instead.
.sp
Make a simple edit to a file (pure Python version)
.sp
Equivalent to:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"
.ft P
.fi
.UNINDENT
.UNINDENT
.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 flags
\fBgMS\fP.INDENT 7.0
.TP
.B Flags to modify the search. Valid values are:
.INDENT 7.0
.IP \(bu 2
\fBg\fP: Replace all occurrences of the pattern, not just the first.
.IP \(bu 2
\fBI\fP: Ignore case.
.IP \(bu 2
\fBL\fP: Make \fB\ew\fP, \fB\eW\fP, \fB\eb\fP, \fB\eB\fP, \fB\es\fP and \fB\eS\fP
dependent on the locale.
.IP \(bu 2
\fBM\fP: Treat multiple lines as a single line.
.IP \(bu 2
\fBS\fP: Make \fI\&.\fP match all characters, including newlines.
.IP \(bu 2
\fBU\fP: Make \fB\ew\fP, \fB\eW\fP, \fB\eb\fP, \fB\eB\fP, \fB\ed\fP, \fB\eD\fP,
\fB\es\fP and \fB\eS\fP dependent on Unicode.
.IP \(bu 2
\fBX\fP: Verbose (whitespace is ignored).
.UNINDENT
.UNINDENT
.TP
.B multi: \fBFalse\fP
If True, treat the entire file as a single line
.UNINDENT
.sp
Forward slashes and single quotes will be escaped automatically in the
\fBbefore\fP and \fBafter\fP patterns.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.readdir(path)
New in version 2014.1.0.
.sp
Return a list containing the contents of a directory
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.readdir /path/to/dir/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.readlink(path)
New in version 2014.1.0.
.sp
Return the path that a symlink points to
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.readlink /path/to/link
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.remove(path)
Remove the named file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.remove /tmp/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.rename(src, dst)
Rename a file or directory
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.rename /path/to/src /path/to/dst
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.replace(path, pattern, repl, count=0, flags=0, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, backup=\(aq.bak\(aq, dry_run=False, search_only=False, show_changes=True)
New in version 0.17.0.
.sp
Replace occurrences of a pattern in a file
.sp
This is a pure Python implementation that wraps Python\(aqs \fI\%sub()\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpath\fP \-\- Filesystem path to the file to be edited
.IP \(bu 2
\fBpattern\fP \-\- Python\(aqs regular expression search
\fI\%https://docs.python.org/2/library/re.html\fP
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.replace /path/to/file pattern="bind\-address\es*=" repl=\(aqbind\-address:\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBrepl\fP \-\- The replacement text
.IP \(bu 2
\fBcount\fP \-\- Maximum number of pattern occurrences to be replaced
.IP \(bu 2
\fBflags\fP (\fIlist or int\fP) \-\- A list of flags defined in the \fI\%re module documentation\fP\&. Each list item should be a string that will
correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq,
\(aqMULTILINE\(aq]\fP\&. Note: multiline searches must specify \fBfile\fP as the
\fBbufsize\fP argument below.
.IP \(bu 2
\fBbufsize\fP (\fIint or str\fP) \-\- How much of the file to buffer into memory at once. The
default value \fB1\fP processes one line at a time. The special value
\fBfile\fP may be specified which will read the entire file into memory
before processing. Note: multiline searches must specify \fBfile\fP
buffering.
.IP \(bu 2
\fBappend_if_not_found\fP \-\-
.sp
If pattern is not found and set to \fBTrue\fP
then, the content will be appended to the file.
.sp
New in version 2014.7.0.
.IP \(bu 2
\fBprepend_if_not_found\fP \-\-
.sp
If pattern is not found and set to \fBTrue\fP
then, the content will be prepended to the file.
.sp
New in version 2014.7.0.
.IP \(bu 2
\fBnot_found_content\fP \-\-
.sp
Content to use for append/prepend if not found. If
None (default), uses repl. Useful when repl uses references to group in
pattern.
.sp
New in version 2014.7.0.
.IP \(bu 2
\fBbackup\fP \-\- The file extension to use for a backup of the file before
editing. Set to \fBFalse\fP to skip making a backup.
.IP \(bu 2
\fBdry_run\fP \-\- Don\(aqt make any edits to the file
.IP \(bu 2
\fBsearch_only\fP \-\- Just search for the pattern; ignore the replacement;
stop on the first match
.IP \(bu 2
\fBshow_changes\fP \-\- Output a unified diff of the old file and the new
file. If \fBFalse\fP return a boolean if any changes were made.
Note: using this option will store two copies of the file in\-memory
(the original version and the edited version) in order to generate the
diff.
.UNINDENT
.TP
.B Return type
bool or str
.UNINDENT
.sp
If an equal sign (\fB=\fP) appears in an argument to a Salt command it is
interpreted as a keyword argument in the format \fBkey=val\fP\&. That
processing can be bypassed in order to pass an equal sign through to the
remote shell command by manually specifying the kwarg:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.replace /path/to/file pattern=\(aq=\(aq repl=\(aq:\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.replace /etc/httpd/httpd.conf pattern=\(aqLogLevel warn\(aq repl=\(aqLogLevel info\(aq
salt \(aq*\(aq file.replace /some/file pattern=\(aqbefore\(aq repl=\(aqafter\(aq flags=\(aq[MULTILINE, IGNORECASE]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.restore_backup(path, backup_id)
New in version 0.17.0.
.sp
Restore a previous version of a file that was backed up using Salt\(aqs
\fBfile state backup\fP system.
.INDENT 7.0
.TP
.B path
The path on the minion to check for backups
.TP
.B backup_id
The numeric id for the backup you wish to restore, as found using
\fI\%file.list_backups\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.restore_backup /foo/bar/baz.txt 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.restorecon(path, recursive=False)
Reset the SELinux context on a given path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.restorecon /home/user/.ssh/authorized_keys
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.rmdir(path)
New in version 2014.1.0.
.sp
Remove the specified directory. Fails if a directory is not empty.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.rmdir /tmp/foo/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.search(path, pattern, flags=0, bufsize=1)
New in version 0.17.0.
.sp
Search for occurrences of a pattern in a file
.sp
Params are identical to \fI\%replace()\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.search /etc/crontab \(aqmymaintenance.sh\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.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, escape_all=False, negate_match=False)
Deprecated since version 0.17.0: Use \fI\%replace()\fP instead.
.sp
Make a simple edit to a file
.sp
Equivalent to:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>"
.ft P
.fi
.UNINDENT
.UNINDENT
.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\-insensitive pattern
matching
.TP
.B negate_match
False
Negate the search command (\fB!\fP)
.sp
New in version 0.17.0.
.UNINDENT
.sp
Forward slashes and single quotes will be escaped automatically in the
\fBbefore\fP and \fBafter\fP patterns.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.sed_contains(path, text, limit=\(aq\(aq, flags=\(aqg\(aq)
Deprecated since version 0.17.0: Use \fI\%search()\fP instead.
.sp
Return True if the file at \fBpath\fP contains \fBtext\fP\&. Utilizes sed to
perform the search (line\-wise search).
.sp
Note: the \fBp\fP flag will be added to any flags you pass in.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.seek_read(path, size, offset)
New in version 2014.1.0.
.sp
Seek to a position on a file and read it
.INDENT 7.0
.TP
.B path
path to file
.TP
.B seek
amount to read at once
.TP
.B offset
offset to start into the file
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.seek_read /path/to/file 4096 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.seek_write(path, data, offset)
New in version 2014.1.0.
.sp
Seek to a position on a file and write to it
.INDENT 7.0
.TP
.B path
path to file
.TP
.B data
data to write to file
.TP
.B offset
position in file to start writing
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.seek_write /path/to/file \(aqsome data\(aq 4096
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.set_mode(path, mode)
Set the mode of a file
.INDENT 7.0
.TP
.B path
file or directory of which to set the mode
.TP
.B mode
mode to set the path to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.set_mode /etc/passwd 0644
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.set_selinux_context(path, user=None, role=None, type=None, range=None)
Set a specific SELinux label on a given path
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.set_selinux_context path <role> <type> <range>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.source_list(source, source_hash, saltenv)
Check the source list and return the source to use
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.source_list salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: <md5sum>}\(aq base
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.stats(path, hash_type=None, follow_symlinks=True)
Return a dict containing the stats for a given file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.stats /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.statvfs(path)
New in version 2014.1.0.
.sp
Perform a statvfs call against the filesystem that the file resides on
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.statvfs /path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.symlink(src, path)
Create a symbolic link to a file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.symlink /path/to/file /path/to/link
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.touch(name, atime=None, mtime=None)
New in version 0.9.5.
.sp
Just like the \fBtouch\fP 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
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.touch /var/log/emptyfile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.truncate(path, length)
New in version 2014.1.0.
.sp
Seek to a position on a file and delete everything after that point
.INDENT 7.0
.TP
.B path
path to file
.TP
.B length
offset into file to truncate
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.truncate /path/to/file 512
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.uid_to_user(uid)
Convert a uid to a user name
.INDENT 7.0
.TP
.B uid
uid to convert to a username
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.uid_to_user 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.uncomment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq)
Deprecated since version 0.17.0: Use \fI\%replace()\fP instead.
.sp
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
.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
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.uncomment /etc/hosts.deny \(aqALL: PARANOID\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.user_to_uid(user)
Convert user name to a uid
.INDENT 7.0
.TP
.B user
user name to convert to its uid
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.user_to_uid root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.file.write(path, *args, **kwargs)
New in version 2014.7.0.
.sp
Write text to a file, overwriting any existing contents.
.INDENT 7.0
.TP
.B path
path to file
.TP
.B args
strings to write to the file
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.write /etc/motd \e
"With all thine offerings thou shalt offer salt."
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
If you need to pass a string to append and that string contains
an equal sign, you \fBmust\fP include the argument name, args.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.write /etc/motd args=\(aqcheese=spam\(aq
salt \(aq*\(aq file.write /etc/motd args="[\(aqcheese=spam\(aq,\(aqspam=cheese\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.freebsd_sysctl
.sp
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
.B salt.modules.freebsd_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsd_sysctl.get(name)
Return a single sysctl parameter for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.get hw.physmem
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsd_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq)
Assign and persist a simple sysctl parameter for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50
salt \(aq*\(aq sysctl.persist coretemp_load NO config=/boot/loader.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsd_sysctl.show(config_file=False)
Return a list of sysctl parameters for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.freebsdjail
.sp
The jail module for FreeBSD
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.fstab(jail)
Display contents of a fstab(5) file defined in specified
jail\(aqs configuration. If no file is defined, return False.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.fstab <jail name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.get_enabled()
Return which jails are set to be run
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.is_enabled()
See if jail service is actually enabled on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.is_enabled <jail name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.restart(jail=\(aq\(aq)
Restart the specified jail or all, if none specified
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.restart [<jail name>]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.show_config(jail)
Display specified jail\(aqs configuration
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.show_config <jail name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.start(jail=\(aq\(aq)
Start the specified jail or all, if none specified
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.start [<jail name>]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.status(jail)
See if specified jail is currently running
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.status <jail name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.stop(jail=\(aq\(aq)
Stop the specified jail or all, if none specified
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.stop [<jail name>]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdjail.sysctl()
Dump all jail related kernel states (sysctl)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq jail.sysctl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.freebsdkmod
.sp
Module to manage FreeBSD kernel modules
.INDENT 0.0
.TP
.B salt.modules.freebsdkmod.available()
Return a list of all available kernel modules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.available
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdkmod.check_available(mod)
Check to see if the specified kernel module is available
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.check_available vmm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdkmod.is_loaded(mod)
Check to see if the specified kernel module is loaded
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.is_loaded vmm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdkmod.load(mod, persist=False)
Load the specified kernel module
.INDENT 7.0
.TP
.B mod
Name of the module to add
.TP
.B persist
Write the module to sysrc kld_modules to make it load on system reboot
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.load bhyve
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdkmod.lsmod()
Return a dict containing information about currently loaded modules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.lsmod
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdkmod.mod_list(only_persist=False)
Return a list of the loaded module names
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.mod_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdkmod.remove(mod, persist=False)
Remove the specified kernel module
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.remove vmm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.freebsdpkg
.sp
Remote package support using \fBpkg_add(1)\fP
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This module has been completely rewritten. Up to and including version
0.17.0, it supported \fBpkg_add(1)\fP, but checked for the existence of a
pkgng local database and, if found, would provide some of pkgng\(aqs
functionality. The rewrite of this module has removed all pkgng support,
and moved it to the \fBpkgng\fP execution module. For
versions <= 0.17.0, the documentation here should not be considered
accurate. If your Minion is running one of these versions, then the
documentation for this module can be viewed using the \fBsys.doc\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt bsdminion sys.doc pkg
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This module acts as the default package provider for FreeBSD 9 and older. If
you need to use pkgng on a FreeBSD 9 system, you will need to override the
\fBpkg\fP provider by setting the \fBproviders\fP parameter in your
Minion config file, in order to use pkgng.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
providers:
pkg: pkgng
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
More information on pkgng support can be found in the documentation for the
\fBpkgng\fP module.
.sp
This module will respect the \fBPACKAGEROOT\fP and \fBPACKAGESITE\fP environment
variables, if set, but these values can also be overridden in several ways:
.INDENT 0.0
.IP 1. 3
\fBSalt configuration parameters.\fP The configuration parameters
\fBfreebsdpkg.PACKAGEROOT\fP and \fBfreebsdpkg.PACKAGESITE\fP are recognized.
These config parameters are looked up using \fBconfig.get\fP and can thus be specified in the Master config
file, Grains, Pillar, or in the Minion config file. Example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
freebsdpkg.PACKAGEROOT: ftp://ftp.freebsd.org/
freebsdpkg.PACKAGESITE: ftp://ftp.freebsd.org/pub/FreeBSD/ports/ia64/packages\-9\-stable/Latest/
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
\fBCLI arguments.\fP Both the \fBpackageroot\fP (used interchangeably with
\fBfromrepo\fP for API compatibility) and \fBpackagesite\fP CLI arguments are
recognized, and override their config counterparts from section 1 above.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos:FreeBSD\(aq pkg.install zsh fromrepo=ftp://ftp2.freebsd.org/
salt \-G \(aqos:FreeBSD\(aq pkg.install zsh packageroot=ftp://ftp2.freebsd.org/
salt \-G \(aqos:FreeBSD\(aq pkg.install zsh packagesite=ftp://ftp2.freebsd.org/pub/FreeBSD/ports/ia64/packages\-9\-stable/Latest/
\&.. note::
These arguments can also be passed through in states:
.. code\-block:: yaml
zsh:
pkg.installed:
\- fromrepo: ftp://ftp2.freebsd.org/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.file_dict(*packages)
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of _every_ file on the
system\(aqs package database (not generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.file_list(*packages)
List the files that belong to a package. Not specifying any packages will
return a list of _every_ file on the system\(aqs package database (not
generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs)
Install package(s) using \fBpkg_add(1)\fP
.INDENT 7.0
.TP
.B name
The name of the package to be installed.
.TP
.B refresh
Whether or not to refresh the package database before installing.
.TP
.B fromrepo or packageroot
Specify a package repository from which to install. Overrides the
system default, as well as the PACKAGEROOT environment variable.
.TP
.B packagesite
Specify the exact directory from which to install the remote package.
Overrides the PACKAGESITE environment variable, if present.
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from a software repository. Must be
passed as a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B sources
A list of packages to install. Must be passed as a list of dicts,
with the keys being package names, and the values being the source URI
or local path to the package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.deb"}, {"bar": "salt://bar.deb"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.latest_version(*names, **kwargs)
\fBpkg_add(1)\fP is not capable of querying for remote packages, so this
function will always return results as if there is no package available for
install or upgrade.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.list_pkgs(versions_as_list=False, with_origin=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B with_origin
False
Return a nested dictionary containing both the origin name and version
for each installed package.
.sp
New in version 2014.1.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.refresh_db()
\fBpkg_add(1)\fP does not use a local database of available packages, so this
function simply returns \fBTrue\fP\&. it exists merely for API compatibility.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.remove(name=None, pkgs=None, **kwargs)
Remove packages using \fBpkg_delete(1)\fP
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.upgrade()
Upgrades are not supported with \fBpkg_add(1)\fP\&. This function is included
for API compatibility only and always returns an empty dict.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdpkg.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.INDENT 7.0
.TP
.B with_origin
False
Return a nested dictionary containing both the origin name and version
for each specified package.
.sp
New in version 2014.1.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.freebsdports
.sp
Install software from the FreeBSD \fBports(7)\fP system
.sp
New in version 2014.1.0.
.sp
This module allows you to install ports using \fBBATCH=yes\fP to bypass
configuration prompts. It is recommended to use the the \fBports state\fP to install ports, but it it also possible to use
this module exclusively from the command line.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt minion\-id ports.config security/nmap IPV6=off
salt minion\-id ports.install security/nmap
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.config(name, reset=False, **kwargs)
Modify configuration options for a given port. Multiple options can be
specified. To see the available options for a port, use
\fI\%ports.showconfig\fP\&.
.INDENT 7.0
.TP
.B name
The port name, in \fBcategory/name\fP format
.TP
.B reset
False
If \fBTrue\fP, runs a \fBmake rmconfig\fP for the port, clearing its
configuration before setting the desired options
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ports.config security/nmap IPV6=off
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.deinstall(name)
De\-install a port.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ports.deinstall security/nmap
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.install(name, clean=True)
Install a port from the ports tree. Installs using \fBBATCH=yes\fP for
non\-interactive building. To set config options for a given port, use
\fI\%ports.config\fP\&.
.INDENT 7.0
.TP
.B clean
True
If \fBTrue\fP, cleans after installation. Equivalent to running \fBmake
install clean BATCH=yes\fP\&.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
It may be helpful to run this function using the \fB\-t\fP option to set a
higher timeout, since compiling a port may cause the Salt command to
exceed the default timeout.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-t 1200 \(aq*\(aq ports.install security/nmap
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.list_all()
Lists all ports available.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ports.list_all
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Takes a while to run, and returns a \fBLOT\fP of output
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.rmconfig(name)
Clear the cached options for the specified port; run a \fBmake rmconfig\fP
.INDENT 7.0
.TP
.B name
The name of the port to clear
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ports.rmconfig security/nmap
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.search(name)
Search for matches in the ports tree. Globs are supported, and the category
is optional
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ports.search \(aqsecurity/*\(aq
salt \(aq*\(aq ports.search \(aqsecurity/n*\(aq
salt \(aq*\(aq ports.search nmap
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Takes a while to run
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.showconfig(name, default=False, dict_return=False)
Show the configuration options for a given port.
.INDENT 7.0
.TP
.B default
False
Show the default options for a port (not necessarily the same as the
current configuration)
.TP
.B dict_return
False
Instead of returning the output of \fBmake showconfig\fP, return the data
in an dictionary
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ports.showconfig security/nmap
salt \(aq*\(aq ports.showconfig security/nmap default=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdports.update(extract=False)
Update the ports tree
.INDENT 7.0
.TP
.B extract
False
If \fBTrue\fP, runs a \fBportsnap extract\fP after fetching, should be used
for first\-time installation of the ports tree.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ports.update
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.freebsdservice
.sp
The service module for FreeBSD
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.available(name)
Check that the given service is available.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.disable(name, **kwargs)
Disable the named service to start at boot
.sp
Arguments the same as for enable()
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.disabled(name)
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.enable(name, **kwargs)
Enable the named service to start at boot
.INDENT 7.0
.TP
.B name
service name
.TP
.B config
/etc/rc.conf
Config file for managing service. If config value is
empty string, then /etc/rc.conf.d/<service> used.
See man rc.conf(5) for details.
.sp
Also service.config variable can be used to change default.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.enabled(name)
Return True if the named service is enabled, false otherwise
.INDENT 7.0
.TP
.B name
Service name
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.get_all()
Return a list of all available services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.get_disabled()
Return what services are available but not enabled to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.get_enabled()
Return what services are set to run on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.reload_(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.status(name, sig=None)
Return the status for a service (True or False).
.INDENT 7.0
.TP
.B name
Name of service
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.freebsdservice.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.gem
.sp
Manage ruby gems.
.INDENT 0.0
.TP
.B salt.modules.gem.install(gems, ruby=None, runas=None, version=None, rdoc=False, ri=False, proxy=None)
Installs one or several gems.
.INDENT 7.0
.TP
.B gems
The gems to install
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.TP
.B version
None
Specify the version to install for the gem.
Doesn\(aqt play nice with multiple gems at once
.TP
.B rdoc
False
Generate RDoc documentation for the gem(s).
.TP
.B ri
False
Generate RI documentation for the gem(s).
.TP
.B proxy
None
Use the specified HTTP proxy server for all outgoing traffic.
Format: \fI\%http://hostname[:port\fP]
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.install vagrant
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gem.list_(prefix=\(aq\(aq, ruby=None, runas=None)
List locally installed gems.
.INDENT 7.0
.TP
.B prefix :
Only list gems when the name matches this prefix.
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gem.sources_add(source_uri, ruby=None, runas=None)
Add a gem source.
.INDENT 7.0
.TP
.B source_uri
The source URI to add.
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.sources_add http://rubygems.org/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gem.sources_list(ruby=None, runas=None)
List the configured gem sources.
.INDENT 7.0
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.sources_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gem.sources_remove(source_uri, ruby=None, runas=None)
Remove a gem source.
.INDENT 7.0
.TP
.B source_uri
The source URI to remove.
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.sources_remove http://rubygems.org/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gem.uninstall(gems, ruby=None, runas=None)
Uninstall one or several gems.
.INDENT 7.0
.TP
.B gems
The gems to uninstall.
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.uninstall vagrant
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gem.update(gems, ruby=None, runas=None)
Update one or several gems.
.INDENT 7.0
.TP
.B gems
The gems to update.
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.update vagrant
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gem.update_system(version=\(aq\(aq, ruby=None, runas=None)
Update rubygems.
.INDENT 7.0
.TP
.B version
(newest)
The version of rubygems to install.
.TP
.B ruby
None
If RVM or rbenv are installed, the ruby version and gemset to use.
.TP
.B runas
None
The user to run gem as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gem.update_system
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.genesis
.sp
Module for managing container and VM images
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B salt.modules.genesis.avail_platforms()
Return which platforms are available
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion genesis.avail_platforms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.genesis.bootstrap(platform, root, img_format=\(aqdir\(aq, fs_format=\(aqext2\(aq, arch=None, flavor=None, repo_url=None, static_qemu=None)
Create an image for a specific platform.
.sp
Please note that this function \fIMUST\fP be run as root, as images that are
created make files belonging to root.
.INDENT 7.0
.TP
.B platform
Which platform to use to create the image. Currently supported platforms
are rpm, deb and pacman.
.TP
.B root
Local path to create the root of the image filesystem.
.TP
.B img_format
Which format to create the image in. By default, just copies files into
a directory on the local filesystem (\fBdir\fP). Future support will exist
for \fBsparse\fP\&.
.TP
.B fs_format
When using a non\-\fBdir\fP img_format, which filesystem to format the
image to. By default, \fBext2\fP\&.
.TP
.B arch
Architecture to install packages for, if supported by the underlying
bootstrap tool. Currently only used for deb.
.TP
.B flavor
Which flavor of operating system to install. This correlates to a
specific directory on the distribution repositories. For instance,
\fBwheezy\fP on Debian.
.TP
.B repo_url
Mainly important for Debian\-based repos. Base URL for the mirror to
install from. (e.x.: \fI\%http://ftp.debian.org/debian/\fP)
.TP
.B static_qemu
Local path to the static qemu binary required for this arch.
(e.x.: /usr/bin/qemu\-amd64\-static)
.TP
.B pkg_confs
The location of the conf files to copy into the image, to point the
installer to the right repos and configuration.
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion genesis.bootstrap pacman /root/arch
salt myminion genesis.bootstrap rpm /root/redhat
salt myminion genesis.bootstrap deb /root/wheezy arch=amd64 flavor=wheezy static_qemu=/usr/bin/qemu\-x86_64\-static
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.genesis.pack(name, root, path=None, pack_format=\(aqtar\(aq, compress=\(aqbzip2\(aq)
Pack up a directory structure, into a specific format
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion genesis.pack centos /root/centos
salt myminion genesis.pack centos /root/centos pack_format=\(aqtar\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.genesis.unpack(name, dest=None, path=None, pack_format=\(aqtar\(aq, compress=\(aqbz2\(aq)
Unpack an image into a directory structure
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion genesis.unpack centos /root/centos
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.gentoo_service
.sp
Top level package command wrapper, used to translate the os detected by grains
to the correct service manager
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.disable(name, **kwargs)
Disable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.disabled(name)
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.enable(name, **kwargs)
Enable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.enabled(name)
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.get_all()
Return all available boot services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.get_disabled()
Return a set of services that are installed but disabled
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.get_enabled()
Return a list of service that are enabled on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.status(name, sig=None)
Return the status for a service, returns the PID or an empty string if the
service is running or not, pass a signature to use to find the service via
ps
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name> [service signature]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoo_service.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.gentoolkitmod
.sp
Support for Gentoolkit
.INDENT 0.0
.TP
.B salt.modules.gentoolkitmod.eclean_dist(destructive=False, package_names=False, size_limit=0, time_limit=0, fetch_restricted=False, exclude_file=\(aq/etc/eclean/distfiles.exclude\(aq)
Clean obsolete portage sources
.INDENT 7.0
.TP
.B destructive
Only keep minimum for reinstallation
.TP
.B package_names
Protect all versions of installed packages. Only meaningful if used
with destructive=True
.TP
.B size_limit <size>
Don\(aqt delete distfiles bigger than <size>.
<size> is a size specification: "10M" is "ten megabytes",
"200K" is "two hundreds kilobytes", etc. Units are: G, M, K and B.
.TP
.B time_limit <time>
Don\(aqt delete distfiles files modified since <time>
<time> is an amount of time: "1y" is "one year", "2w" is
"two weeks", etc. Units are: y (years), m (months), w (weeks),
d (days) and h (hours).
.TP
.B fetch_restricted
Protect fetch\-restricted files. Only meaningful if used with
destructive=True
.TP
.B exclude_file
Path to exclusion file. Default is /etc/eclean/distfiles.exclude
This is the same default eclean\-dist uses. Use None if this file
exists and you want to ignore.
.UNINDENT
.sp
Returns a dict containing the cleaned, saved, and deprecated dists:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqcleaned\(aq: {<dist file>: <size>},
\(aqdeprecated\(aq: {<package>: <dist file>},
\(aqsaved\(aq: {<package>: <dist file>},
\(aqtotal_cleaned\(aq: <size>}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gentoolkit.eclean_dist destructive=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoolkitmod.eclean_pkg(destructive=False, package_names=False, time_limit=0, exclude_file=\(aq/etc/eclean/packages.exclude\(aq)
Clean obsolete binary packages
.INDENT 7.0
.TP
.B destructive
Only keep minimum for reinstallation
.TP
.B package_names
Protect all versions of installed packages. Only meaningful if used
with destructive=True
.TP
.B time_limit <time>
Don\(aqt delete distfiles files modified since <time>
<time> is an amount of time: "1y" is "one year", "2w" is
"two weeks", etc. Units are: y (years), m (months), w (weeks),
d (days) and h (hours).
.TP
.B exclude_file
Path to exclusion file. Default is /etc/eclean/packages.exclude
This is the same default eclean\-pkg uses. Use None if this file
exists and you want to ignore.
.UNINDENT
.sp
Returns a dict containing the cleaned binary packages:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqcleaned\(aq: {<dist file>: <size>},
\(aqtotal_cleaned\(aq: <size>}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gentoolkit.eclean_pkg destructive=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoolkitmod.glsa_check_list(glsa_list)
List the status of Gentoo Linux Security Advisories
.INDENT 7.0
.TP
.B glsa_list
can contain an arbitrary number of GLSA ids, filenames
containing GLSAs or the special identifiers \(aqall\(aq and \(aqaffected\(aq
.UNINDENT
.sp
Returns a dict containing glsa ids with a description, status, and CVEs:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{<glsa_id>: {\(aqdescription\(aq: <glsa_description>,
\(aqstatus\(aq: <glsa status>,
\(aqCVEs\(aq: [<list of CVEs>]}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gentoolkit.glsa_check_list \(aqaffected\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gentoolkitmod.revdep_rebuild(lib=None)
Fix up broken reverse dependencies
.INDENT 7.0
.TP
.B lib
Search for reverse dependencies for a particular library rather
than every library on the system. It can be a full path to a
library or basic regular expression.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gentoolkit.revdep_rebuild
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.git
.sp
Support for the Git SCM
.INDENT 0.0
.TP
.B salt.modules.git.add(cwd, file_name, user=None, opts=None)
add a file to git
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B file_name
Path to the file in the cwd
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.add /path/to/git/repo /path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.archive(cwd, output, rev=\(aqHEAD\(aq, fmt=None, prefix=None, user=None)
Export a tarball from the repository
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B output
The path to the archive tarball
.TP
.B rev: HEAD
The revision to create an archive from
.TP
.B fmt: None
Format of the resulting archive, zip and tar are commonly used
.TP
.B prefix
None
Prepend <prefix>/ to every filename in the archive
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
If \fBprefix\fP is not specified it defaults to the basename of the repo
directory.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.archive /path/to/repo /path/to/archive.tar.gz
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.branch(cwd, rev, opts=None, user=None)
Interacts with branches.
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B rev
The branch/revision to be used in the command.
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.branch mybranch \-\-set\-upstream\-to=origin/mybranch
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.checkout(cwd, rev, force=False, opts=None, user=None)
Checkout a given revision
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B rev
The remote branch or revision to checkout
.TP
.B force
False
Force a checkout even if there might be overwritten changes
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.checkout /path/to/repo somebranch user=jeff
salt \(aq*\(aq git.checkout /path/to/repo opts=\(aqtestbranch \-\- conf/file1 file2\(aq
salt \(aq*\(aq git.checkout /path/to/repo rev=origin/mybranch opts=\-\-track
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.clone(cwd, repository, opts=None, user=None, identity=None)
Clone a new repository
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B repository
The git URI of the repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.TP
.B identity
None
A path to a private key to use over SSH
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.clone /path/to/repo git://github.com/saltstack/salt.git
salt \(aq*\(aq git.clone /path/to/repo.git\e
git://github.com/saltstack/salt.git \(aq\-\-bare \-\-origin github\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.commit(cwd, message, user=None, opts=None)
create a commit
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B message
The commit message
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.commit /path/to/git/repo \(aqThe commit message\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.config_get(cwd=None, setting_name=None, user=None)
Get a key or keys from the git configuration file (.git/config).
.INDENT 7.0
.TP
.B cwd
None
Optional path to a Git repository
.sp
Changed in version 2014.7.0: Made \fBcwd\fP optional
.TP
.B setting_name
None
The name of the configuration key to get. Required.
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.config_get setting_name=user.email
salt \(aq*\(aq git.config_get /path/to/repo user.name arthur
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.config_set(cwd=None, setting_name=None, setting_value=None, user=None, is_global=False)
Set a key in the git configuration file (.git/config) of the repository or
globally.
.INDENT 7.0
.TP
.B cwd
None
Options path to the Git repository
.sp
Changed in version 2014.7.0: Made \fBcwd\fP optional
.TP
.B setting_name
None
The name of the configuration key to set. Required.
.TP
.B setting_value
None
The (new) value to set. Required.
.TP
.B user
None
Run git as a user other than what the minion runs as
.TP
.B is_global
False
Set to True to use the \(aq\-\-global\(aq flag with \(aqgit config\(aq
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.config_set /path/to/repo user.email me@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.current_branch(cwd, user=None)
Returns the current branch name, if on a branch.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.current_branch /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.describe(cwd, rev=\(aqHEAD\(aq, user=None)
Returns the git describe string (or the SHA hash if there are no tags) for
the given revision
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B rev: HEAD
The revision to describe
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.describe /path/to/repo
salt \(aq*\(aq git.describe /path/to/repo develop
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.fetch(cwd, opts=None, user=None, identity=None)
Perform a fetch on the given repository
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.TP
.B identity
None
A path to a private key to use over SSH
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.fetch /path/to/repo \(aq\-\-all\(aq
salt \(aq*\(aq git.fetch cwd=/path/to/repo opts=\(aq\-\-all\(aq user=johnny
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.init(cwd, opts=None, user=None)
Initialize a new git repository
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.init /path/to/repo.git opts=\(aq\-\-bare\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.ls_remote(cwd, repository=\(aqorigin\(aq, branch=\(aqmaster\(aq, user=None, identity=None)
Returns the upstream hash for any given URL and branch.
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B repository: origin
The name of the repository to get the revision from. Can be the name of
a remote, an URL, etc.
.TP
.B branch: master
The name of the branch to get the revision from.
.TP
.B user
none
run git as a user other than what the minion runs as
.TP
.B identity
none
a path to a private key to use over ssh
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.ls_remote /pat/to/repo origin master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.merge(cwd, branch=\(aq@{upstream}\(aq, opts=None, user=None)
Merge a given branch
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B branch
@{upstream}
The remote branch or revision to merge into the current branch
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.fetch /path/to/repo
salt \(aq*\(aq git.merge /path/to/repo @{upstream}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.pull(cwd, opts=None, user=None, identity=None)
Perform a pull on the given repository
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.TP
.B identity
None
A path to a private key to use over SSH
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.pull /path/to/repo opts=\(aq\-\-rebase origin master\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.push(cwd, remote_name, branch=\(aqmaster\(aq, user=None, opts=None, identity=None)
Push to remote
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B remote_name
Name of the remote to push to
.TP
.B branch
master
Name of the branch to push
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.TP
.B identity
None
A path to a private key to use over SSH
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.push /path/to/git/repo remote\-name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.rebase(cwd, rev=\(aqmaster\(aq, opts=None, user=None)
Rebase the current branch
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B rev
master
The revision to rebase onto the current branch
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.rebase /path/to/repo master
salt \(aq*\(aq git.rebase /path/to/repo \(aqorigin master\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
That is the same as:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
git rebase master
git rebase origin master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.remote_get(cwd, remote=\(aqorigin\(aq, user=None)
get the fetch and push URL for a specified remote name
.INDENT 7.0
.TP
.B remote
origin
the remote name used to define the fetch and push URL
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.remote_get /path/to/repo
salt \(aq*\(aq git.remote_get /path/to/repo upstream
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.remote_set(cwd, name=\(aqorigin\(aq, url=None, user=None)
sets a remote with name and URL like git remote add <remote_name> <remote_url>
.INDENT 7.0
.TP
.B remote_name
origin
defines the remote name
.TP
.B remote_url
None
defines the remote URL; should not be None!
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.remote_set /path/to/repo remote_url=git@github.com:saltstack/salt.git
salt \(aq*\(aq git.remote_set /path/to/repo origin git@github.com:saltstack/salt.git
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.remotes(cwd, user=None)
Get remotes like git remote \-v
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.remotes /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.reset(cwd, opts=None, user=None)
Reset the repository checkout
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.reset /path/to/repo master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.revision(cwd, rev=\(aqHEAD\(aq, short=False, user=None)
Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc)
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B rev: HEAD
The revision
.TP
.B short: False
Return an abbreviated SHA1 git hash
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.revision /path/to/repo mybranch
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.rm(cwd, file_name, user=None, opts=None)
Remove a file from git
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B file_name
Path to the file in the cwd
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.rm /path/to/git/repo /path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.stash(cwd, opts=None, user=None)
Stash changes in the repository checkout
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.stash /path/to/repo master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.status(cwd, user=None)
Return the status of the repository. The returned format uses the status
codes of git\(aqs \(aqporcelain\(aq output mode
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B user
None
Run git as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.status /path/to/git/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.git.submodule(cwd, init=True, opts=None, user=None, identity=None)
Initialize git submodules
.INDENT 7.0
.TP
.B cwd
The path to the Git repository
.TP
.B init
True
Ensure that new submodules are initialized
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run git as a user other than what the minion runs as
.TP
.B identity
None
A path to a private key to use over SSH
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq git.submodule /path/to/repo.git/sub/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.glance
.sp
Module for handling openstack glance calls.
.INDENT 0.0
.TP
.B optdepends
.INDENT 7.0
.IP \(bu 2
glanceclient Python adapter
.UNINDENT
.TP
.B configuration
This module is not usable until the following are specified
either in a pillar or in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.insecure: False #(optional)
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If configuration for multiple openstack accounts is required, they can be
set up as different configuration profiles:
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
openstack1:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
openstack2:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this configuration in place, any of the keystone functions can make use
of a configuration profile by declaring it explicitly.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glance.image_list profile=openstack1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glance.image_create(profile=None, **kwargs)
Create an image (glance image\-create)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glance.image_create name=f16\-jeos is_public=true \e
disk_format=qcow2 container_format=ovf \e
copy_from=http://berrange.fedorapeople.org/images/2012\-02\-29/f16\-x86_64\-openstack\-sda.qcow2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For all possible values, run \fBglance help image\-create\fP on the minion.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glance.image_delete(id=None, name=None, profile=None)
Delete an image (glance image\-delete)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glance.image_delete c2eb2eb0\-53e1\-4a80\-b990\-8ec887eae7df
salt \(aq*\(aq glance.image_delete id=c2eb2eb0\-53e1\-4a80\-b990\-8ec887eae7df
salt \(aq*\(aq glance.image_delete name=f16\-jeos
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glance.image_list(id=None, profile=None)
Return a list of available images (glance image\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glance.image_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glance.image_show(id=None, name=None, profile=None)
Return details about a specific image (glance image\-show)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glance.image_get
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.glusterfs
.sp
Manage a glusterfs pool
.INDENT 0.0
.TP
.B salt.modules.glusterfs.create(name, bricks, stripe=False, replica=False, device_vg=False, transport=\(aqtcp\(aq, start=False)
Create a glusterfs volume.
.INDENT 7.0
.TP
.B name
Name of the gluster volume
.TP
.B bricks
Bricks to create volume from, in <peer>:<brick path> format. For multiple bricks use list format: \(aq["<peer1>:<brick1>", "<peer2>:<brick2>"]\(aq
.TP
.B stripe
Stripe count, the number of bricks should be a multiple of the stripe count for a distributed striped volume
.TP
.B replica
Replica count, the number of bricks should be a multiple of the replica count for a distributed replicated volume
.TP
.B device_vg
If true, specifies volume should use block backend instead of regular posix backend. Block device backend volume does not support multiple bricks
.TP
.B transport
Transport protocol to use, can be \(aqtcp\(aq, \(aqrdma\(aq or \(aqtcp,rdma\(aq
.TP
.B start
Start the volume after creation
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt host1 glusterfs.create newvolume host1:/brick
salt gluster1 glusterfs.create vol2 \(aq["gluster1:/export/vol2/brick", "gluster2:/export/vol2/brick"]\(aq replica=2 start=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.delete(target, stop=True)
Deletes a gluster volume
.INDENT 7.0
.TP
.B target
Volume to delete
.TP
.B stop
Stop volume before delete if it is started, True by default
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.list_peers()
Return a list of gluster peers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glusterfs.list_peers
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.list_volumes()
List configured volumes
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glusterfs.list_volumes
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.peer(name)
Add another node into the peer list.
.INDENT 7.0
.TP
.B name
The remote host to probe.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqone.gluster.*\(aq glusterfs.peer two
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.start_volume(name)
Start a gluster volume.
.INDENT 7.0
.TP
.B name
Volume name
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glusterfs.start mycluster
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.status(name)
Check the status of a gluster volume.
.INDENT 7.0
.TP
.B name
Volume name
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glusterfs.status myvolume
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.stop_volume(name)
Stop a gluster volume.
.INDENT 7.0
.TP
.B name
Volume name
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq glusterfs.stop_volume mycluster
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.gnomedesktop
.sp
GNOME implementations
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.get(schema=None, key=None, user=None, **kwargs)
Get key in a particular GNOME schema
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.get user=<username> schema=org.gnome.desktop.screensaver key=idle\-activation\-enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.getClockFormat(**kwargs)
Return the current clock format, either 12h or 24h format.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.getClockFormat user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.getClockShowDate(**kwargs)
Return the current setting, if the date is shown in the clock
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.getClockShowDate user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.getIdleActivation(**kwargs)
Get whether the idle activation is enabled
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.getIdleActivation user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.getIdleDelay(**kwargs)
Return the current idle delay setting in seconds
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.getIdleDelay user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.ping(**kwargs)
A test to ensure the GNOME module is loaded
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.ping user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.setClockFormat(clockFormat, **kwargs)
Set the clock format, either 12h or 24h format.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.setClockFormat <12h|24h> user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.setClockShowDate(kvalue, **kwargs)
Set whether the date is visible in the clock
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.setClockShowDate <True|False> user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.setIdleActivation(kvalue, **kwargs)
Set whether the idle activation is enabled
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.setIdleActivation <True|False> user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.setIdleDelay(delaySeconds, **kwargs)
Set the current idle delay setting in seconds
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.setIdleDelay <seconds> user=<username>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.gnomedesktop.set_(schema=None, key=None, user=None, value=None, **kwargs)
Set key in a particular GNOME schema
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq gnome.set user=<username> schema=org.gnome.desktop.screensaver key=idle\-activation\-enabled value=False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.grains
.sp
Return/control aspects of the grains data
.INDENT 0.0
.TP
.B salt.modules.grains.append(key, val, convert=False)
New in version 0.17.0.
.sp
Append a value to a list in the grains config file. If the grain doesn\(aqt
exist, the grain key is added and the value is appended to the new grain
as a list item.
.INDENT 7.0
.TP
.B key
The grain key to be appended to
.TP
.B val
The value to append to the grain key
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBconvert\fP \-\- If convert is True, convert non\-list contents into a list.
If convert is False and the grain contains non\-list contents, an error
is given. Defaults to False.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.append key val
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.delval(key, destructive=False)
New in version 0.17.0.
.sp
Delete a grain from the grains config file
.INDENT 7.0
.TP
.B Parameters
\fBdestructive\fP \-\- Delete the key, too. Defaults to False.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.delval key
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.filter_by(lookup_dict, grain=\(aqos_family\(aq, merge=None, default=\(aqdefault\(aq)
New in version 0.17.0.
.sp
Look up the given grain in a given dictionary for the current OS and return
the result
.sp
Although this may occasionally be useful at the CLI, the primary intent of
this function is for use in Jinja to make short work of creating lookup
tables for OS\-specific data. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% set apache = salt[\(aqgrains.filter_by\(aq]({
\(aqDebian\(aq: {\(aqpkg\(aq: \(aqapache2\(aq, \(aqsrv\(aq: \(aqapache2\(aq},
\(aqRedHat\(aq: {\(aqpkg\(aq: \(aqhttpd\(aq, \(aqsrv\(aq: \(aqhttpd\(aq},
}), default=\(aqDebian\(aq %}
myapache:
pkg.installed:
\- name: {{ apache.pkg }}
service.running:
\- name: {{ apache.srv }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Values in the lookup table may be overridden by values in Pillar. An
example Pillar to override values in the example above could be as follows:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
lookup:
pkg: apache_13
srv: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The call to \fBfilter_by()\fP would be modified as follows to reference those
Pillar values:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% set apache = salt[\(aqgrains.filter_by\(aq]({
...
}, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBlookup_dict\fP \-\- A dictionary, keyed by a grain, containing a value or
values relevant to systems matching that grain. For example, a key
could be the grain for an OS and the value could the name of a package
on that particular OS.
.IP \(bu 2
\fBgrain\fP \-\- The name of a grain to match with the current system\(aqs
grains. For example, the value of the "os_family" grain for the current
system could be used to pull values from the \fBlookup_dict\fP
dictionary.
.IP \(bu 2
\fBmerge\fP \-\- A dictionary to merge with the \fBlookup_dict\fP before doing
the lookup. This allows Pillar to override the values in the
\fBlookup_dict\fP\&. This could be useful, for example, to override the
values for non\-standard package names such as when using a different
Python version from the default Python version provided by the OS
(e.g., \fBpython26\-mysql\fP instead of \fBpython\-mysql\fP).
.IP \(bu 2
\fBdefault\fP \-\-
.sp
default lookup_dict\(aqs key used if the grain does not exists
or if the grain value has no match on lookup_dict.
.sp
New in version 2014.1.0.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.filter_by \(aq{Debian: Debheads rule, RedHat: I love my hat}\(aq
# this one will render {D: {E: I, G: H}, J: K}
salt \(aq*\(aq grains.filter_by \(aq{A: B, C: {D: {E: F,G: H}}}\(aq \(aqxxx\(aq \(aq{D: {E: I},J: K}\(aq \(aqC\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.get(key, default=\(aq\(aq, delimiter=\(aq:\(aq)
Attempt to retrieve the named value from grains, if the named value is not
available return the passed default. The default return is an empty string.
.sp
The value can also represent a value in a nested dict using a ":" delimiter
for the dict. This means that if a dict in grains looks like this:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To retrieve the value associated with the apache key in the pkg dict this
key can be passed:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B delimiter
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.get pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.get_or_set_hash(name, length=8, chars=\(aqabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(\-_=+)\(aq)
Perform a one\-time generation of a hash and write it to the local grains.
If that grain has already been set return the value instead.
.sp
This is useful for generating passwords or keys that are specific to a
single minion that don\(aqt need to be stored somewhere centrally.
.sp
State Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
some_mysql_user:
mysql_user:
\- present
\- host: localhost
\- password: {{ salt[\(aqgrains.get_or_set_hash\(aq](\(aqmysql:some_mysql_user\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.get_or_set_hash \(aqdjango:SECRET_KEY\(aq 50
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.has_value(key)
Determine whether a named value exists in the grains dictionary.
.sp
Given a grains dictionary that contains the following structure:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
One would determine if the apache key in the pkg dict exists by:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.has_value pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.item(*args, **kwargs)
Return one or more grains
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.item os
salt \(aq*\(aq grains.item os osrelease oscodename
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Sanitized CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.item host sanitize=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.items(sanitize=False)
Return all of the minion\(aqs grains
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.items
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Sanitized CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.items sanitize=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.ls()
Return a list of all available grains
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.ls
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.remove(key, val)
New in version 0.17.0.
.sp
Remove a value from a list in the grains config file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.remove key val
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.setval(key, val, destructive=False)
Set a grains value in the grains config file
.INDENT 7.0
.TP
.B Parameters
\fBDestructive\fP \-\- If an operation results in a key being removed, delete the key, too. Defaults to False.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.setval key val
salt \(aq*\(aq grains.setval key "{\(aqsub\-key\(aq: \(aqval\(aq, \(aqsub\-key2\(aq: \(aqval2\(aq}"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grains.setvals(grains, destructive=False)
Set new grains values in the grains config file
.INDENT 7.0
.TP
.B Parameters
\fBDestructive\fP \-\- If an operation results in a key being removed, delete the key, too. Defaults to False.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grains.setvals "{\(aqkey1\(aq: \(aqval1\(aq, \(aqkey2\(aq: \(aqval2\(aq}"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.groupadd
.sp
Manage groups on Linux and OpenBSD
.INDENT 0.0
.TP
.B salt.modules.groupadd.add(name, gid=None, system=False)
Add the specified group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.add foo 3456
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.adduser(name, username)
Add a user in the group.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.adduser foo bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Verifies if a valid username \(aqbar\(aq as a member of an existing group \(aqfoo\(aq,
if not then adds it.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.chgid(name, gid)
Change the gid for a named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.delete(name)
Remove the named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.delete foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.deluser(name, username)
Remove a user from the group.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.deluser foo bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Removes a member user \(aqbar\(aq from a group \(aqfoo\(aq. If group is not present
then returns True.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.getent(refresh=False)
Return info on all groups
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.info(name)
Return information about a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.info foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.groupadd.members(name, members_list)
Replaces members of the group with a provided list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Replaces a membership list for a local group \(aqfoo\(aq.
foo:x:1234:user1,user2,user3,...
.UNINDENT
.UNINDENT
.SS salt.modules.grub_legacy
.sp
Support for GRUB Legacy
.INDENT 0.0
.TP
.B salt.modules.grub_legacy.conf()
Parse GRUB conf file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grub.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.grub_legacy.version()
Return server version from grub \-\-version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq grub.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.guestfs
.sp
Interact with virtual machine images via libguestfs
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
libguestfs
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.guestfs.mount(location, access=\(aqrw\(aq)
Mount an image
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq guest.mount /srv/images/fedora.qcow
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.hadoop
.sp
Support for hadoop
.INDENT 0.0
.TP
.B maintainer
Yann Jouanin <\fI\%yann.jouanin@intelunix.fr\fP>
.TP
.B maturity
new
.TP
.B depends
.TP
.B platform
linux
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hadoop.dfs(command=None, *args)
Execute a command on DFS
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hadoop.dfs ls /
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hadoop.dfs_absent(path)
Check if a file or directory is absent on the distributed FS.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hadoop.dfs_absent /some_random_file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns True if the file is absent
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hadoop.dfs_present(path)
Check if a file or directory is present on the distributed FS.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hadoop.dfs_present /some_random_file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns True if the file is present
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hadoop.namenode_format(force=None)
Format a name node
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hadoop.namenode_format force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hadoop.version()
Return version from hadoop version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hadoop.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.haproxyconn
.sp
Support for haproxy
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.disable_server(name, backend, socket=\(aq/var/run/haproxy.sock\(aq)
Disable server in haproxy.
.INDENT 7.0
.TP
.B name
Server to disable
.TP
.B backend
haproxy backend
.TP
.B socket
haproxy stats socket
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq haproxy.disable_server db1.example.com mysql
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.enable_server(name, backend, socket=\(aq/var/run/haproxy.sock\(aq)
Enable Server in haproxy
.INDENT 7.0
.TP
.B name
Server to enable
.TP
.B backend
haproxy backend
.TP
.B socket
haproxy stats socket
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq haproxy.enable_server web1.example.com www
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.get_weight(name, backend, socket=\(aq/var/run/haproxy.sock\(aq)
Get server weight
.INDENT 7.0
.TP
.B name
Server name
.TP
.B backend
haproxy backend
.TP
.B socket
haproxy stats socket
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq haproxy.get_weight web1.example.com www
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.list_servers(backend, socket=\(aq/var/run/haproxy.sock\(aq)
List servers in haproxy backend.
.INDENT 7.0
.TP
.B backend
haproxy backend
.TP
.B socket
haproxy stats socket
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq haproxy.list_servers mysql
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.set_weight(name, backend, weight=0, socket=\(aq/var/run/haproxy.sock\(aq)
Set server weight
.INDENT 7.0
.TP
.B name
Server name
.TP
.B backend
haproxy backend
.TP
.B weight
Server Weight
.TP
.B socket
haproxy stats socket
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq haproxy.set_weight web1.example.com www 13
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.show_backends(socket=\(aq/var/run/haproxy.sock\(aq)
Show HaProxy Backends
.INDENT 7.0
.TP
.B socket
haproxy stats socket
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq haproxy.show_backends
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.show_frontends(socket=\(aq/var/run/haproxy.sock\(aq)
Show HaProxy frontends
.INDENT 7.0
.TP
.B socket
haproxy stats socket
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq haproxy.show_frontends
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.hashutil
.sp
A collection of hashing and encoding functions
.INDENT 0.0
.TP
.B salt.modules.hashutil.base64_decodestring(instr)
.INDENT 7.0
.INDENT 3.5
Decode a base64\-encoded string
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hashutil.base64_decodestring \(aqZ2V0IHNhbHRlZA==
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\(aq
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hashutil.base64_encodestring(instr)
Encode a string as base64
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hashutil.base64_encodestring \(aqget salted\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hashutil.hmac_signature(string, shared_secret, challenge_hmac)
Verify a challenging hmac signature against a string / shared\-secret
.sp
New in version 2014.7.0.
.sp
Returns a boolean if the verification succeeded or failed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hashutil.hmac_signature \(aqget salted\(aq \(aqshared secret\(aq \(aqNS2BvKxFRk+rndAlFbCYIFNVkPtI/3KiIYQw4okNKU8=\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hashutil.md5_digest(instr)
Generate an md5 hash of a given string
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hashutil.md5_digest \(aqget salted\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hashutil.sha256_digest(instr)
Generate an sha256 hash of a given string
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hashutil.sha256_digest \(aqget salted\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hashutil.sha512_digest(instr)
Generate an sha512 hash of a given string
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hashutil.sha512_digest \(aqget salted\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.hg
.sp
Support for the Mercurial SCM
.INDENT 0.0
.TP
.B salt.modules.hg.archive(cwd, output, rev=\(aqtip\(aq, fmt=None, prefix=None, user=None)
Export a tarball from the repository
.INDENT 7.0
.TP
.B cwd
The path to the Mercurial repository
.TP
.B output
The path to the archive tarball
.TP
.B rev: tip
The revision to create an archive from
.TP
.B fmt: None
Format of the resulting archive. Mercurial supports: tar,
tbz2, tgz, zip, uzip, and files formats.
.TP
.B prefix
None
Prepend <prefix>/ to every filename in the archive
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.sp
If \fBprefix\fP is not specified it defaults to the basename of the repo
directory.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hg.archive /path/to/repo output=/tmp/archive.tgz fmt=tgz
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hg.clone(cwd, repository, opts=None, user=None)
Clone a new repository
.INDENT 7.0
.TP
.B cwd
The path to the Mercurial repository
.TP
.B repository
The hg URI of the repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hg.clone /path/to/repo https://bitbucket.org/birkenfeld/sphinx
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hg.describe(cwd, rev=\(aqtip\(aq, user=None)
Mimic git describe and return an identifier for the given revision
.INDENT 7.0
.TP
.B cwd
The path to the Mercurial repository
.TP
.B rev: tip
The path to the archive tarball
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hg.describe /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hg.pull(cwd, opts=None, user=None)
Perform a pull on the given repository
.INDENT 7.0
.TP
.B cwd
The path to the Mercurial repository
.TP
.B opts
None
Any additional options to add to the command line
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hg.pull /path/to/repo opts=\-u
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hg.revision(cwd, rev=\(aqtip\(aq, short=False, user=None)
Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc)
.INDENT 7.0
.TP
.B cwd
The path to the Mercurial repository
.TP
.B rev: tip
The revision
.TP
.B short: False
Return an abbreviated commit hash
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hg.revision /path/to/repo mybranch
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hg.update(cwd, rev, force=False, user=None)
Update to a given revision
.INDENT 7.0
.TP
.B cwd
The path to the Mercurial repository
.TP
.B rev
The revision to update to
.TP
.B force
False
Force an update
.TP
.B user
None
Run hg as a user other than what the minion runs as
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt devserver1 hg.update /path/to/repo somebranch
.ft P
.fi
.UNINDENT
.UNINDENT
.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
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hosts.add_host <ip> <alias>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.get_alias(ip)
Return the list of aliases associated with an ip
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hosts.get_alias <ip addr>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.get_ip(host)
Return the ip associated with the named host
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hosts.get_ip <hostname>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.has_pair(ip, alias)
Return true if the alias is set
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hosts.has_pair <ip> <alias>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.list_hosts()
Return the hosts found in the hosts file in this format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<ip addr>\(aq: [\(aqalias1\(aq, \(aqalias2\(aq, ...]}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hosts.list_hosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.hosts.rm_host(ip, alias)
Remove a host entry from the hosts file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hosts.rm_host <ip> <alias>
.ft P
.fi
.UNINDENT
.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
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq hosts.set_host <ip> <alias>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.htpasswd
.sp
Support for htpasswd command
.sp
New in version 2014.1.0.
.sp
The functions here will load inside the webutil module. This allows other
functions that don\(aqt use htpasswd to use the webutil module name.
.INDENT 0.0
.TP
.B salt.modules.htpasswd.useradd(pwfile, user, password, opts=\(aq\(aq)
Add an HTTP user using the htpasswd command. If the htpasswd file does not
exist, it will be created. Valid options that can be passed are:
.INDENT 7.0
.INDENT 3.5
n Don\(aqt update file; display results on stdout.
m Force MD5 encryption of the password (default).
d Force CRYPT encryption of the password.
p Do not encrypt the password (plaintext).
s Force SHA encryption of the password.
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq webutil.useradd /etc/httpd/htpasswd larry badpassword
salt \(aq*\(aq webutil.useradd /etc/httpd/htpasswd larry badpass opts=ns
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.htpasswd.useradd_all(pwfile, user, password, opts=\(aq\(aq)
Add an HTTP user using the htpasswd command. If the htpasswd file does not
exist, it will be created. Valid options that can be passed are:
.INDENT 7.0
.INDENT 3.5
n Don\(aqt update file; display results on stdout.
m Force MD5 encryption of the password (default).
d Force CRYPT encryption of the password.
p Do not encrypt the password (plaintext).
s Force SHA encryption of the password.
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq webutil.useradd /etc/httpd/htpasswd larry badpassword
salt \(aq*\(aq webutil.useradd /etc/httpd/htpasswd larry badpass opts=ns
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.htpasswd.userdel(pwfile, user)
Delete an HTTP user from the specified htpasswd file.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq webutil.userdel /etc/httpd/htpasswd larry
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.img
.sp
Virtual machine image management tools
.INDENT 0.0
.TP
.B salt.modules.img.bootstrap(location, size, fmt)
HIGHLY EXPERIMENTAL
Bootstrap a virtual machine image
.INDENT 7.0
.TP
.B location:
The location to create the image
.TP
.B size:
The size of the image to create in megabytes
.TP
.B fmt:
The image format, raw or qcow2
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq img.bootstrap /srv/salt\-images/host.qcow 4096 qcow2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.img.mount_image(location)
Mount the named image and return the mount point
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq img.mount_image /tmp/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.img.umount_image(mnt)
Unmount an image mountpoint
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq img.umount_image /mnt/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.incron
.sp
Work with incron
.INDENT 0.0
.TP
.B salt.modules.incron.list_tab(user)
Return the contents of the specified user\(aqs incrontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.list_tab root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.ls(user)
Return the contents of the specified user\(aqs incrontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.list_tab root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.raw_incron(user)
Return the contents of the user\(aqs incrontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.raw_cron root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.raw_system_incron()
Return the contents of the system wide incrontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.raw_system_cron
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.rm(user, path, mask, cmd)
Remove a cron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.rm_job root /path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.rm_job(user, path, mask, cmd)
Remove a cron job for a specified user. If any of the day/time params are
specified, the job will only be removed if the specified params match.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.rm_job root /path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.set_job(user, path, mask, cmd)
Sets a cron job up for a specified user.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.set_job root \(aq/root\(aq \(aqIN_MODIFY\(aq \(aqecho "$$ $@ $# $% $&"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.write_cron_file_verbose(user, path)
Writes the contents of a file to a user\(aqs crontab and return error message on error
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.write_incron_file_verbose root /tmp/new_cron
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.incron.write_incron_file(user, path)
Writes the contents of a file to a user\(aqs crontab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq incron.write_cron_file root /tmp/new_cron
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.influx
.sp
InfluxDB \- A distributed time series database
.sp
Module to provide InfluxDB compatibility to Salt
(compatible with InfluxDB version 0.5+)
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
influxdb Python module
.UNINDENT
.TP
.B configuration
This module accepts connection configuration details either as
parameters or as configuration settings in /etc/salt/minion on the relevant
minions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
influxdb.host: \(aqlocalhost\(aq
influxdb.port: 8086
influxdb.user: \(aqroot\(aq
influxdb.password: \(aqroot\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This data can also be passed into pillar. Options passed into opts will
overwrite options passed into pillar.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.db_create(name, user=None, password=None, host=None, port=None)
Create a database
.INDENT 7.0
.TP
.B name
Database name to create
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.db_create <name>
salt \(aq*\(aq influxdb.db_create <name> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.db_exists(name, user=None, password=None, host=None, port=None)
Checks if a database exists in InfluxDB
.INDENT 7.0
.TP
.B name
Database name to create
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.db_exists <name>
salt \(aq*\(aq influxdb.db_exists <name> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.db_list(user=None, password=None, host=None, port=None)
List all InfluxDB databases
.INDENT 7.0
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.db_list
salt \(aq*\(aq influxdb.db_list <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.db_remove(name, user=None, password=None, host=None, port=None)
Remove a database
.INDENT 7.0
.TP
.B name
Database name to remove
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.db_remove <name>
salt \(aq*\(aq influxdb.db_remove <name> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.query(database, query, time_precision=\(aqs\(aq, chunked=False, user=None, password=None, host=None, port=None)
Querying data
.INDENT 7.0
.TP
.B database
The database to query
.TP
.B query
Query to be executed
.TP
.B time_precision
Time precision to use (\(aqs\(aq, \(aqm\(aq, or \(aqu\(aq)
.TP
.B chunked
Whether is chunked or not
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.query <database> <query>
salt \(aq*\(aq influxdb.query <database> <query> <time_precision> <chunked> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.user_chpass(name, passwd, database=None, user=None, password=None, host=None, port=None)
Change password for a cluster admin or a database user.
.sp
If a database is specified: it will update database user password.
If a database is not specified: it will update cluster admin password.
.INDENT 7.0
.TP
.B name
User name for whom to change the password
.TP
.B passwd
New password
.TP
.B database
The database on which to operate
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.user_chpass <name> <passwd>
salt \(aq*\(aq influxdb.user_chpass <name> <passwd> <database>
salt \(aq*\(aq influxdb.user_chpass <name> <passwd> <database> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.user_create(name, passwd, database=None, user=None, password=None, host=None, port=None)
Create a cluster admin or a database user.
.sp
If a database is specified: it will create database user.
If a database is not specified: it will create a cluster admin.
.INDENT 7.0
.TP
.B name
User name for the new user to create
.TP
.B passwd
Password for the new user to create
.TP
.B database
The database to create the user in
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.user_create <name> <passwd>
salt \(aq*\(aq influxdb.user_create <name> <passwd> <database>
salt \(aq*\(aq influxdb.user_create <name> <passwd> <database> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.user_exists(name, database=None, user=None, password=None, host=None, port=None)
Checks if a cluster admin or database user exists.
.sp
If a database is specified: it will check for database user existence.
If a database is not specified: it will check for cluster admin existence.
.INDENT 7.0
.TP
.B name
User name
.TP
.B database
The database to check for the user to exist
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.user_exists <name>
salt \(aq*\(aq influxdb.user_exists <name> <database>
salt \(aq*\(aq influxdb.user_exists <name> <database> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.user_list(database=None, user=None, password=None, host=None, port=None)
List cluster admins or database users.
.sp
If a database is specified: it will return database users list.
If a database is not specified: it will return cluster admins list.
.INDENT 7.0
.TP
.B database
The database to list the users from
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.user_list
salt \(aq*\(aq influxdb.user_list <database>
salt \(aq*\(aq influxdb.user_list <database> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.influx.user_remove(name, database=None, user=None, password=None, host=None, port=None)
Remove a cluster admin or a database user.
.sp
If a database is specified: it will remove the database user.
If a database is not specified: it will remove the cluster admin.
.INDENT 7.0
.TP
.B name
User name to remove
.TP
.B database
The database to remove the user from
.TP
.B user
User name for the new user to delete
.TP
.B user
The user to connect as
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq influxdb.user_remove <name>
salt \(aq*\(aq influxdb.user_remove <name> <database>
salt \(aq*\(aq influxdb.user_remove <name> <database> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.ini_manage
.sp
Edit ini files
.INDENT 0.0
.TP
.B maintainer
<\fI\%akilesh1597@gmail.com\fP>
.TP
.B maturity
new
.TP
.B depends
re
.TP
.B platform
all
.UNINDENT
.sp
Use section as DEFAULT_IMPLICIT if your ini file does not have any section
(for example /etc/sysctl.conf)
.INDENT 0.0
.TP
.B salt.modules.ini_manage.get_option(file_name, section, option)
Get value of a key from a section in an ini file. Returns \fBNone\fP if
no matching key was found.
.sp
API Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt
sc = salt.client.get_local_client()
sc.cmd(\(aqtarget\(aq, \(aqini.get_option\(aq,
[path_to_ini_file, section_name, option])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ini.get_option /path/to/ini section_name option_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ini_manage.get_section(file_name, section)
Retrieve a section from an ini file. Returns the section as dictionary. If
the section is not found, an empty dictionary is returned.
.sp
API Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt
sc = salt.client.get_local_client()
sc.cmd(\(aqtarget\(aq, \(aqini.get_section\(aq,
[path_to_ini_file, section_name])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ini.get_section /path/to/ini section_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ini_manage.remove_option(file_name, section, option)
Remove a key/value pair from a section in an ini file. Returns the value of
the removed key, or \fBNone\fP if nothing was removed.
.sp
API Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt
sc = salt.client.get_local_client()
sc.cmd(\(aqtarget\(aq, \(aqini.remove_option\(aq,
[path_to_ini_file, section_name, option])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ini.remove_option /path/to/ini section_name option_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ini_manage.remove_section(file_name, section)
Remove a section in an ini file. Returns the removed section as dictionary,
or \fBNone\fP if nothing was removed.
.sp
API Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt
sc = salt.client.get_local_client()
sc.cmd(\(aqtarget\(aq, \(aqini.remove_section\(aq,
[path_to_ini_file, section_name])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ini.remove_section /path/to/ini section_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ini_manage.set_option(file_name, sections=None, summary=True)
Edit an ini file, replacing one or more sections. Returns a dictionary
containing the changes made.
.INDENT 7.0
.TP
.B file_name
path of ini_file
.TP
.B sections
None
A dictionary representing the sections to be edited ini file
.UNINDENT
.sp
Set \fBsummary=False\fP if return data need not have previous option value
.sp
API Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt
sc = salt.client.get_local_client()
sc.cmd(\(aqtarget\(aq, \(aqini.set_option\(aq,
[\(aqpath_to_ini_file\(aq, \(aq{"section_to_change": {"key": "value"}}\(aq])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ini.set_option /path/to/ini \(aq{section_foo: {key: value}}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.introspect
.sp
Functions to perform introspection on a minion, and return data in a format
usable by Salt States
.INDENT 0.0
.TP
.B salt.modules.introspect.enabled_service_owners()
Return which packages own each of the services that are currently enabled.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt myminion introspect.enabled_service_owners
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.introspect.running_service_owners(exclude=(\(aq/dev\(aq, \(aq/home\(aq, \(aq/media\(aq, \(aq/proc\(aq, \(aq/run\(aq, \(aq/sys/\(aq, \(aq/tmp\(aq, \(aq/var\(aq))
Determine which packages own the currently running services. By default,
excludes files whose full path starts with \fB/dev\fP, \fB/home\fP, \fB/media\fP,
\fB/proc\fP, \fB/run\fP, \fB/sys\fP, \fB/tmp\fP and \fB/var\fP\&. This can be
overridden by passing in a new list to \fBexclude\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt myminion introspect.running_service_owners
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.introspect.service_highstate(requires=True)
Return running and enabled services in a highstate structure. By default
also returns package dependencies for those services, which means that
package definitions must be created outside this function. To drop the
package dependencies, set \fBrequires\fP to False.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt myminion introspect.service_highstate
salt myminion introspect.service_highstate requires=False
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.ipset
.sp
Support for ipset
.INDENT 0.0
.TP
.B salt.modules.ipset.add(set=None, entry=None, family=\(aqipv4\(aq, **kwargs)
Append an entry to the specified set.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.add setname 192.168.1.26
salt \(aq*\(aq ipset.add setname 192.168.0.3,AA:BB:CC:DD:EE:FF
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.check(set=None, entry=None, family=\(aqipv4\(aq)
Check that an entry exists in the specified set.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.check setname \(aq192.168.0.1 comment "Hello"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.check_set(set=None, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Check that given ipset set exists.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.check_set setname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.delete(set=None, entry=None, family=\(aqipv4\(aq, **kwargs)
Delete an entry from the specified set.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.delete setname 192.168.0.3,AA:BB:CC:DD:EE:FF
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.delete_set(set=None, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Delete ipset set.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.delete_set custom_set
IPv6:
salt \(aq*\(aq ipset.delete_set custom_set family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.flush(set=None, family=\(aqipv4\(aq)
Flush entries in the specified set,
Flush all sets if set is not specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.flush
salt \(aq*\(aq ipset.flush set
IPv6:
salt \(aq*\(aq ipset.flush
salt \(aq*\(aq ipset.flush set
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.list_sets(family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
List all ipset sets.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.list_sets
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.new_set(set=None, set_type=None, family=\(aqipv4\(aq, comment=False, **kwargs)
New in version 2014.7.0.
.sp
Create new custom set
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.new_set custom_set list:set
salt \(aq*\(aq ipset.new_set custom_set list:set comment=True
IPv6:
salt \(aq*\(aq ipset.new_set custom_set list:set family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.rename_set(set=None, new_set=None, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Delete ipset set.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.rename_set custom_set new_set=new_set_name
IPv6:
salt \(aq*\(aq ipset.rename_set custom_set new_set=new_set_name family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.test(set=None, entry=None, family=\(aqipv4\(aq, **kwargs)
Test if an entry is in the specified set.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.test setname 192.168.0.2
IPv6:
salt \(aq*\(aq ipset.test setname fd81:fc56:9ac7::/48
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ipset.version()
Return version from ipset \-\-version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ipset.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.iptables
.sp
Support for iptables
.INDENT 0.0
.TP
.B salt.modules.iptables.append(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq)
Append a rule to the specified table/chain.
.INDENT 7.0
.TP
.B This function accepts a rule in a standard iptables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.append filter INPUT \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq
IPv6:
salt \(aq*\(aq iptables.append filter INPUT \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.build_rule(table=None, chain=None, command=None, position=\(aq\(aq, full=None, family=\(aqipv4\(aq, **kwargs)
Build a well\-formatted iptables rule based on kwargs. Long options must be
used (\fI\-\-jump\fP instead of \fI\-j\fP) because they will have the \fI\-\-\fP added to
them. A \fItable\fP and \fIchain\fP are not required, unless \fIfull\fP is True.
.sp
If \fIfull\fP is \fITrue\fP, then \fItable\fP, \fIchain\fP and \fIcommand\fP are required.
\fIcommand\fP may be specified as either a short option (\(aqI\(aq) or a long option
(\fI\-\-insert\fP). This will return the iptables command, exactly as it would
be used from the command line.
.sp
If a position is required (as with \fI\-I\fP or \fI\-D\fP), it may be specified as
\fIposition\fP\&. This will only be useful if \fIfull\fP is True.
.sp
If \fIconnstate\fP is passed in, it will automatically be changed to \fIstate\fP\&.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.build_rule match=state \e
connstate=RELATED,ESTABLISHED jump=ACCEPT
salt \(aq*\(aq iptables.build_rule filter INPUT command=I position=3 \e
full=True match=state state=RELATED,ESTABLISHED jump=ACCEPT
salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e
full=True match=state state=RELATED,ESTABLISHED \e
source=\(aq127.0.0.1\(aq jump=ACCEPT
\&.. Invert Rules
salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e
full=True match=state state=RELATED,ESTABLISHED \e
source=\(aq! 127.0.0.1\(aq jump=ACCEPT
salt \(aq*\(aq iptables.build_rule filter INPUT command=A \e
full=True match=state state=RELATED,ESTABLISHED \e
destination=\(aqnot 127.0.0.1\(aq jump=ACCEPT
IPv6:
salt \(aq*\(aq iptables.build_rule match=state \e
connstate=RELATED,ESTABLISHED jump=ACCEPT \e
family=ipv6
salt \(aq*\(aq iptables.build_rule filter INPUT command=I position=3 \e
full=True match=state state=RELATED,ESTABLISHED jump=ACCEPT \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.check(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq)
Check for the existence of a rule in the table and chain
.INDENT 7.0
.TP
.B This function accepts a rule in a standard iptables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.check filter INPUT \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq
IPv6:
salt \(aq*\(aq iptables.check filter INPUT \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.check_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq)
New in version 2014.1.0.
.sp
Check for the existence of a chain in the table
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.check_chain filter INPUT
IPv6:
salt \(aq*\(aq iptables.check_chain filter INPUT family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.delete(table, chain=None, position=None, rule=None, family=\(aqipv4\(aq)
.INDENT 7.0
.TP
.B Delete a rule from the specified table/chain, specifying either the rule
in its entirety, or the rule\(aqs position in the chain.
.TP
.B This function accepts a rule in a standard iptables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.delete filter INPUT position=3
salt \(aq*\(aq iptables.delete filter INPUT \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq
IPv6:
salt \(aq*\(aq iptables.delete filter INPUT position=3 family=ipv6
salt \(aq*\(aq iptables.delete filter INPUT \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.delete_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq)
New in version 2014.1.0.
.sp
Delete custom chain to the specified table.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.delete_chain filter CUSTOM_CHAIN
IPv6:
salt \(aq*\(aq iptables.delete_chain filter CUSTOM_CHAIN family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.flush(table=\(aqfilter\(aq, chain=\(aq\(aq, family=\(aqipv4\(aq)
Flush the chain in the specified table, flush all chains in the specified
table if not specified chain.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.flush filter INPUT
IPv6:
salt \(aq*\(aq iptables.flush filter INPUT family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.get_policy(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq)
Return the current policy for the specified table/chain
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.get_policy filter INPUT
IPv6:
salt \(aq*\(aq iptables.get_policy filter INPUT family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.get_rules(family=\(aqipv4\(aq)
Return a data structure of the current, in\-memory rules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.get_rules
IPv6:
salt \(aq*\(aq iptables.get_rules family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.get_saved_policy(table=\(aqfilter\(aq, chain=None, conf_file=None, family=\(aqipv4\(aq)
Return the current policy for the specified table/chain
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.get_saved_policy filter INPUT
salt \(aq*\(aq iptables.get_saved_policy filter INPUT \e
conf_file=/etc/iptables.saved
IPv6:
salt \(aq*\(aq iptables.get_saved_policy filter INPUT family=ipv6
salt \(aq*\(aq iptables.get_saved_policy filter INPUT \e
conf_file=/etc/iptables.saved family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.get_saved_rules(conf_file=None, family=\(aqipv4\(aq)
Return a data structure of the rules in the conf file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.get_saved_rules
IPv6:
salt \(aq*\(aq iptables.get_saved_rules family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.insert(table=\(aqfilter\(aq, chain=None, position=None, rule=None, family=\(aqipv4\(aq)
Insert a rule into the specified table/chain, at the specified position.
.INDENT 7.0
.TP
.B This function accepts a rule in a standard iptables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.TP
.B If the position specified is a negative number, then the insert will be
performed counting from the end of the list. For instance, a position
of \-1 will insert the rule as the second to last rule. To insert a rule
in the last position, use the append function instead.
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.insert filter INPUT position=3 \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq
IPv6:
salt \(aq*\(aq iptables.insert filter INPUT position=3 \e
rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.new_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq)
New in version 2014.1.0.
.sp
Create new custom chain to the specified table.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.new_chain filter CUSTOM_CHAIN
IPv6:
salt \(aq*\(aq iptables.new_chain filter CUSTOM_CHAIN family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.save(filename=None, family=\(aqipv4\(aq)
Save the current in\-memory rules to disk
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.save /etc/sysconfig/iptables
IPv6:
salt \(aq*\(aq iptables.save /etc/sysconfig/iptables family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.set_policy(table=\(aqfilter\(aq, chain=None, policy=None, family=\(aqipv4\(aq)
Set the current policy for the specified table/chain
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.set_policy filter INPUT ACCEPT
IPv6:
salt \(aq*\(aq iptables.set_policy filter INPUT ACCEPT family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.iptables.version(family=\(aqipv4\(aq)
Return version from iptables \-\-version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq iptables.version
IPv6:
salt \(aq*\(aq iptables.version family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.junos
.sp
Module for interfacing to Junos devices
.sp
ALPHA QUALITY code.
.INDENT 0.0
.TP
.B salt.modules.junos.commit()
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.diff()
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.facts_refresh()
Reload the facts dictionary from the device. Usually only needed
if the device configuration is changed by some other actor.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.ping()
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.rollback()
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.set_hostname(hostname=None, commit_change=True)
.UNINDENT
.SS salt.modules.key
.sp
Functions to view the minion\(aqs public key information
.INDENT 0.0
.TP
.B salt.modules.key.finger()
Return the minion\(aqs public key fingerprint
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq key.finger
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.key.finger_master()
Return the fingerprint of the master\(aqs public key on the minion.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq key.finger_master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.keyboard
.sp
Module for managing keyboards on supported POSIX\-like systems using
systemd, or such as Redhat, Debian and Gentoo.
.INDENT 0.0
.TP
.B salt.modules.keyboard.get_sys()
Get current system keyboard setting
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keyboard.get_sys
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keyboard.get_x()
Get current X keyboard setting
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keyboard.get_x
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keyboard.set_sys(layout)
Set current system keyboard setting
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keyboard.set_sys dvorak
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keyboard.set_x(layout)
Set current X keyboard setting
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keyboard.set_x dvorak
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.keystone
.sp
Module for handling openstack keystone calls.
.INDENT 0.0
.TP
.B optdepends
.INDENT 7.0
.IP \(bu 2
keystoneclient Python adapter
.UNINDENT
.TP
.B configuration
This module is not usable until the following are specified
either in a pillar or in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
OR (for token based authentication)
keystone.token: \(aqADMIN\(aq
keystone.endpoint: \(aqhttp://127.0.0.1:35357/v2.0\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If configuration for multiple openstack accounts is required, they can be
set up as different configuration profiles:
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
openstack1:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
openstack2:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.tenant_id: f80919baedab48ec8931f200c65a50df
keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this configuration in place, any of the keystone functions can make use
of a configuration profile by declaring it explicitly.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.tenant_list profile=openstack1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.auth(profile=None, **connection_args)
Set up keystone credentials
.sp
Only intended to be used within Keystone\-enabled modules
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.ec2_credentials_create(user_id=None, name=None, tenant_id=None, tenant=None, profile=None, **connection_args)
Create EC2\-compatible credentials for user per tenant
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.ec2_credentials_create name=admin tenant=admin
salt \(aq*\(aq keystone.ec2_credentials_create user_id=c965f79c4f864eaaa9c3b41904e67082 tenant_id=722787eb540849158668370dc627ec5f
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.ec2_credentials_delete(user_id=None, name=None, access_key=None, profile=None, **connection_args)
Delete EC2\-compatible credentials
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.ec2_credentials_delete 860f8c2c38ca4fab989f9bc56a061a64
access_key=5f66d2f24f604b8bb9cd28886106f442
salt \(aq*\(aq keystone.ec2_credentials_delete name=admin access_key=5f66d2f24f604b8bb9cd28886106f442
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.ec2_credentials_get(user_id=None, name=None, access=None, profile=None, **connection_args)
Return ec2_credentials for a user (keystone ec2\-credentials\-get)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.ec2_credentials_get c965f79c4f864eaaa9c3b41904e67082 access=722787eb540849158668370dc627ec5f
salt \(aq*\(aq keystone.ec2_credentials_get user_id=c965f79c4f864eaaa9c3b41904e67082 access=722787eb540849158668370dc627ec5f
salt \(aq*\(aq keystone.ec2_credentials_get name=nova access=722787eb540849158668370dc627ec5f
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.ec2_credentials_list(user_id=None, name=None, profile=None, **connection_args)
Return a list of ec2_credentials for a specific user (keystone ec2\-credentials\-list)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.ec2_credentials_list 298ce377245c4ec9b70e1c639c89e654
salt \(aq*\(aq keystone.ec2_credentials_list user_id=298ce377245c4ec9b70e1c639c89e654
salt \(aq*\(aq keystone.ec2_credentials_list name=jack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.endpoint_create(service, publicurl=None, internalurl=None, adminurl=None, region=None, profile=None, **connection_args)
Create an endpoint for an Openstack service
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.endpoint_create nova \(aqhttp://public/url\(aq
\(aqhttp://internal/url\(aq \(aqhttp://adminurl/url\(aq region
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.endpoint_delete(service, profile=None, **connection_args)
Delete endpoints of an Openstack service
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.endpoint_delete nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.endpoint_get(service, profile=None, **connection_args)
Return a specific endpoint (keystone endpoint\-get)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.endpoint_get nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.endpoint_list(profile=None, **connection_args)
Return a list of available endpoints (keystone endpoints\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.endpoint_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.role_create(name, profile=None, **connection_args)
Create named role
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.role_create admin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.role_delete(role_id=None, name=None, profile=None, **connection_args)
Delete a role (keystone role\-delete)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.role_delete c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.role_delete role_id=c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.role_delete name=admin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.role_get(role_id=None, name=None, profile=None, **connection_args)
Return a specific roles (keystone role\-get)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.role_get c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.role_get role_id=c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.role_get name=nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.role_list(profile=None, **connection_args)
Return a list of available roles (keystone role\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.role_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.service_create(name, service_type, description=None, profile=None, **connection_args)
Add service to Keystone service catalog
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.service_create nova compute \(aqOpenStack Compute Service\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.service_delete(service_id=None, name=None, profile=None, **connection_args)
Delete a service from Keystone service catalog
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.service_delete c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.service_delete name=nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.service_get(service_id=None, name=None, profile=None, **connection_args)
Return a specific services (keystone service\-get)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.service_get c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.service_get service_id=c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.service_get name=nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.service_list(profile=None, **connection_args)
Return a list of available services (keystone services\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.service_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.tenant_create(name, description=None, enabled=True, profile=None, **connection_args)
Create a keystone tenant
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.tenant_create nova description=\(aqnova tenant\(aq
salt \(aq*\(aq keystone.tenant_create test enabled=False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.tenant_delete(tenant_id=None, name=None, profile=None, **connection_args)
Delete a tenant (keystone tenant\-delete)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.tenant_delete c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.tenant_delete tenant_id=c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.tenant_delete name=demo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.tenant_get(tenant_id=None, name=None, profile=None, **connection_args)
Return a specific tenants (keystone tenant\-get)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.tenant_get c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.tenant_get tenant_id=c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.tenant_get name=nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.tenant_list(profile=None, **connection_args)
Return a list of available tenants (keystone tenants\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.tenant_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.tenant_update(tenant_id=None, name=None, description=None, enabled=None, profile=None, **connection_args)
Update a tenant\(aqs information (keystone tenant\-update)
The following fields may be updated: name, email, enabled.
Can only update name if targeting by ID
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.tenant_update name=admin enabled=True
salt \(aq*\(aq keystone.tenant_update c965f79c4f864eaaa9c3b41904e67082 name=admin email=admin@domain.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.token_get(profile=None, **connection_args)
Return the configured tokens (keystone token\-get)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.token_get c965f79c4f864eaaa9c3b41904e67082
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_create(name, password, email, tenant_id=None, enabled=True, profile=None, **connection_args)
Create a user (keystone user\-create)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_create name=jack password=zero email=jack@halloweentown.org tenant_id=a28a7b5a999a455f84b1f5210264375e enabled=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_delete(user_id=None, name=None, profile=None, **connection_args)
Delete a user (keystone user\-delete)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_delete c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.user_delete user_id=c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.user_delete name=nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_get(user_id=None, name=None, profile=None, **connection_args)
Return a specific users (keystone user\-get)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_get c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.user_get user_id=c965f79c4f864eaaa9c3b41904e67082
salt \(aq*\(aq keystone.user_get name=nova
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_list(profile=None, **connection_args)
Return a list of available users (keystone user\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_password_update(user_id=None, name=None, password=None, profile=None, **connection_args)
Update a user\(aqs password (keystone user\-password\-update)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_password_update c965f79c4f864eaaa9c3b41904e67082 password=12345
salt \(aq*\(aq keystone.user_password_update user_id=c965f79c4f864eaaa9c3b41904e67082 password=12345
salt \(aq*\(aq keystone.user_password_update name=nova password=12345
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_role_add(user_id=None, user=None, tenant_id=None, tenant=None, role_id=None, role=None, profile=None, **connection_args)
Add role for user in tenant (keystone user\-role\-add)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_role_add user_id=298ce377245c4ec9b70e1c639c89e654 tenant_id=7167a092ece84bae8cead4bf9d15bb3b role_id=ce377245c4ec9b70e1c639c89e8cead4
salt \(aq*\(aq keystone.user_role_add user=admin tenant=admin role=admin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_role_list(user_id=None, tenant_id=None, user_name=None, tenant_name=None, profile=None, **connection_args)
Return a list of available user_roles (keystone user\-roles\-list)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_role_list user_id=298ce377245c4ec9b70e1c639c89e654 tenant_id=7167a092ece84bae8cead4bf9d15bb3b
salt \(aq*\(aq keystone.user_role_list user_name=admin tenant_name=admin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_role_remove(user_id=None, user=None, tenant_id=None, tenant=None, role_id=None, role=None, profile=None, **connection_args)
Remove role for user in tenant (keystone user\-role\-remove)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_role_remove user_id=298ce377245c4ec9b70e1c639c89e654 tenant_id=7167a092ece84bae8cead4bf9d15bb3b role_id=ce377245c4ec9b70e1c639c89e8cead4
salt \(aq*\(aq keystone.user_role_remove user=admin tenant=admin role=admin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_update(user_id=None, name=None, email=None, enabled=None, tenant=None, profile=None, **connection_args)
Update a user\(aqs information (keystone user\-update)
The following fields may be updated: name, email, enabled, tenant.
Because the name is one of the fields, a valid user id is required.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_update user_id=c965f79c4f864eaaa9c3b41904e67082 name=newname
salt \(aq*\(aq keystone.user_update c965f79c4f864eaaa9c3b41904e67082 name=newname email=newemail@domain.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.keystone.user_verify_password(user_id=None, name=None, password=None, profile=None, **connection_args)
Verify a user\(aqs password
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq keystone.user_verify_password name=test password=foobar
salt \(aq*\(aq keystone.user_verify_password user_id=c965f79c4f864eaaa9c3b41904e67082 password=foobar
.ft P
.fi
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.available
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.check_available kvm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.is_loaded(mod)
Check to see if the specified kernel module is loaded
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.is_loaded kvm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.load(mod, persist=False)
Load the specified kernel module
.INDENT 7.0
.TP
.B mod
Name of module to add
.TP
.B persist
Write module to /etc/modules to make it load on system reboot
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.load kvm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.lsmod()
Return a dict containing information about currently loaded modules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.lsmod
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.mod_list(only_persist=False)
Return a list of the loaded module names
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.mod_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.kmod.remove(mod, persist=False, comment=True)
Remove the specified kernel module
.INDENT 7.0
.TP
.B mod
Name of module to remove
.TP
.B persist
Also remove module from /etc/modules
.TP
.B comment
If persist is set don\(aqt remove line from /etc/modules but only
comment it
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq kmod.remove kvm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.launchctl
.sp
Module for the management of MacOS systems that use launchd/launchctl
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
plistlib Python module
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.launchctl.available(job_label)
Check that the given service is available.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available com.openssh.sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.launchctl.get_all()
Return all installed services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.launchctl.missing(job_label)
The inverse of service.available
Check that the given service is not available.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing com.openssh.sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.launchctl.restart(job_label, runas=None)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service label>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.launchctl.start(job_label, runas=None)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service label>
salt \(aq*\(aq service.start org.ntp.ntpd
salt \(aq*\(aq service.start /System/Library/LaunchDaemons/org.ntp.ntpd.plist
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.launchctl.status(job_label, runas=None)
Return the status for a service, returns a bool whether the service is
running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service label>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.launchctl.stop(job_label, runas=None)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service label>
salt \(aq*\(aq service.stop org.ntp.ntpd
salt \(aq*\(aq service.stop /System/Library/LaunchDaemons/org.ntp.ntpd.plist
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.layman
.sp
Support for Layman
.INDENT 0.0
.TP
.B salt.modules.layman.add(overlay)
Add the given overlay from the cached remote list to your locally
installed overlays. Specify \(aqALL\(aq to add all overlays from the
remote list.
.sp
Return a list of the new overlay(s) added:
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq layman.add <overlay name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.layman.delete(overlay)
Remove the given overlay from the your locally installed overlays.
Specify \(aqALL\(aq to remove all overlays.
.sp
Return a list of the overlays(s) that were removed:
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq layman.delete <overlay name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.layman.list_local()
List the locally installed overlays.
.sp
Return a list of installed overlays:
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq layman.list_local
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.layman.sync(overlay=\(aqALL\(aq)
Update the specified overlay. Use \(aqALL\(aq to synchronize all overlays.
This is the default if no overlay is specified.
.INDENT 7.0
.TP
.B overlay
Name of the overlay to sync. (Defaults to \(aqALL\(aq)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq layman.sync
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.ldapmod
.sp
Salt interface to LDAP commands
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
ldap Python module
.UNINDENT
.TP
.B configuration
In order to connect to LDAP, certain configuration is required
in the minion config on the LDAP server. The minimum configuration items
that must be set are:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ldap.basedn: dc=acme,dc=com (example values, adjust to suit)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If your LDAP server requires authentication then you must also set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ldap.anonymous: False
ldap.binddn: admin
ldap.bindpw: password
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In addition, the following optional values may be set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ldap.server: localhost (default=localhost, see warning below)
ldap.port: 389 (default=389, standard port)
ldap.tls: False (default=False, no TLS)
ldap.no_verify: False (default=False, verify TLS)
ldap.anonymous: True (default=True, bind anonymous)
ldap.scope: 2 (default=2, ldap.SCOPE_SUBTREE)
ldap.attrs: [saltAttr] (default=None, return all attributes)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
At the moment this module only recommends connection to LDAP services
listening on \fBlocalhost\fP\&. This is deliberate to avoid the potentially
dangerous situation of multiple minions sending identical update commands
to the same LDAP server. It\(aqs easy enough to override this behavior, but
badness may ensue \- you have been warned.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ldapmod.search(filter, dn=None, scope=None, attrs=None, **kwargs)
Run an arbitrary LDAP query and return the results.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqldaphost\(aq ldap.search "filter=cn=myhost"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Return data:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqmyhost\(aq: {\(aqcount\(aq: 1,
\(aqresults\(aq: [[\(aqcn=myhost,ou=hosts,o=acme,c=gb\(aq,
{\(aqsaltKeyValue\(aq: [\(aqntpserver=ntp.acme.local\(aq,
\(aqfoo=myfoo\(aq],
\(aqsaltState\(aq: [\(aqfoo\(aq, \(aqbar\(aq]}]],
\(aqtime\(aq: {\(aqhuman\(aq: \(aq1.2ms\(aq, \(aqraw\(aq: \(aq0.00123\(aq}}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Search and connection options can be overridden by specifying the relevant
option as key=value pairs, for example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqldaphost\(aq ldap.search filter=cn=myhost dn=ou=hosts,o=acme,c=gb
scope=1 attrs=\(aq\(aq server=\(aqlocalhost\(aq port=\(aq7393\(aq tls=True bindpw=\(aqssh\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.linux_acl
.sp
Support for Linux File Access Control Lists
.INDENT 0.0
.TP
.B salt.modules.linux_acl.delfacl(acl_type, acl_name, *args)
Remove specific FACL from the specified file(s)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq acl.delfacl user myuser /tmp/house/kitchen
salt \(aq*\(aq acl.delfacl default:group mygroup /tmp/house/kitchen
salt \(aq*\(aq acl.delfacl d:u myuser /tmp/house/kitchen
salt \(aq*\(aq acl.delfacl g myuser /tmp/house/kitchen /tmp/house/livingroom
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_acl.getfacl(*args)
Return (extremely verbose) map of FACLs on specified file(s)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq acl.getfacl /tmp/house/kitchen
salt \(aq*\(aq acl.getfacl /tmp/house/kitchen /tmp/house/livingroom
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_acl.modfacl(acl_type, acl_name, perms, *args)
Add or modify a FACL for the specified file(s)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq acl.addfacl user myuser rwx /tmp/house/kitchen
salt \(aq*\(aq acl.addfacl default:group mygroup rx /tmp/house/kitchen
salt \(aq*\(aq acl.addfacl d:u myuser 7 /tmp/house/kitchen
salt \(aq*\(aq acl.addfacl g mygroup 0 /tmp/house/kitchen /tmp/house/livingroom
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_acl.version()
Return facl version from getfacl \-\-version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq acl.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_acl.wipefacls(*args)
Remove all FACLs from the specified file(s)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq acl.wipefacls /tmp/house/kitchen
salt \(aq*\(aq acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.linux_lvm
.sp
Support for Linux LVM2
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.fullversion()
Return all version info from lvm version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvm.fullversion
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.lvcreate(lvname, vgname, size=None, extents=None, snapshot=None, pv=None, **kwargs)
Create a new logical volume, with option for which physical volume to be used
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvm.lvcreate new_volume_name vg_name size=10G
salt \(aq*\(aq lvm.lvcreate new_volume_name vg_name extents=100 pv=/dev/sdb
salt \(aq*\(aq lvm.lvcreate new_snapshot vg_name snapshot=volume_name size=3G
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.lvdisplay(lvname=\(aq\(aq)
Return information about the logical volume(s)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvm.lvdisplay
salt \(aq*\(aq lvm.lvdisplay /dev/vg_myserver/root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.lvremove(lvname, vgname)
Remove a given existing logical volume from a named existing volume group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvm.lvremove lvname vgname force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.pvcreate(devices, **kwargs)
Set a physical device to be used as an LVM physical volume
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt mymachine lvm.pvcreate /dev/sdb1,/dev/sdb2
salt mymachine lvm.pvcreate /dev/sdb1 dataalignmentoffset=7s
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.pvdisplay(pvname=\(aq\(aq)
Return information about the physical volume(s)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvm.pvdisplay
salt \(aq*\(aq lvm.pvdisplay /dev/md0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.pvremove(devices)
Remove a physical device being used as an LVM physical volume
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt mymachine lvm.pvremove /dev/sdb1,/dev/sdb2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.version()
Return LVM version from lvm version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvm.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.vgcreate(vgname, devices, **kwargs)
Create an LVM volume group
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt mymachine lvm.vgcreate my_vg /dev/sdb1,/dev/sdb2
salt mymachine lvm.vgcreate my_vg /dev/sdb1 clustered=y
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.vgdisplay(vgname=\(aq\(aq)
Return information about the volume group(s)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvm.vgdisplay
salt \(aq*\(aq lvm.vgdisplay nova\-volumes
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_lvm.vgremove(vgname)
Remove an LVM volume group
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt mymachine lvm.vgremove vgname
salt mymachine lvm.vgremove vgname force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.assign net.ipv4.ip_forward 1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.default_config()
Linux hosts using systemd 207 or later ignore \fB/etc/sysctl.conf\fP and only
load from \fB/etc/sysctl.d/*.conf\fP\&. This function will do the proper checks
and return a default config file which will be valid for the Minion. Hosts
running systemd >= 207 will use \fB/etc/sysctl.d/99\-salt.conf\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqkernel:Linux\(aq sysctl.default_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.get(name)
Return a single sysctl parameter for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.get net.ipv4.ip_forward
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.persist(name, value, config=None)
Assign and persist a simple sysctl parameter for this minion. If \fBconfig\fP
is not specified, a sensible default will be chosen using
\fI\%sysctl.default_config\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.persist net.ipv4.ip_forward 1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.linux_sysctl.show(config_file=False)
Return a list of sysctl parameters for this minion
.INDENT 7.0
.TP
.B config: Pull the data from the system configuration file
instead of the live data.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.localemod
.sp
Module for managing locales on POSIX\-like systems.
.INDENT 0.0
.TP
.B salt.modules.localemod.avail(locale)
Check if a locale is available.
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locale.avail \(aqen_US.UTF\-8\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.localemod.gen_locale(locale)
Generate a locale.
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B Parameters
\fBlocale\fP \-\- Any locale listed in /usr/share/i18n/locales or
/usr/share/i18n/SUPPORTED for debian and gentoo based distros
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locale.gen_locale en_US.UTF\-8
salt \(aq*\(aq locale.gen_locale \(aqen_IE@euro ISO\-8859\-15\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.localemod.get_locale()
Get the current system locale
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locale.get_locale
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.localemod.list_avail()
Lists available (compiled) locales
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locale.list_avail
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.localemod.set_locale(locale)
Sets the current system locale
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locale.set_locale \(aqen_US.UTF\-8\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.locate
.sp
Module for using the locate utilities
.INDENT 0.0
.TP
.B salt.modules.locate.locate(pattern, database=\(aq\(aq, limit=0, **kwargs)
Performs a file lookup. Valid options (and their defaults) are:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
basename=False
count=False
existing=False
follow=True
ignore=False
nofollow=False
wholename=True
regex=False
database=<locate\(aqs default database>
limit=<integer, not set by default>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See the manpage for \fBlocate(1)\fP for further explanation of these options.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locate.locate
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.locate.stats()
Returns statistics about the locate database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locate.stats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.locate.updatedb()
Updates the locate database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locate.updatedb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.locate.version()
Returns the version of locate
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq locate.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.logadm
.sp
Module for managing Solaris logadm based log rotations.
.INDENT 0.0
.TP
.B salt.modules.logadm.remove(name, conf_file=\(aq/etc/logadm.conf\(aq)
Remove log pattern from logadm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq logadm.remove myapplog
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.logadm.rotate(name, pattern=False, count=False, age=False, size=False, copy=True, conf_file=\(aq/etc/logadm.conf\(aq)
Set up pattern for logging.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq logadm.rotate myapplog pattern=\(aq/var/log/myapp/*.log\(aq count=7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.logadm.show_conf(conf_file=\(aq/etc/logadm.conf\(aq)
Show parsed configuration
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq logadm.show_conf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.logrotate
.sp
Module for managing logrotate.
.INDENT 0.0
.TP
.B salt.modules.logrotate.set_(key, value, setting=None, conf_file=\(aq/etc/logrotate.conf\(aq)
Set a new value for a specific configuration line
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq logrotate.set rotate 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Can also be used to set a single value inside a multiline configuration
block. For instance, to change rotate in the following block:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/var/log/wtmp {
monthly
create 0664 root root
rotate 1
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use the following command:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq logrotate.set /var/log/wtmp rotate 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This module also has the ability to scan files inside an include directory,
and make changes in the appropriate file.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.logrotate.show_conf(conf_file=\(aq/etc/logrotate.conf\(aq)
Show parsed configuration
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq logrotate.show_conf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.lvs
.sp
Support for LVS (Linux Virtual Server)
.INDENT 0.0
.TP
.B salt.modules.lvs.add_server(protocol=None, service_address=None, server_address=None, packet_forward_method=\(aqdr\(aq, weight=1, **kwargs)
Add a real server to a virtual service.
.INDENT 7.0
.TP
.B protocol
The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service).
.TP
.B service_address
The LVS service address.
.TP
.B server_address
The real server address.
.TP
.B packet_forward_method
The LVS packet forwarding method(\fBdr\fP for direct routing, \fBtunnel\fP for tunneling, \fBnat\fP for network access translation).
.TP
.B weight
The capacity of a server relative to the others in the pool.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.add_server tcp 1.1.1.1:80 192.168.0.11:8080 nat 1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.add_service(protocol=None, service_address=None, scheduler=\(aqwlc\(aq)
Add a virtual service.
.INDENT 7.0
.TP
.B protocol
The service protocol(only support tcp, udp and fwmark service).
.TP
.B service_address
The LVS service address.
.TP
.B scheduler
Algorithm for allocating TCP connections and UDP datagrams to real servers.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.add_service tcp 1.1.1.1:80 rr
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.check_server(protocol=None, service_address=None, server_address=None, **kwargs)
Check the real server exists in the specified service.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.check_server tcp 1.1.1.1:80 192.168.0.11:8080
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.check_service(protocol=None, service_address=None, **kwargs)
Check the virtual service exists.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.check_service tcp 1.1.1.1:80
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.clear()
Clear the virtual server table
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.clear
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.delete_server(protocol=None, service_address=None, server_address=None)
Delete the realserver from the virtual service.
.INDENT 7.0
.TP
.B protocol
The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service).
.TP
.B service_address
The LVS service address.
.TP
.B server_address
The real server address.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.delete_server tcp 1.1.1.1:80 192.168.0.11:8080
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.delete_service(protocol=None, service_address=None)
Delete the virtual service.
.INDENT 7.0
.TP
.B protocol
The service protocol(only support tcp, udp and fwmark service).
.TP
.B service_address
The LVS service address.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.delete_service tcp 1.1.1.1:80
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.edit_server(protocol=None, service_address=None, server_address=None, packet_forward_method=None, weight=None, **kwargs)
Edit a real server to a virtual service.
.INDENT 7.0
.TP
.B protocol
The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service).
.TP
.B service_address
The LVS service address.
.TP
.B server_address
The real server address.
.TP
.B packet_forward_method
The LVS packet forwarding method(\fBdr\fP for direct routing, \fBtunnel\fP for tunneling, \fBnat\fP for network access translation).
.TP
.B weight
The capacity of a server relative to the others in the pool.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.edit_server tcp 1.1.1.1:80 192.168.0.11:8080 nat 1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.edit_service(protocol=None, service_address=None, scheduler=None)
Edit the virtual service.
.INDENT 7.0
.TP
.B protocol
The service protocol(only support tcp, udp and fwmark service).
.TP
.B service_address
The LVS service address.
.TP
.B scheduler
Algorithm for allocating TCP connections and UDP datagrams to real servers.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.edit_service tcp 1.1.1.1:80 rr
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.get_rules()
Get the virtual server rules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.get_rules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.list_(protocol=None, service_address=None)
List the virtual server table if service_address is not specified. If a service_address is selected, list this service only.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lvs.zero(protocol=None, service_address=None)
Zero the packet, byte and rate counters in a service or all services.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lvs.zero
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.lxc
.sp
Control Linux Containers via Salt
.INDENT 0.0
.TP
.B depends
lxc package for distribution
.UNINDENT
.sp
lxc >= 1.0 (even beta alpha) is required
.INDENT 0.0
.TP
.B salt.modules.lxc.attachable(name)
Return True if the named container can be attached to via the lxc\-attach
command
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.attachable ubuntu
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.bootstrap(name, config=None, approve_key=True, install=True, pub_key=None, priv_key=None, bootstrap_url=None, force_install=False, unconditional_install=False, bootstrap_args=None, bootstrap_shell=None)
Install and configure salt in a container.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.bootstrap name [config=config_data] \e
[approve_key=(True|False)] [install=(True|False)]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B config
Minion configuration options. By default, the \fBmaster\fP option is set
to the target host\(aqs master.
.TP
.B approve_key
Request a pre\-approval of the generated minion key. Requires
that the salt\-master be configured to either auto\-accept all keys or
expect a signing request from the target host. Default: \fBTrue\fP
.TP
.B pub_key
Explicit public key to pressed the minion with (optional).
This can be either a filepath or a string representing the key
.TP
.B priv_key
Explicit private key to pressed the minion with (optional).
This can be either a filepath or a string representing the key
.TP
.B bootstrap_url
url, content or filepath to the salt bootstrap script
.TP
.B bootstrap_args
salt bootstrap script arguments
.TP
.B bootstrap_shell
shell to execute the script into
.TP
.B install
Whether to attempt a full installation of salt\-minion if needed.
.TP
.B force_install
Force installation even if salt\-minion is detected,
this is the way to run vendor bootstrap scripts even
if a salt minion is already present in the container
.TP
.B unconditional_install
Run the script even if the container seems seeded
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.bootstrap ubuntu
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.clone(name, orig, snapshot=False, profile=None, **kwargs)
Create a new container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.clone name orig [snapshot=(True|False)] \e
[size=filesystem_size] [vgname=volume_group] \e
[profile=profile_name]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the container.
.TP
.B orig
Name of the cloned original container
.TP
.B snapshot
Do we use Copy On Write snapshots (LVM)
.TP
.B size
Size of the container
.TP
.B vgname
LVM volume group(lxc)
.TP
.B profile
A LXC profile (defined in config or pillar).
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.clone myclone ubuntu "snapshot=True"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.cloud_init(name, vm_=None, **kwargs)
Thin wrapper to lxc.init to be used from the saltcloud lxc driver
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.cloud_init foo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the container. May be \fBNone\fP and then guessed from saltcloud
mapping.
.TP
.B \fBvm_\fP
saltcloud mapping defaults for the vm
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.cloud_init_interface(name, vm_=None, **kwargs)
Interface between salt.cloud.lxc driver and lxc.init
\fBvm_\fP is a mapping of vm opts in the salt.cloud format
as documented for the lxc driver.
.sp
This can be used either:
.INDENT 7.0
.IP \(bu 2
from the salt cloud driver
.IP \(bu 2
because you find the argument to give easier here
than using directly lxc.init
.UNINDENT
.INDENT 7.0
.TP
.B WARNING: BE REALLY CAREFUL CHANGING DEFAULTS !!!
IT\(aqS A RETRO COMPATIBLE INTERFACE WITH
THE SALT CLOUD DRIVER (ask kiorky).
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.cloud_init_interface foo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
name of the lxc container to create
.TP
.B from_container
which container we use as a template
when running lxc.clone
.TP
.B image
which template do we use when we
are using lxc.create. This is the default
mode unless you specify something in from_container
.TP
.B backing
which backing store to use.
Values can be: overlayfs, dir(default), lvm, zfs, brtfs
.TP
.B fstype
When using a blockdevice level backing store,
which filesystem to use on
.TP
.B size
When using a blockdevice level backing store,
which size for the filesystem to use on
.TP
.B snapshot
Use snapshot when cloning the container source
.TP
.B vgname
if using LVM: vgname
.TP
.B lgname
if using LVM: lvname
.TP
.B pub_key
public key to preseed the minion with.
Can be the keycontent or a filepath
.TP
.B priv_key
private key to preseed the minion with.
Can be the keycontent or a filepath
.TP
.B ip
ip for the primary nic
.TP
.B mac
mac for the primary nic
.TP
.B netmask
netmask for the primary nic (24)
= \fBvm_.get(\(aqnetmask\(aq, \(aq24\(aq)\fP
.TP
.B bridge
bridge for the primary nic (lxcbr0)
.TP
.B gateway
network gateway for the container
.TP
.B additional_ips
additionnal ips which will be wired on the main bridge (br0)
which is connected to internet.
Be aware that you may use manual virtual mac addresses
providen by you provider (online, ovh, etc).
This is a list of mappings {ip: \(aq\(aq, mac: \(aq\(aq,netmask:\(aq\(aq}
Set gateway to None and an interface with a gateway
to escape from another interface that eth0.
eg:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- {\(aqmac\(aq: \(aq00:16:3e:01:29:40\(aq,
\(aqgateway\(aq: None, (default)
\(aqlink\(aq: \(aqbr0\(aq, (default)
\(aqnetmask\(aq: \(aq\(aq, (default)
\(aqip\(aq: \(aq22.1.4.25\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B unconditional_install
given to lxc.bootstrap (see relative doc)
.TP
.B force_install
given to lxc.bootstrap (see relative doc)
.TP
.B config
any extra argument for the salt minion config
.TP
.B dnsservers
dns servers to set inside the container
.TP
.B autostart
autostart the container at boot time
.TP
.B password
administrative password for the container
.TP
.B users
administrative users for the container
default: [root] and [root, ubuntu] on ubuntu
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.cp(name, src, dest)
Copy a file or directory from the host into a container
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.cp /tmp/foo /root/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.create(name, config=None, profile=None, options=None, **kwargs)
Create a new container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.create name [config=config_file] \e
[profile=profile] [template=template_name] \e
[backing=backing_store] [vgname=volume_group] \e
[size=filesystem_size] [options=template_options]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the container.
.TP
.B config
The config file to use for the container. Defaults to system\-wide
config (usually in /etc/lxc/lxc.conf).
.TP
.B profile
A LXC profile (defined in config or pillar).
.TP
.B template
The template to use. E.g., \(aqubuntu\(aq or \(aqfedora\(aq.
.TP
.B backing
The type of storage to use. Set to \(aqlvm\(aq to use an LVM group. Defaults
to filesystem within /var/lib/lxc/.
.TP
.B vgname
Name of the LVM volume group in which to create the volume for this
container. Only applicable if backing=lvm. Defaults to \(aqlxc\(aq.
.TP
.B fstype
fstype to use on LVM lv.
.TP
.B size
Size of the volume to create. Only applicable if backing=lvm.
Defaults to 1G.
.TP
.B options
Template specific options to pass to the lxc\-create command.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.destroy(name, stop=True)
Destroy the named container.
WARNING: Destroys all data associated with the container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.destroy name [stop=(True|False)]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.edit_conf(conf_file, out_format=\(aqsimple\(aq, **kwargs)
Edit an LXC configuration file. If a setting is already present inside the
file, its value will be replaced. If it does not exist, it will be appended
to the end of the file. Comments and blank lines will be kept in\-tact if
they already exist in the file.
.sp
After the file is edited, its contents will be returned. By default, it
will be returned in \fBsimple\fP format, meaning an unordered dict (which
may not represent the actual file order). Passing in an \fBout_format\fP of
\fBcommented\fP will return a data structure which accurately represents the
order and content of the file.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.edit_conf /etc/lxc/mycontainer.conf out_format=commented lxc.network.type=veth
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.exists(name)
Returns whether the named container exists.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.exists name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.freeze(name)
Freeze the named container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.freeze name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.get_base(**kwargs)
If the needed base does not exist, then create it, if it does exist
create nothing and return the name of the base lxc container so
it can be cloned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.init name [cpuset=cgroups_cpuset] \e
[nic=nic_profile] [profile=lxc_profile] \e
[nic_opts=nic_opts] [image=network image path]\e
[seed=(True|False)] [install=(True|False)] \e
[config=minion_config]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.get_parameter(name, parameter)
Returns the value of a cgroup parameter for a container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.get_parameter name parameter
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.info(name)
Returns information about a container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.info name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.init(name, cpuset=None, cpushare=None, memory=None, nic=\(aqdefault\(aq, profile=None, nic_opts=None, cpu=None, autostart=True, password=None, users=None, dnsservers=None, bridge=None, gateway=None, pub_key=None, priv_key=None, force_install=False, unconditional_install=False, bootstrap_args=None, bootstrap_shell=None, bootstrap_url=None, **kwargs)
Initialize a new container.
.sp
This is a partial idempotent function as if it is already
provisioned, we will reset a bit the lxc configuration
file but much of the hard work will be escaped as
markers will prevent re\-execution of harmful tasks.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.init name [cpuset=cgroups_cpuset] \e
[cpushare=cgroups_cpushare] [memory=cgroups_memory] \e
[nic=nic_profile] [profile=lxc_profile] \e
[nic_opts=nic_opts] [start=(True|False)] \e
[seed=(True|False)] [install=(True|False)] \e
[config=minion_config] [approve_key=(True|False) \e
[clone=original] [autostart=True] \e
[priv_key=/path_or_content] [pub_key=/path_or_content] \e
[bridge=lxcbr0] [gateway=10.0.3.1] \e
[dnsservers[dns1,dns2]] \e
[users=[foo]] password=\(aqsecret\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the container.
.TP
.B cpus
Select a random number of cpu cores and assign it to the cpuset, if the
cpuset option is set then this option will be ignored
.TP
.B cpuset
Explicitly define the cpus this container will be bound to
.TP
.B cpushare
cgroups cpu shares.
.TP
.B autostart
autostart container on reboot
.TP
.B memory
cgroups memory limit, in MB.
(0 for nolimit, None for old default 1024MB)
.TP
.B gateway
the ipv4 gateway to use
the default does nothing more than lxcutils does
.TP
.B bridge
the bridge to use
the default does nothing more than lxcutils does
.TP
.B nic
Network interfaces profile (defined in config or pillar).
.TP
.B users
Sysadmins users to set the administrative password to
e.g. [root, ubuntu, sysadmin], default [root] and [root, ubuntu]
on ubuntu
.TP
.B password
Set the initial password for default sysadmin users, at least root
but also can be used for sudoers, e.g. [root, ubuntu, sysadmin]
.TP
.B profile
A LXC profile (defined in config or pillar).
This can be either a real profile mapping or a string
to retrieve it in configuration
.TP
.B nic_opts
Extra options for network interfaces. E.g:
.sp
\fB{"eth0": {"mac": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1", "ipv6": "2001:db8::ff00:42:8329"}}\fP
.sp
or
.sp
\fB{"eth0": {"mac": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1/24", "ipv6": "2001:db8::ff00:42:8329"}}\fP
.TP
.B start
Start the newly created container.
.TP
.B dnsservers
list of dns servers to set in the container, default [] (no setting)
.TP
.B seed
Seed the container with the minion config. Default: \fBTrue\fP
.TP
.B install
If salt\-minion is not already installed, install it. Default: \fBTrue\fP
.TP
.B config
Optional config parameters. By default, the id is set to
the name of the container.
.TP
.B pub_key
Explicit public key to preseed the minion with (optional).
This can be either a filepath or a string representing the key
.TP
.B priv_key
Explicit private key to preseed the minion with (optional).
This can be either a filepath or a string representing the key
.TP
.B approve_key
If explicit preseeding is not used;
Attempt to request key approval from the master. Default: \fBTrue\fP
.TP
.B clone
Original from which to use a clone operation to create the container.
Default: \fBNone\fP
.TP
.B bootstrap_url
See lxc.bootstrap
*
.TP
.B bootstrap_shell
See lxc.bootstrap
.TP
.B bootstrap_args
See lxc.bootstrap
.TP
.B force_install
Force installation even if salt\-minion is detected,
this is the way to run vendor bootstrap scripts even
if a salt minion is already present in the container
.TP
.B unconditional_install
Run the script even if the container seems seeded
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.list_(extra=False)
List defined containers classified by status.
Status can be running, stopped, and frozen.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B extra
Also get per container specific info at once.
Warning: it will not return a collection of list
but a collection of mappings by status and then per
container name:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqrunning\(aq: [\(aqfoo\(aq]} # normal mode
{\(aqrunning\(aq: {\(aqfoo\(aq: {\(aqinfo1\(aq: \(aqbar\(aq}} # extra mode
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.list
salt \(aq*\(aq lxc.list extra=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.ls()
Return just a list of the containers available
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.ls
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.read_conf(conf_file, out_format=\(aqsimple\(aq)
Read in an LXC configuration file. By default returns a simple, unsorted
dict, but can also return a more detailed structure including blank lines
and comments.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.read_conf /etc/lxc/mycontainer.conf
salt \(aqminion\(aq lxc.read_conf /etc/lxc/mycontainer.conf out_format=commented
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.run_cmd(name, cmd, no_start=False, preserve_state=True, stdout=True, stderr=False, use_vt=False, keep_env=\(aqhttp_proxy, https_proxy, no_proxy\(aq)
Run a command inside the container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq name command [no_start=(True|False)] \e
[preserve_state=(True|False)] [stdout=(True|False)] \e
[stderr=(True|False)]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the container on which to operate.
.TP
.B cmd
Command to run
.TP
.B no_start
If the container is not running, don\(aqt start it. Default: \fBFalse\fP
.TP
.B preserve_state
After running the command, return the container to its previous
state. Default: \fBTrue\fP
.TP
.B stdout:
Return stdout. Default: \fBTrue\fP
.TP
.B stderr:
Return stderr. Default: \fBFalse\fP
.TP
.B use_vt
use saltstack utils.vt to stream output to console
.TP
.B keep_env
A list of env vars to preserve. May be passed as commma\-delimited list.
Defaults to http_proxy,https_proxy.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If stderr and stdout are both \fBFalse\fP, the return code is returned.
If stderr and stdout are both \fBTrue\fP, the pid and return code are
also returned.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.set_dns(name, dnsservers=None, searchdomains=None)
Update container DNS configuration
and possibly also resolv.conf one.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call \-lall lxc.set_dns ubuntu [\(aq8.8.8.8\(aq, \(aq4.4.4.4\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.set_parameter(name, parameter, value)
Set the value of a cgroup parameter for a container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.set_parameter name parameter value
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.set_pass(name, users, password)
Set the password of one or more system users inside containers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.set_pass container\-name root foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.start(name, restart=False)
Start the named container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.start name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.state(name)
Returns the state of a container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.state name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.stop(name, kill=True)
Stop the named container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.stop name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.templates(templates_dir=\(aq/usr/share/lxc/templates\(aq)
Returns a list of existing templates
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.templates
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.unfreeze(name)
Unfreeze the named container.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lxc.unfreeze name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.update_lxc_conf(name, lxc_conf, lxc_conf_unset)
Edit LXC configuration options
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call \-lall lxc.update_lxc_conf ubuntu lxc_conf="[{\(aqnetwork.ipv4.ip\(aq:\(aq10.0.3.5\(aq}]" lxc_conf_unset="[\(aqlxc.utsname\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.lxc.write_conf(conf_file, conf)
Write out an LXC configuration file
.sp
This is normally only used internally. The format of the data structure
must match that which is returned from \fBlxc.read_conf()\fP, with
\fBout_format\fP set to \fBcommented\fP\&.
.sp
An example might look like:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
{\(aqlxc.utsname\(aq: \(aq$CONTAINER_NAME\(aq},
\(aq# This is a commented line\en\(aq,
\(aq\en\(aq,
{\(aqlxc.mount\(aq: \(aq$CONTAINER_FSTAB\(aq},
{\(aqlxc.rootfs\(aq: {\(aqcomment\(aq: \(aqThis is another test\(aq,
\(aqvalue\(aq: \(aqThis is another test\(aq}},
\(aq\en\(aq,
{\(aqlxc.network.type\(aq: \(aqveth\(aq},
{\(aqlxc.network.flags\(aq: \(aqup\(aq},
{\(aqlxc.network.link\(aq: \(aqbr0\(aq},
{\(aqlxc.network.hwaddr\(aq: \(aq$CONTAINER_MACADDR\(aq},
{\(aqlxc.network.ipv4\(aq: \(aq$CONTAINER_IPADDR\(aq},
{\(aqlxc.network.name\(aq: \(aq$CONTAINER_DEVICENAME\(aq},
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq lxc.write_conf /etc/lxc/mycontainer.conf \e
out_format=commented
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.mac_group
.sp
Manage groups on Mac OS 10.7+
.INDENT 0.0
.TP
.B salt.modules.mac_group.add(name, gid=None, **kwargs)
Add the specified group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.add foo 3456
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_group.chgid(name, gid)
Change the gid for a named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_group.delete(name)
Remove the named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.delete foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_group.getent(refresh=False)
Return info on all groups
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_group.info(name)
Return information about a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.info foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.mac_user
.sp
Manage users on Mac OS 10.7+
.INDENT 0.0
.TP
.B salt.modules.mac_user.add(name, uid=None, gid=None, groups=None, home=None, shell=None, fullname=None, createhome=True, **kwargs)
Add a user to the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.chfullname(name, fullname)
Change the user\(aqs Full Name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chfullname foo \(aqFoo Bar\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.chgid(name, gid)
Change the default group of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.chgroups(name, groups, append=False)
Change the groups to which the user belongs. Note that the user\(aqs primary
group does not have to be one of the groups passed, membership in the
user\(aqs primary group is automatically assumed.
.INDENT 7.0
.TP
.B groups
Groups to which the user should belong, can be passed either as a
python list or a comma\-separated string
.TP
.B append
Instead of removing user from groups not included in the \fBgroups\fP
parameter, just add user to any groups for which they are not members
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgroups foo wheel,root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.chhome(name, home)
Change the home directory of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhome foo /Users/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.chshell(name, shell)
Change the default shell of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chshell foo /bin/zsh
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.chuid(name, uid)
Change the uid for a named user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chuid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.delete(name, *args)
Remove a user from the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.delete foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.getent(refresh=False)
Return the list of all info for all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.info(name)
Return user information
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.list_groups(name)
Return a list of groups the named user belongs to
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_groups foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_user.list_users()
Return a list of all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_users
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.macports
.sp
Support for MacPorts under Mac OSX.
.sp
This module has some caveats.
.sp
1. Updating the database of available ports is quite resource\-intensive.
However, \fIrefresh=True\fP is the default for all operations that need an
up\-to\-date copy of available ports. Consider \fIrefresh=False\fP when you are
sure no db update is needed.
.sp
2. In some cases MacPorts doesn\(aqt always realize when another copy of itself
is running and will gleefully tromp all over the available ports database.
This makes MacPorts behave in undefined ways until a fresh complete
copy is retrieved.
.sp
Because of 1 and 2 it is possible to get the salt\-minion into a state where
\fIsalt mac\-machine pkg./something/\fP won\(aqt want to return. Use
.sp
\fIsalt\-run jobs.active\fP
.sp
on the master to check for potentially long\-running calls to \fIport\fP\&.
.sp
Finally, ports database updates are always handled with \fIport selfupdate\fP
as opposed to \fIport sync\fP\&. This makes sense in the MacPorts user commmunity
but may confuse experienced Linux admins as Linux package managers
don\(aqt upgrade the packaging software when doing a package database update.
In other words \fIsalt mac\-machine pkg.refresh_db\fP is more like
\fIapt\-get update; apt\-get upgrade dpkg apt\-get\fP than simply \fIapt\-get update\fP\&.
.INDENT 0.0
.TP
.B salt.modules.macports.available_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation
.sp
Options:
.INDENT 7.0
.TP
.B refresh
Update ports with \fBport selfupdate\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.install(name=None, refresh=False, pkgs=None, **kwargs)
Install the passed package(s) with \fBport install\fP
.INDENT 7.0
.TP
.B name
The name of the formula to be installed. Note that this parameter is
ignored if "pkgs" is passed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B version
Specify a version to pkg to install. Ignored if pkgs is specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
salt \(aq*\(aq pkg.install git\-core version=\(aq1.8.5.5\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B variant
Specify a variant to pkg to install. Ignored if pkgs is specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
salt \(aq*\(aq pkg.install git\-core version=\(aq1.8.5.5\(aq variant=\(aq+credential_osxkeychain+doc+pcre\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of formulas to install. Must be passed as a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo@1.2","bar"]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo@1.2+ssl","bar@2.3"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install \(aqpackage package package\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation
.sp
Options:
.INDENT 7.0
.TP
.B refresh
Update ports with \fBport selfupdate\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.list_upgrades(refresh=True)
Check whether or not an upgrade is available for all packages
.sp
Options:
.INDENT 7.0
.TP
.B refresh
Update ports with \fBport selfupdate\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.refresh_db()
Update ports with \fBport selfupdate\fP
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.remove(name=None, pkgs=None, **kwargs)
Removes packages with \fBport uninstall\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.upgrade(refresh=True)
Run a full upgrade using MacPorts \(aqport upgrade outdated\(aq
.sp
Options:
.INDENT 7.0
.TP
.B refresh
Update ports with \fBport selfupdate\fP
.UNINDENT
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.upgrade_available(pkg, refresh=True)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.macports.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.makeconf
.sp
Support for modifying make.conf under Gentoo
.INDENT 0.0
.TP
.B salt.modules.makeconf.append_cflags(value)
Add to or create a new CFLAGS in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.append_cflags \(aq\-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.append_cxxflags(value)
Add to or create a new CXXFLAGS in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.append_cxxflags \(aq\-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.append_emerge_default_opts(value)
Add to or create a new EMERGE_DEFAULT_OPTS in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.append_emerge_default_opts \(aq\-\-jobs\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.append_features(value)
Add to or create a new FEATURES in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.append_features \(aqwebrsync\-gpg\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.append_gentoo_mirrors(value)
Add to or create a new GENTOO_MIRRORS in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.append_gentoo_mirrors \(aqhttp://distfiles.gentoo.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.append_makeopts(value)
Add to or create a new MAKEOPTS in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.append_makeopts \(aq\-j3\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.append_var(var, value)
Add to or create a new variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.append_var \(aqLINGUAS\(aq \(aqen\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.cflags_contains(value)
Verify if CFLAGS variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.cflags_contains \(aq\-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.chost_contains(value)
Verify if CHOST variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.chost_contains \(aqx86_64\-pc\-linux\-gnu\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.cxxflags_contains(value)
Verify if CXXFLAGS variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.cxxflags_contains \(aq\-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.emerge_default_opts_contains(value)
Verify if EMERGE_DEFAULT_OPTS variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.emerge_default_opts_contains \(aq\-\-jobs\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.features_contains(value)
Verify if FEATURES variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.features_contains \(aqwebrsync\-gpg\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.gentoo_mirrors_contains(value)
Verify if GENTOO_MIRRORS variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.gentoo_mirrors_contains \(aqhttp://distfiles.gentoo.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_cflags()
Get the value of CFLAGS variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_cflags
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_chost()
Get the value of CHOST variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_chost
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_cxxflags()
Get the value of CXXFLAGS variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_cxxflags
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_emerge_default_opts()
Get the value of EMERGE_DEFAULT_OPTS variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_emerge_default_opts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_features()
Get the value of FEATURES variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_features
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_gentoo_mirrors()
Get the value of GENTOO_MIRRORS variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_gentoo_mirrors
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_makeopts()
Get the value of MAKEOPTS variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_makeopts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_sync()
Get the value of SYNC variable in the make.conf
.sp
Return the value of the variable or None if the variable is
not in the make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_sync
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.get_var(var)
Get the value of a variable in make.conf
.sp
Return the value of the variable or None if the variable is not in
make.conf
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.get_var \(aqLINGUAS\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.makeopts_contains(value)
Verify if MAKEOPTS variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.makeopts_contains \(aq\-j3\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.remove_var(var)
Remove a variable from the make.conf
.sp
Return a dict containing the new value for the variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.remove_var \(aqLINGUAS\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_cflags(value)
Set the CFLAGS variable
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_cflags \(aq\-march=native \-O2 \-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_chost(value)
Set the CHOST variable
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_chost \(aqx86_64\-pc\-linux\-gnu\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_cxxflags(value)
Set the CXXFLAGS variable
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_cxxflags \(aq\-march=native \-O2 \-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_emerge_default_opts(value)
Set the EMERGE_DEFAULT_OPTS variable
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_emerge_default_opts \(aq\-\-jobs\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_gentoo_mirrors(value)
Set the GENTOO_MIRRORS variable
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_gentoo_mirrors \(aqhttp://distfiles.gentoo.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_makeopts(value)
Set the MAKEOPTS variable
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_makeopts \(aq\-j3\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_sync(value)
Set the SYNC variable
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_sync \(aqrsync://rsync.namerica.gentoo.org/gentoo\-portage\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.set_var(var, value)
Set a variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.set_var \(aqLINGUAS\(aq \(aqen\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.sync_contains(value)
Verify if SYNC variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.sync_contains \(aqrsync://rsync.namerica.gentoo.org/gentoo\-portage\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.trim_cflags(value)
Remove a value from CFLAGS variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.trim_cflags \(aq\-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.trim_cxxflags(value)
Remove a value from CXXFLAGS variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.trim_cxxflags \(aq\-pipe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.trim_emerge_default_opts(value)
Remove a value from EMERGE_DEFAULT_OPTS variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.trim_emerge_default_opts \(aq\-\-jobs\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.trim_features(value)
Remove a value from FEATURES variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.trim_features \(aqwebrsync\-gpg\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.trim_gentoo_mirrors(value)
Remove a value from GENTOO_MIRRORS variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.trim_gentoo_mirrors \(aqhttp://distfiles.gentoo.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.trim_makeopts(value)
Remove a value from MAKEOPTS variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.trim_makeopts \(aq\-j3\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.trim_var(var, value)
Remove a value from a variable in the make.conf
.sp
Return a dict containing the new value for variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<variable>\(aq: {\(aqold\(aq: \(aq<old\-value>\(aq,
\(aqnew\(aq: \(aq<new\-value>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.trim_var \(aqLINGUAS\(aq \(aqen\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.makeconf.var_contains(var, value)
Verify if variable contains a value in make.conf
.sp
Return True if value is set for var
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq makeconf.var_contains \(aqLINGUAS\(aq \(aqen\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.match
.sp
The match module allows for match routines to be run and determine target specs
.INDENT 0.0
.TP
.B salt.modules.match.compound(tgt, minion_id=None)
Return True if the minion ID matches the given compound target
.INDENT 7.0
.TP
.B minion_id
Specify the minion ID to match against the target expression
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.compound \(aqL@cheese,foo and *\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.data(tgt)
Return True if the minion matches the given data target
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.data \(aqspam:eggs\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.filter_by(lookup, expr_form=\(aqcompound\(aq, minion_id=None)
Return the first match in a dictionary of target patterns
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.filter_by \(aq{foo*: Foo!, bar*: Bar!}\(aq minion_id=bar03
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Pillar Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% set roles = salt[\(aqmatch.filter_by\(aq]({
\(aqweb*\(aq: [\(aqapp\(aq, \(aqcaching\(aq],
\(aqdb*\(aq: [\(aqdb\(aq],
}) %}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.glob(tgt, minion_id=None)
Return True if the minion ID matches the given glob target
.INDENT 7.0
.TP
.B minion_id
Specify the minion ID to match against the target expression
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.glob \(aq*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.grain(tgt, delimiter=\(aq:\(aq, delim=None)
Return True if the minion matches the given grain target. The \fBdelimiter\fP
argument can be used to specify a different delimiter.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.grain \(aqos:Ubuntu\(aq
salt \(aq*\(aq match.grain \(aqipv6|2001:db8::ff00:42:8329\(aq delimiter=\(aq|\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B delimiter
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 2014.7.0.
.TP
.B delim
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 0.16.4.
.sp
Deprecated since version 2014.7.0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.grain_pcre(tgt, delimiter=\(aq:\(aq, delim=None)
Return True if the minion matches the given grain_pcre target. The
\fBdelimiter\fP argument can be used to specify a different delimiter.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.grain_pcre \(aqos:Fedo.*\(aq
salt \(aq*\(aq match.grain_pcre \(aqipv6|2001:.*\(aq delimiter=\(aq|\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B delimiter
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 2014.7.0.
.TP
.B delim
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 0.16.4.
.sp
Deprecated since version 2014.7.0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.ipcidr(tgt)
Return True if the minion matches the given ipcidr target
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.ipcidr \(aq192.168.44.0/24\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.list_(tgt, minion_id=None)
Return True if the minion ID matches the given list target
.INDENT 7.0
.TP
.B minion_id
Specify the minion ID to match against the target expression
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.list \(aqserver1,server2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.pcre(tgt, minion_id=None)
Return True if the minion ID matches the given pcre target
.INDENT 7.0
.TP
.B minion_id
Specify the minion ID to match against the target expression
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.pcre \(aq.*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.match.pillar(tgt, delimiter=\(aq:\(aq, delim=None)
Return True if the minion matches the given pillar target. The
\fBdelimiter\fP argument can be used to specify a different delimiter.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq match.pillar \(aqcheese:foo\(aq
salt \(aq*\(aq match.pillar \(aqclone_url|https://github.com/saltstack/salt.git\(aq delimiter=\(aq|\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B delimiter
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 2014.7.0.
.TP
.B delim
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 0.16.4.
.sp
Deprecated since version 2014.7.0.
.UNINDENT
.UNINDENT
.SS salt.modules.mdadm
.sp
Salt module to manage RAID arrays with mdadm
.INDENT 0.0
.TP
.B salt.modules.mdadm.assemble(name, devices, test_mode=False, **kwargs)
Assemble a RAID device.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq raid.assemble /dev/md0 [\(aq/dev/xvdd\(aq, \(aq/dev/xvde\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Adding \fBtest_mode=True\fP as an argument will print out the mdadm
command that would have been run.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
The name of the array to assemble.
.TP
.B devices
The list of devices comprising the array to assemble.
.TP
.B kwargs
Optional arguments to be passed to mdadm.
.TP
.B returns
.INDENT 7.0
.TP
.B test_mode=True:
Prints out the full command.
.TP
.B test_mode=False (Default):
Executes command on the host(s) and prints out the mdadm output.
.UNINDENT
.UNINDENT
.sp
For more info, read the \fBmdadm\fP manpage.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mdadm.create(name, level, devices, metadata=\(aqdefault\(aq, test_mode=False, **kwargs)
Create a RAID device.
.sp
Changed in version 2014.7.0.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Use with CAUTION, as this function can be very destructive if not used
properly!
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq raid.create /dev/md0 level=1 chunk=256 devices="[\(aq/dev/xvdd\(aq, \(aq/dev/xvde\(aq]" test_mode=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Adding \fBtest_mode=True\fP as an argument will print out the mdadm
command that would have been run.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
The name of the array to create.
.TP
.B level
The RAID level to use when creating the raid.
.TP
.B devices
A list of devices used to build the array.
.TP
.B kwargs
Optional arguments to be passed to mdadm.
.TP
.B returns
.INDENT 7.0
.TP
.B test_mode=True:
Prints out the full command.
.TP
.B test_mode=False (Default):
Executes command on remote the host(s) and
Prints out the mdadm output.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
It takes time to create a RAID array. You can check the progress in
"resync_status:" field of the results from the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq raid.detail /dev/md0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For more info, read the \fBmdadm(8)\fP manpage
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mdadm.destroy(device)
Destroy a RAID device.
.sp
WARNING This will zero the superblock of all members of the RAID array..
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq raid.destroy /dev/md0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mdadm.detail(device=\(aq/dev/md0\(aq)
Show detail for a specified RAID device
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq raid.detail \(aq/dev/md0\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mdadm.list_()
List the RAID devices.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq raid.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mdadm.save_config()
Save RAID configuration to config file.
.sp
Same as:
mdadm \-\-detail \-\-scan >> /etc/mdadm/mdadm.conf
.sp
Fixes this issue with Ubuntu
REF: \fI\%http://askubuntu.com/questions/209702/why\-is\-my\-raid\-dev\-md1\-showing\-up\-as\-dev\-md126\-is\-mdadm\-conf\-being\-ignored\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq raid.save_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.memcached
.SS Module for Management of Memcached Keys
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B salt.modules.memcached.add(key, value, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0)
Add a key to the memcached server, but only if it does not exist. Returns
False if the key already exists.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.add <key> <value>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.decrement(key, delta=1, host=\(aq127.0.0.1\(aq, port=11211)
Decrement the value of a key
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.decrement <key>
salt \(aq*\(aq memcached.decrement <key> 2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.delete(key, host=\(aq127.0.0.1\(aq, port=11211, time=0)
Delete a key from memcache server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.delete <key>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.get(key, host=\(aq127.0.0.1\(aq, port=11211)
Retrieve value for a key
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.get <key>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.increment(key, delta=1, host=\(aq127.0.0.1\(aq, port=11211)
Increment the value of a key
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.increment <key>
salt \(aq*\(aq memcached.increment <key> 2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.replace(key, value, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0)
Replace a key on the memcached server. This only succeeds if the key
already exists. This is the opposite of \fI\%memcached.add\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.replace <key> <value>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.set_(key, value, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0)
Set a key on the memcached server, overwriting the value if it exists.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.set <key> <value>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.status(host=\(aq127.0.0.1\(aq, port=11211)
Get memcached status
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq memcached.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.mine
.sp
The function cache system allows for data to be stored on the master so it can be easily read by other minions
.INDENT 0.0
.TP
.B salt.modules.mine.delete(fun)
Remove specific function contents of minion. Returns True on success.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mine.delete \(aqnetwork.interfaces\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mine.flush()
Remove all mine contents of minion. Returns True on success.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mine.flush
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mine.get(tgt, fun, expr_form=\(aqglob\(aq)
Get data from the mine based on the target, function and expr_form
.sp
Targets can be matched based on any standard matching system that can be
matched on the master via these keywords:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
glob
pcre
grain
grain_pcre
compound
pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that all pillar matches, whether using the compound matching system or
the pillar matching system, will be exact matches, with globbing disabled.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mine.get \(aq*\(aq network.interfaces
salt \(aq*\(aq mine.get \(aqos:Fedora\(aq network.interfaces grain
salt \(aq*\(aq mine.get \(aqos:Fedora and S@192.168.5.0/24\(aq network.ipaddrs compound
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mine.get_docker(interfaces=None, cidrs=None)
Get all mine data for \(aqdocker.get_containers\(aq and run an aggregation
routine. The "interfaces" parameter allows for specifying which network
interfaces to select ip addresses from. The "cidrs" parameter allows for
specifying a list of cidrs which the ip address must match.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mine.get_docker
salt \(aq*\(aq mine.get_docker interfaces=\(aqeth0\(aq
salt \(aq*\(aq mine.get_docker interfaces=\(aq["eth0", "eth1"]\(aq
salt \(aq*\(aq mine.get_docker cidrs=\(aq107.170.147.0/24\(aq
salt \(aq*\(aq mine.get_docker cidrs=\(aq["107.170.147.0/24", "172.17.42.0/24"]\(aq
salt \(aq*\(aq mine.get_docker interfaces=\(aq["eth0", "eth1"]\(aq cidrs=\(aq["107.170.147.0/24", "172.17.42.0/24"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mine.send(func, *args, **kwargs)
Send a specific function to the mine.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mine.send network.interfaces eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mine.update(clear=False)
Execute the configured functions and send the data back up to the master
The functions to be executed are merged from the master config, pillar and
minion config under the option "function_cache":
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mine_functions:
network.ip_addrs:
\- eth0
disk.usage: []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The function cache will be populated with information from executing these
functions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mine.update
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.mod_random
.sp
New in version 2014.7.0.
.sp
Provides access to randomness generators.
.INDENT 0.0
.TP
.B salt.modules.mod_random.get_str(length=20)
New in version 2014.7.0.
.sp
Returns a random string of the specified length.
.INDENT 7.0
.TP
.B length
20
Any valid number of bytes.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq random.get_str 128
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mod_random.hash(value, algorithm=\(aqsha512\(aq)
New in version 2014.7.0.
.sp
Encodes a value with the specified encoder.
.INDENT 7.0
.TP
.B value
The value to be hashed.
.TP
.B algorithm
sha512
The algorithm to use. May be any valid algorithm supported by
hashlib.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq random.hash \(aqI am a string\(aq md5
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mod_random.shadow_hash(crypt_salt=None, password=None, algorithm=\(aqsha512\(aq)
Generates a salted hash suitable for /etc/shadow.
.INDENT 7.0
.TP
.B crypt_salt
None
Salt to be used in the generation of the hash. If one is not
provided, a random salt will be generated.
.TP
.B password
None
Value to be salted and hashed. If one is not provided, a random
password will be generated.
.TP
.B algorithm
sha512
Hash algorithm to use.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq random.shadow_hash \(aqMy5alT\(aq \(aqMyP@asswd\(aq md5
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mod_random.str_encode(value, encoder=\(aqbase64\(aq)
New in version 2014.7.0.
.INDENT 7.0
.TP
.B value
The value to be encoded.
.TP
.B encoder
base64
The encoder to use on the subsequent string.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq random.str_encode \(aqI am a new string\(aq base64
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.modjk
.sp
Control Modjk via the Apache Tomcat "Status" worker
(\fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP)
.sp
Below is an example of the configuration needed for this module. This
configuration data can be placed either in \fBgrains\fP or \fBpillar\fP\&.
.sp
If using grains, this can be accomplished \fIstatically\fP or via a \fIgrain module\fP\&.
.sp
If using pillar, the yaml configuration can be placed directly into a pillar
SLS file, making this both the easier and more dynamic method of configuring
this module.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
modjk:
default:
url: http://localhost/jkstatus
user: modjk
pass: secret
realm: authentication realm for digest passwords
timeout: 5
otherVhost:
url: http://otherVhost/jkstatus
user: modjk
pass: secret2
realm: authentication realm2 for digest passwords
timeout: 600
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.bulk_activate(workers, lbn, profile=\(aqdefault\(aq)
Activate all the given workers in the specific load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.bulk_activate node1,node2,node3 loadbalancer1
salt \(aq*\(aq modjk.bulk_activate node1,node2,node3 loadbalancer1 other\-profile
salt \(aq*\(aq modjk.bulk_activate ["node1","node2","node3"] loadbalancer1
salt \(aq*\(aq modjk.bulk_activate ["node1","node2","node3"] loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.bulk_disable(workers, lbn, profile=\(aqdefault\(aq)
Disable all the given workers in the specific load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.bulk_disable node1,node2,node3 loadbalancer1
salt \(aq*\(aq modjk.bulk_disable node1,node2,node3 loadbalancer1 other\-profile
salt \(aq*\(aq modjk.bulk_disable ["node1","node2","node3"] loadbalancer1
salt \(aq*\(aq modjk.bulk_disable ["node1","node2","node3"] loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.bulk_recover(workers, lbn, profile=\(aqdefault\(aq)
Recover all the given workers in the specific load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.bulk_recover node1,node2,node3 loadbalancer1
salt \(aq*\(aq modjk.bulk_recover node1,node2,node3 loadbalancer1 other\-profile
salt \(aq*\(aq modjk.bulk_recover ["node1","node2","node3"] loadbalancer1
salt \(aq*\(aq modjk.bulk_recover ["node1","node2","node3"] loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.bulk_stop(workers, lbn, profile=\(aqdefault\(aq)
Stop all the given workers in the specific load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.bulk_stop node1,node2,node3 loadbalancer1
salt \(aq*\(aq modjk.bulk_stop node1,node2,node3 loadbalancer1 other\-profile
salt \(aq*\(aq modjk.bulk_stop ["node1","node2","node3"] loadbalancer1
salt \(aq*\(aq modjk.bulk_stop ["node1","node2","node3"] loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.dump_config(profile=\(aqdefault\(aq)
Dump the original configuration that was loaded from disk
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.dump_config
salt \(aq*\(aq modjk.dump_config other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.get_running(profile=\(aqdefault\(aq)
Get the current running config (not from disk)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.get_running
salt \(aq*\(aq modjk.get_running other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.lb_edit(lbn, settings, profile=\(aqdefault\(aq)
Edit the loadbalancer settings
.sp
Note: \fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP
Data Parameters for the standard Update Action
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.lb_edit loadbalancer1 "{\(aqvlr\(aq: 1, \(aqvlt\(aq: 60}"
salt \(aq*\(aq modjk.lb_edit loadbalancer1 "{\(aqvlr\(aq: 1, \(aqvlt\(aq: 60}" other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.list_configured_members(lbn, profile=\(aqdefault\(aq)
Return a list of member workers from the configuration files
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.list_configured_members loadbalancer1
salt \(aq*\(aq modjk.list_configured_members loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.recover_all(lbn, profile=\(aqdefault\(aq)
Set the all the workers in lbn to recover and activate them if they are not
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.recover_all loadbalancer1
salt \(aq*\(aq modjk.recover_all loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.reset_stats(lbn, profile=\(aqdefault\(aq)
Reset all runtime statistics for the load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.reset_stats loadbalancer1
salt \(aq*\(aq modjk.reset_stats loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.version(profile=\(aqdefault\(aq)
Return the modjk version
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.version
salt \(aq*\(aq modjk.version other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.worker_activate(worker, lbn, profile=\(aqdefault\(aq)
Set the worker to activate state in the lbn load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1
salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.worker_disable(worker, lbn, profile=\(aqdefault\(aq)
Set the worker to disable state in the lbn load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.worker_disable node1 loadbalancer1
salt \(aq*\(aq modjk.worker_disable node1 loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.worker_edit(worker, lbn, settings, profile=\(aqdefault\(aq)
Edit the worker settings
.sp
Note: \fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP
Data Parameters for the standard Update Action
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.worker_edit node1 loadbalancer1 "{\(aqvwf\(aq: 500, \(aqvwd\(aq: 60}"
salt \(aq*\(aq modjk.worker_edit node1 loadbalancer1 "{\(aqvwf\(aq: 500, \(aqvwd\(aq: 60}" other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.worker_recover(worker, lbn, profile=\(aqdefault\(aq)
Set the worker to recover
this module will fail if it is in OK state
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.worker_recover node1 loadbalancer1
salt \(aq*\(aq modjk.worker_recover node1 loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.worker_status(worker, profile=\(aqdefault\(aq)
Return the state of the worker
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.worker_status node1
salt \(aq*\(aq modjk.worker_status node1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.worker_stop(worker, lbn, profile=\(aqdefault\(aq)
Set the worker to stopped state in the lbn load balancer
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1
salt \(aq*\(aq modjk.worker_activate node1 loadbalancer1 other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.modjk.workers(profile=\(aqdefault\(aq)
Return a list of member workers and their status
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq modjk.workers
salt \(aq*\(aq modjk.workers other\-profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.mongodb
.sp
Module to provide MongoDB functionality to Salt
.INDENT 0.0
.TP
.B configuration
This module uses PyMongo, and accepts configuration details as
parameters as well as configuration settings:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mongodb.host: \(aqlocalhost\(aq
mongodb.port: 27017
mongodb.user: \(aq\(aq
mongodb.password: \(aq\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This data can also be passed into pillar. Options passed into opts will
overwrite options passed into pillar.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mongodb.db_exists(name, user=None, password=None, host=None, port=None)
Checks if a database exists in Mongodb
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mongodb.db_exists <name> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mongodb.db_list(user=None, password=None, host=None, port=None)
List all Mongodb databases
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mongodb.db_list <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mongodb.db_remove(name, user=None, password=None, host=None, port=None)
Remove a Mongodb database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mongodb.db_remove <name> <user> <password> <host> <port>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mongodb.user_create(name, passwd, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq)
Create a Mongodb user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mongodb.user_create <name> <user> <password> <host> <port> <database>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mongodb.user_exists(name, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq)
Checks if a user exists in Mongodb
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mongodb.user_exists <name> <user> <password> <host> <port> <database>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mongodb.user_list(user=None, password=None, host=None, port=None, database=\(aqadmin\(aq)
List users of a Mongodb database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mongodb.user_list <user> <password> <host> <port> <database>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mongodb.user_remove(name, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq)
Remove a Mongodb user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mongodb.user_remove <name> <user> <password> <host> <port> <database>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.monit
.sp
Monit service module. This module will create a monit type
service watcher.
.INDENT 0.0
.TP
.B salt.modules.monit.monitor(name)
monitor service via monit
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq monit.monitor <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.monit.restart(name)
Restart service via monit
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq monit.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.monit.start(name)
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq monit.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.monit.stop(name)
Stops service via monit
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq monit.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.monit.summary(svc_name=\(aq\(aq)
Display a summary from monit
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq monit.summary
salt \(aq*\(aq monit.summary <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.monit.unmonitor(name)
Unmonitor service via monit
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq monit.unmonitor <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq moosefs.dirinfo /path/to/dir/ [\-[n][h|H]]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.moosefs.fileinfo(path)
Return information on a file located on the Moose
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq moosefs.fileinfo /path/to/dir/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.moosefs.getgoal(path, opts=None)
Return goal(s) for a file or directory
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.moosefs.mounts()
Return a list of current MooseFS mounts
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq moosefs.mounts
.ft P
.fi
.UNINDENT
.UNINDENT
.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(extended=False)
List the active mounts.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.active
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.fstab(config=\(aq/etc/fstab\(aq)
List the contents of the fstab
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.fstab
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.is_fuse_exec sshfs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.is_mounted(name)
New in version 2014.7.0.
.sp
Provide information if the path is mounted
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.is_mounted /mnt/share
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.mount /mnt/foo /dev/sdz1 True
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.remount /mnt/foo /dev/sdz1 True
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.rm_fstab /mnt/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.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, test=False, **kwargs)
Verify that this mount is represented in the fstab, change the mount
to match the data passed, or add the mount if it is not present.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.set_fstab /mnt/foo /dev/sdz1 ext4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.swapoff(name)
Deactivate a named swap mount
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.swapoff /root/swapfile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.swapon(name, priority=None)
Activate a swap disk
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.swapon /root/swapfile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.swaps()
Return a dict containing information on active swap
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.swaps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mount.umount(name)
Attempt to unmount a device by specifying the directory it is mounted on
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mount.umount /mnt/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.munin
.sp
Run munin plugins/checks from salt and format the output as data.
.INDENT 0.0
.TP
.B salt.modules.munin.list_plugins()
List all the munin plugins
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq munin.list_plugins
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.munin.run(plugins)
Run one or more named munin plugins
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq munin.run uptime
salt \(aq*\(aq munin.run uptime,cpu,load,memory
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.munin.run_all()
Run all the munin plugins
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq munin.run_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.mysql
.sp
Module to provide MySQL compatibility to salt.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
MySQLdb Python module
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
On CentOS 5 (and possibly RHEL 5) both MySQL\-python and python26\-mysqldb
need to be installed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B configuration
In order to connect to MySQL, certain configuration is required
in /etc/salt/minion on the relevant minions. Some sample configs might look
like:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mysql.host: \(aqlocalhost\(aq
mysql.port: 3306
mysql.user: \(aqroot\(aq
mysql.pass: \(aq\(aq
mysql.db: \(aqmysql\(aq
mysql.unix_socket: \(aq/tmp/mysql.sock\(aq
mysql.charset: \(aqutf8\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also use a defaults file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mysql.default_file: \(aq/etc/mysql/debian.cnf\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.1.0: charset connection argument added. This is a MySQL charset, not a python one
.sp
Changed in version 0.16.2: Connection arguments from the minion config file can be overridden on the
CLI by using the arguments defined \fBhere\fP\&. Additionally, it is now possible
to setup a user with no password.
.INDENT 0.0
.TP
.B salt.modules.mysql.db_check(name, table=None, **connection_args)
Repairs the full database or just a given table
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_check dbname
salt \(aq*\(aq mysql.db_check dbname dbtable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.db_create(name, character_set=None, collate=None, **connection_args)
Adds a databases to the MySQL server.
.INDENT 7.0
.TP
.B name
The name of the database to manage
.TP
.B character_set
The character set, if left empty the MySQL default will be used
.TP
.B collate
The collation, if left empty the MySQL default will be used
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_create \(aqdbname\(aq
salt \(aq*\(aq mysql.db_create \(aqdbname\(aq \(aqutf8\(aq \(aqutf8_general_ci\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.db_exists(name, **connection_args)
Checks if a database exists on the MySQL server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_exists \(aqdbname\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.db_list(**connection_args)
Return a list of databases of a MySQL server using the output
from the \fBSHOW DATABASES\fP query.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.db_optimize(name, table=None, **connection_args)
Optimizes the full database or just a given table
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_optimize dbname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.db_remove(name, **connection_args)
Removes a databases from the MySQL server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_remove \(aqdbname\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.db_repair(name, table=None, **connection_args)
Repairs the full database or just a given table
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_repair dbname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.db_tables(name, **connection_args)
Shows the tables in the given MySQL database (if exists)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.db_tables \(aqdatabase\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.free_slave(**connection_args)
Frees a slave from its master. This is a WIP, do not use.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.free_slave
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.get_master_status(**connection_args)
Retrieves the master status from the minion.
.INDENT 7.0
.TP
.B Returns:
.INDENT 7.0
.TP
.B {\(aqhost.domain.com\(aq: {\(aqBinlog_Do_DB\(aq: \(aq\(aq,
\(aqBinlog_Ignore_DB\(aq: \(aq\(aq,
\(aqFile\(aq: \(aqmysql\-bin.000021\(aq,
\(aqPosition\(aq: 107}}
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.get_master_status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.get_slave_status(**connection_args)
Retrieves the slave status from the minion.
.sp
Returns:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqhost.domain.com\(aq: {\(aqConnect_Retry\(aq: 60,
\(aqExec_Master_Log_Pos\(aq: 107,
\(aqLast_Errno\(aq: 0,
\(aqLast_Error\(aq: \(aq\(aq,
\(aqLast_IO_Errno\(aq: 0,
\(aqLast_IO_Error\(aq: \(aq\(aq,
\(aqLast_SQL_Errno\(aq: 0,
\(aqLast_SQL_Error\(aq: \(aq\(aq,
\(aqMaster_Host\(aq: \(aqcomet.scion\-eng.com\(aq,
\(aqMaster_Log_File\(aq: \(aqmysql\-bin.000021\(aq,
\(aqMaster_Port\(aq: 3306,
\(aqMaster_SSL_Allowed\(aq: \(aqNo\(aq,
\(aqMaster_SSL_CA_File\(aq: \(aq\(aq,
\(aqMaster_SSL_CA_Path\(aq: \(aq\(aq,
\(aqMaster_SSL_Cert\(aq: \(aq\(aq,
\(aqMaster_SSL_Cipher\(aq: \(aq\(aq,
\(aqMaster_SSL_Key\(aq: \(aq\(aq,
\(aqMaster_SSL_Verify_Server_Cert\(aq: \(aqNo\(aq,
\(aqMaster_Server_Id\(aq: 1,
\(aqMaster_User\(aq: \(aqreplu\(aq,
\(aqRead_Master_Log_Pos\(aq: 107,
\(aqRelay_Log_File\(aq: \(aqklo\-relay\-bin.000071\(aq,
\(aqRelay_Log_Pos\(aq: 253,
\(aqRelay_Log_Space\(aq: 553,
\(aqRelay_Master_Log_File\(aq: \(aqmysql\-bin.000021\(aq,
\(aqReplicate_Do_DB\(aq: \(aq\(aq,
\(aqReplicate_Do_Table\(aq: \(aq\(aq,
\(aqReplicate_Ignore_DB\(aq: \(aq\(aq,
\(aqReplicate_Ignore_Server_Ids\(aq: \(aq\(aq,
\(aqReplicate_Ignore_Table\(aq: \(aq\(aq,
\(aqReplicate_Wild_Do_Table\(aq: \(aq\(aq,
\(aqReplicate_Wild_Ignore_Table\(aq: \(aq\(aq,
\(aqSeconds_Behind_Master\(aq: 0,
\(aqSkip_Counter\(aq: 0,
\(aqSlave_IO_Running\(aq: \(aqYes\(aq,
\(aqSlave_IO_State\(aq: \(aqWaiting for master to send event\(aq,
\(aqSlave_SQL_Running\(aq: \(aqYes\(aq,
\(aqUntil_Condition\(aq: \(aqNone\(aq,
\(aqUntil_Log_File\(aq: \(aq\(aq,
\(aqUntil_Log_Pos\(aq: 0}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.get_slave_status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.grant_add(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True, ssl_option=False, **connection_args)
Adds a grant to the MySQL server.
.sp
For database, make sure you specify database.table or database.*
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.grant_add \(aqSELECT,INSERT,UPDATE,...\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.grant_exists(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True, **connection_args)
Checks to see if a grant exists in the database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.grant_exists \(aqSELECT,INSERT,UPDATE,...\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.grant_revoke(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True, **connection_args)
Removes a grant from the MySQL server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.grant_revoke \(aqSELECT,INSERT,UPDATE\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.processlist(**connection_args)
Retrieves the processlist from the MySQL server via
"SHOW FULL PROCESSLIST".
.INDENT 7.0
.TP
.B Returns: a list of dicts, with each dict representing a process:
.INDENT 7.0
.TP
.B {\(aqCommand\(aq: \(aqQuery\(aq,
\(aqHost\(aq: \(aqlocalhost\(aq,
\(aqId\(aq: 39,
\(aqInfo\(aq: \(aqSHOW FULL PROCESSLIST\(aq,
\(aqRows_examined\(aq: 0,
\(aqRows_read\(aq: 1,
\(aqRows_sent\(aq: 0,
\(aqState\(aq: None,
\(aqTime\(aq: 0,
\(aqUser\(aq: \(aqroot\(aq,
\(aqdb\(aq: \(aqmysql\(aq}
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.processlist
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.query(database, query, **connection_args)
Run an arbitrary SQL query and return the results or
the number of affected rows.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.query mydb "UPDATE mytable set myfield=1 limit 1"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Return data:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqquery time\(aq: {\(aqhuman\(aq: \(aq39.0ms\(aq, \(aqraw\(aq: \(aq0.03899\(aq}, \(aqrows affected\(aq: 1L}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.query mydb "SELECT id,name,cash from users limit 3"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Return data:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqcolumns\(aq: (\(aqid\(aq, \(aqname\(aq, \(aqcash\(aq),
\(aqquery time\(aq: {\(aqhuman\(aq: \(aq1.0ms\(aq, \(aqraw\(aq: \(aq0.001\(aq},
\(aqresults\(aq: ((1L, \(aqUser 1\(aq, Decimal(\(aq110.000000\(aq)),
(2L, \(aqUser 2\(aq, Decimal(\(aq215.636756\(aq)),
(3L, \(aqUser 3\(aq, Decimal(\(aq0.040000\(aq))),
\(aqrows returned\(aq: 3L}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.query mydb \(aqINSERT into users values (null,"user 4", 5)\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Return data:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqquery time\(aq: {\(aqhuman\(aq: \(aq25.6ms\(aq, \(aqraw\(aq: \(aq0.02563\(aq}, \(aqrows affected\(aq: 1L}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.query mydb \(aqDELETE from users where id = 4 limit 1\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Return data:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqquery time\(aq: {\(aqhuman\(aq: \(aq39.0ms\(aq, \(aqraw\(aq: \(aq0.03899\(aq}, \(aqrows affected\(aq: 1L}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Jinja Example: Run a query on \fBmydb\fP and use row 0, column 0\(aqs data.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{{ salt[\(aqmysql.query\(aq](\(aqmydb\(aq, \(aqSELECT info from mytable limit 1\(aq)[\(aqresults\(aq][0][0] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.quote_identifier(identifier, for_grants=False)
Return an identifier name (column, table, database, etc) escaped for MySQL
.sp
This means surrounded by "\(ga" character and escaping this character inside.
It also means doubling the \(aq%\(aq character for MySQLdb internal usage.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBidentifier\fP \-\- the table, column or database identifier
.IP \(bu 2
\fBfor_grants\fP \-\- is False by default, when using database names on grant
queries you should set it to True to also escape "_" and "%" characters as
requested by MySQL. Note that theses characters should only be escaped when
requesting grants on the database level (\fImy_%db\fP\&.*) but not for table
level grants (\fImy_%db\fP\&.\(gafoo\(ga)
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.quote_identifier \(aqfoo\(gabar\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.showglobal(**connection_args)
Retrieves the show global variables from the minion.
.INDENT 7.0
.TP
.B Returns::
show global variables full dict
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.showglobal
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.showvariables(**connection_args)
Retrieves the show variables from the minion.
.INDENT 7.0
.TP
.B Returns::
show variables full dict
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.showvariables
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.slave_lag(**connection_args)
Return the number of seconds that a slave SQL server is lagging behind the
master, if the host is not a slave it will return \-1. If the server is
configured to be a slave for replication but slave IO is not running then
\-2 will be returned. If there was an error connecting to the database or
checking the slave status, \-3 will be returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.slave_lag
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.status(**connection_args)
Return the status of a MySQL server using the output from the \fBSHOW
STATUS\fP query.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.tokenize_grant(grant)
External wrapper function
:param grant:
:return: dict
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.tokenize_grant "GRANT SELECT, INSERT ON testdb.* TO \(aqtestuser\(aq@\(aqlocalhost\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.user_chpass(user, host=\(aqlocalhost\(aq, password=None, password_hash=None, allow_passwordless=False, unix_socket=None, **connection_args)
Change password for a MySQL user
.INDENT 7.0
.TP
.B host
Host for which this user/password combo applies
.TP
.B password
The password to set for the new user. Will take precedence over the
\fBpassword_hash\fP option if both are specified.
.TP
.B password_hash
The password in hashed form. Be sure to quote the password because YAML
doesn\(aqt like the \fB*\fP\&. A password hash can be obtained from the mysql
command\-line client like so:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mysql> SELECT PASSWORD(\(aqmypass\(aq);
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| PASSWORD(\(aqmypass\(aq) |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
1 row in set (0.00 sec)
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B allow_passwordless
If \fBTrue\fP, then \fBpassword\fP and \fBpassword_hash\fP can be omitted (or
set to \fBNone\fP) to permit a passwordless login.
.UNINDENT
.sp
New in version 0.16.2: The \fBallow_passwordless\fP option was added.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.user_chpass frank localhost newpassword
salt \(aq*\(aq mysql.user_chpass frank localhost password_hash=\(aqhash\(aq
salt \(aq*\(aq mysql.user_chpass frank localhost allow_passwordless=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.user_create(user, host=\(aqlocalhost\(aq, password=None, password_hash=None, allow_passwordless=False, unix_socket=False, **connection_args)
Creates a MySQL user
.INDENT 7.0
.TP
.B host
Host for which this user/password combo applies
.TP
.B password
The password to use for the new user. Will take precedence over the
\fBpassword_hash\fP option if both are specified.
.TP
.B password_hash
The password in hashed form. Be sure to quote the password because YAML
doesn\(aqt like the \fB*\fP\&. A password hash can be obtained from the mysql
command\-line client like so:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mysql> SELECT PASSWORD(\(aqmypass\(aq);
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| PASSWORD(\(aqmypass\(aq) |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
1 row in set (0.00 sec)
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B allow_passwordless
If \fBTrue\fP, then \fBpassword\fP and \fBpassword_hash\fP can be omitted (or
set to \fBNone\fP) to permit a passwordless login.
.TP
.B unix_socket
If \fBTrue\fP and allow_passwordless is \fBTrue\fP then will be used unix_socket auth plugin.
.UNINDENT
.sp
New in version 0.16.2: The \fBallow_passwordless\fP option was added.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq \(aqpassword\(aq
salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq password_hash=\(aqhash\(aq
salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq allow_passwordless=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.user_exists(user, host=\(aqlocalhost\(aq, password=None, password_hash=None, passwordless=False, unix_socket=False, **connection_args)
Checks if a user exists on the MySQL server. A login can be checked to see
if passwordless login is permitted by omitting \fBpassword\fP and
\fBpassword_hash\fP, and using \fBpasswordless=True\fP\&.
.sp
New in version 0.16.2: The \fBpasswordless\fP option was added.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.user_exists \(aqusername\(aq \(aqhostname\(aq \(aqpassword\(aq
salt \(aq*\(aq mysql.user_exists \(aqusername\(aq \(aqhostname\(aq password_hash=\(aqhash\(aq
salt \(aq*\(aq mysql.user_exists \(aqusername\(aq passwordless=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.user_grants(user, host=\(aqlocalhost\(aq, **connection_args)
Shows the grants for the given MySQL user (if it exists)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.user_grants \(aqfrank\(aq \(aqlocalhost\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.user_info(user, host=\(aqlocalhost\(aq, **connection_args)
Get full info on a MySQL user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.user_info root localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.user_list(**connection_args)
Return a list of users on a MySQL server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.user_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.user_remove(user, host=\(aqlocalhost\(aq, **connection_args)
Delete MySQL user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.user_remove frank localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.version(**connection_args)
Return the version of a MySQL server using the output from the \fBSELECT
VERSION()\fP query.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq mysql.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.nagios
.sp
Run nagios plugins/checks from salt and get the return as data.
.INDENT 0.0
.TP
.B salt.modules.nagios.list_plugins()
List all the nagios plugins
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nagios.list_plugins
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nagios.retcode(plugin, args=\(aq\(aq, key_name=None)
Run one nagios plugin and return retcode of the execution
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nagios.run check_apt
salt \(aq*\(aq nagios.run check_icmp \(aq8.8.8.8\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nagios.retcode_pillar(pillar_name)
Run one or more nagios plugins from pillar data and get the result of cmd.retcode
The pillar have to be in this format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-
webserver:
Ping_google:
\- check_icmp:8.8.8.8
\- check_icmp:google.com
Load:
\- check_load:\-w 0.8 \-c 1
APT:
\- check_apt
\-\-\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
webserver is the role to check, the next keys are the group and the items
the check with the arguments if needed
.sp
You must to group different checks(one o more) and always it will return
the highest value of all the checks
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nagios.retcode webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nagios.run(plugin, args=\(aq\(aq)
Run nagios plugin and return all the data execution with cmd.run
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nagios.run_all(plugin, args=\(aq\(aq)
Run nagios plugin and return all the data execution with cmd.run_all
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nagios.run_all_pillar(pillar_name)
Run one or more nagios plugins from pillar data and get the result of cmd.run_all
The pillar have to be in this format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-
webserver:
Ping_google:
\- check_icmp:8.8.8.8
\- check_icmp:google.com
Load:
\- check_load:\-w 0.8 \-c 1
APT:
\- check_apt
\-\-\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
webserver is the role to check, the next keys are the group and the items
the check with the arguments if needed
.sp
You have to group different checks in a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nagios.run webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nagios.run_pillar(pillar_name)
Run one or more nagios plugins from pillar data and get the result of cmd.run
The pillar have to be in this format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-
webserver:
Ping_google:
\- check_icmp:8.8.8.8
\- check_icmp:google.com
Load:
\- check_load:\-w 0.8 \-c 1
APT:
\- check_apt
\-\-\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
webserver is the role to check, the next keys are the group and the items
the check with the arguments if needed
.sp
You have to group different checks in a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nagios.run webserver
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.netbsd_sysctl
.sp
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
.B salt.modules.netbsd_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsd_sysctl.get(name)
Return a single sysctl parameter for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.get hw.physmem
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsd_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq)
Assign and persist a simple sysctl parameter for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsd_sysctl.show(config_file=False)
Return a list of sysctl parameters for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysctl.show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.netbsdservice
.sp
The service module for NetBSD
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.disable(name, **kwargs)
Disable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.disabled(name)
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.enable(name, **kwargs)
Enable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.enabled(name)
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.force_reload(name)
Force\-reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.force_reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.get_all()
Return all available boot services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.get_disabled()
Return a set of services that are installed but disabled
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.get_enabled()
Return a list of service that are enabled on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.reload_(name)
Reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.status(name, sig=None)
Return the status for a service, returns a bool whether the service is
running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.netbsdservice.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.network
.sp
Module for gathering and managing network information
.INDENT 0.0
.TP
.B salt.modules.network.active_tcp()
Return a dict containing information on all of the running TCP connections
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.active_tcp
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.arp()
Return the arp table from the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.arp
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.connect(host, port=None, **kwargs)
Test connectivity to a host using a particular
port from the minion.
.sp
New in version 2014.7.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.connect archlinux.org 80
salt \(aq*\(aq network.connect archlinux.org 80 timeout=3
salt \(aq*\(aq network.connect archlinux.org 80 timeout=3 family=ipv4
salt \(aq*\(aq network.connect google\-public\-dns\-a.google.com port=53 proto=udp timeout=3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.dig(host)
Performs a DNS lookup with dig
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.dig archlinux.org
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.get_hostname()
Get hostname
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.get_hostname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.hw_addr(iface)
Return the hardware address (a.k.a. MAC address) for a given interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.hw_addr eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.hwaddr(iface)
Return the hardware address (a.k.a. MAC address) for a given interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.hw_addr eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.in_subnet(cidr)
Returns True if host is within specified subnet, otherwise False.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.in_subnet 10.0.0.0/16
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.interface(iface)
Return the inet address for a given interface
.sp
New in version 2014.7.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.interface eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.interface_ip(iface)
Return the inet address for a given interface
.sp
New in version 2014.7.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.interface_ip eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.interfaces()
Return a dictionary of information about all the interfaces on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.ip_addrs(interface=None, include_loopback=False, cidr=None)
Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is
ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is
provided, then only IP addresses from that interface will be returned.
Providing a CIDR via \(aqcidr="10.0.0.0/8"\(aq will return only the addresses
which are within that subnet.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.ip_addrs6(interface=None, include_loopback=False)
Returns a list of IPv6 addresses assigned to the host. ::1 is ignored,
unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided,
then only IP addresses from that interface will be returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.ipaddrs(interface=None, include_loopback=False, cidr=None)
Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is
ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is
provided, then only IP addresses from that interface will be returned.
Providing a CIDR via \(aqcidr="10.0.0.0/8"\(aq will return only the addresses
which are within that subnet.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.ipaddrs6(interface=None, include_loopback=False)
Returns a list of IPv6 addresses assigned to the host. ::1 is ignored,
unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided,
then only IP addresses from that interface will be returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.is_loopback(ip_addr)
Check if the given IP address is a loopback address
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.is_loopback 127.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.is_private(ip_addr)
Check if the given IP address is a private address
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.is_private 10.0.0.3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.mod_hostname(hostname)
Modify hostname
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.mod_hostname master.saltstack.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.netstat()
Return information on open ports and states
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
On BSD minions, the output contains PID info (where available) for each
netstat entry, fetched from sockstat/fstat output.
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.1.4: Added support for OpenBSD, FreeBSD, and NetBSD
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.netstat
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.ping(host)
Performs a ping to a host
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ping archlinux.org
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.subnets()
Returns a list of subnets to which the host belongs
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.subnets
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.network.traceroute(host)
Performs a traceroute to a 3rd party host
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.traceroute archlinux.org
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.nfs3
.sp
Module for managing NFS version 3.
.INDENT 0.0
.TP
.B salt.modules.nfs3.del_export(exports=\(aq/etc/exports\(aq, path=None)
Remove an export
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nfs.del_export /media/storage
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nfs3.list_exports(exports=\(aq/etc/exports\(aq)
List configured exports
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nfs.list_exports
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.nftables
.sp
Support for nftables
.INDENT 0.0
.TP
.B salt.modules.nftables.append(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq)
Append a rule to the specified table & chain.
.INDENT 7.0
.TP
.B This function accepts a rule in a standard nftables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.append filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq
IPv6:
salt \(aq*\(aq nftables.append filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.build_rule(table=None, chain=None, command=None, position=\(aq\(aq, full=None, family=\(aqipv4\(aq, **kwargs)
Build a well\-formatted nftables rule based on kwargs.
A \fItable\fP and \fIchain\fP are not required, unless \fIfull\fP is True.
.sp
If \fIfull\fP is \fITrue\fP, then \fItable\fP, \fIchain\fP and \fIcommand\fP are required.
\fIcommand\fP may be specified as either insert, append, or delete.
This will return the nftables command, exactly as it would
be used from the command line.
.sp
If a position is required (as with \fIinsert\fP or \fIdelete\fP), it may be specified as
\fIposition\fP\&. This will only be useful if \fIfull\fP is True.
.sp
If \fIconnstate\fP is passed in, it will automatically be changed to \fIstate\fP\&.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.build_rule match=state \e
connstate=RELATED,ESTABLISHED jump=ACCEPT
salt \(aq*\(aq nftables.build_rule filter input command=insert position=3 \e
full=True match=state state=related,established jump=accept
IPv6:
salt \(aq*\(aq nftables.build_rule match=state \e
connstate=related,established jump=accept \e
family=ipv6
salt \(aq*\(aq nftables.build_rule filter input command=insert position=3 \e
full=True match=state state=related,established jump=accept \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.check(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq)
Check for the existence of a rule in the table and chain
.INDENT 7.0
.TP
.B This function accepts a rule in a standard nftables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.check filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq
IPv6:
salt \(aq*\(aq nftables.check filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.check_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Check for the existence of a chain in the table
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.check_chain filter input
IPv6:
salt \(aq*\(aq nftables.check_chain filter input family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.check_table(table=None, family=\(aqipv4\(aq)
Check for the existence of a table
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.check_table nat
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.delete(table, chain=None, position=None, rule=None, family=\(aqipv4\(aq)
.INDENT 7.0
.TP
.B Delete a rule from the specified table & chain, specifying either the rule
in its entirety, or the rule\(aqs position in the chain.
.TP
.B This function accepts a rule in a standard nftables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.delete filter input position=3
salt \(aq*\(aq nftables.delete filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq
IPv6:
salt \(aq*\(aq nftables.delete filter input position=3 family=ipv6
salt \(aq*\(aq nftables.delete filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.delete_chain(table=\(aqfilter\(aq, chain=None, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Delete the chain from the specified table.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.delete_chain filter input
salt \(aq*\(aq nftables.delete_chain filter foo
IPv6:
salt \(aq*\(aq nftables.delete_chain filter input family=ipv6
salt \(aq*\(aq nftables.delete_chain filter foo family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.delete_table(table, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Create new custom table.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.delete_table filter
IPv6:
salt \(aq*\(aq nftables.delete_table filter family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.flush(table=\(aqfilter\(aq, chain=\(aq\(aq, family=\(aqipv4\(aq)
Flush the chain in the specified table, flush all chains in the specified
table if chain is not specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.flush filter
salt \(aq*\(aq nftables.flush filter input
IPv6:
salt \(aq*\(aq nftables.flush filter input family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.get_rule_handle(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq)
Get the handle for a particular rule
.INDENT 7.0
.TP
.B This function accepts a rule in a standard nftables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.get_rule_handle filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq
IPv6:
salt \(aq*\(aq nftables.get_rule_handle filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.get_rules(family=\(aqipv4\(aq)
Return a data structure of the current, in\-memory rules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.get_rules
salt \(aq*\(aq nftables.get_rules family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.get_saved_rules(conf_file=None, family=\(aqipv4\(aq)
Return a data structure of the rules in the conf file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.get_saved_rules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.insert(table=\(aqfilter\(aq, chain=None, position=None, rule=None, family=\(aqipv4\(aq)
Insert a rule into the specified table & chain, at the specified position.
.sp
If position is not specified, rule will be inserted in first position.
.INDENT 7.0
.TP
.B This function accepts a rule in a standard nftables command format,
starting with the chain. Trying to force users to adapt to a new
method of creating rules would be irritating at best, and we
already have a parser that can handle it.
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.insert filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq
salt \(aq*\(aq nftables.insert filter input position=3 \e
rule=\(aqinput tcp dport 22 log accept\(aq
IPv6:
salt \(aq*\(aq nftables.insert filter input \e
rule=\(aqinput tcp dport 22 log accept\(aq \e
family=ipv6
salt \(aq*\(aq nftables.insert filter input position=3 \e
rule=\(aqinput tcp dport 22 log accept\(aq \e
family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.new_chain(table=\(aqfilter\(aq, chain=None, table_type=None, hook=None, priority=None, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Create new chain to the specified table.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.new_chain filter input
salt \(aq*\(aq nftables.new_chain filter input \e
table_type=filter hook=input priority=0
salt \(aq*\(aq nftables.new_chain filter foo
IPv6:
salt \(aq*\(aq nftables.new_chain filter input family=ipv6
salt \(aq*\(aq nftables.new_chain filter input \e
table_type=filter hook=input priority=0 family=ipv6
salt \(aq*\(aq nftables.new_chain filter foo family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.new_table(table, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Create new custom table.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.new_table filter
IPv6:
salt \(aq*\(aq nftables.new_table filter family=ipv6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.save(filename=None, family=\(aqipv4\(aq)
Save the current in\-memory rules to disk
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.save /etc/nftables
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nftables.version()
Return version from nftables \-\-version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nftables.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.nginx
.sp
Support for nginx
.INDENT 0.0
.TP
.B salt.modules.nginx.configtest()
test configuration and exit
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nginx.configtest
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nginx.signal(signal=None)
Signals nginx to start, reload, reopen or stop.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nginx.signal reload
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nginx.status(url=\(aqhttp://127.0.0.1/status\(aq)
Return the data from an Nginx status page as a dictionary.
\fI\%http://wiki.nginx.org/HttpStubStatusModule\fP
.INDENT 7.0
.TP
.B url
The URL of the status page. Defaults to \(aq\fI\%http://127.0.0.1/status\fP\(aq
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nginx.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nginx.version()
Return server version from nginx \-v
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nginx.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.nova
.sp
Module for handling OpenStack Nova calls
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
novaclient Python module
.UNINDENT
.TP
.B configuration
This module is not usable until the user, password, tenant, and
auth URL are specified either in a pillar or in the minion\(aqs config file.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
# Optional
keystone.region_name: \(aqregionOne\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If configuration for multiple OpenStack accounts is required, they can be
set up as different configuration profiles:
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
openstack1:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
openstack2:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this configuration in place, any of the nova functions can make use of
a configuration profile by declaring it explicitly.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.flavor_list profile=openstack1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.boot(name, flavor_id=0, image_id=0, profile=None, timeout=300)
Boot (create) a new instance
.INDENT 7.0
.TP
.B name
Name of the new instance (must be first)
.TP
.B flavor_id
Unique integer ID for the flavor
.TP
.B image_id
Unique integer ID for the image
.TP
.B timeout
How long to wait, after creating the instance, for the provider to
return information about it (default 300 seconds).
.sp
New in version 2014.1.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.boot myinstance flavor_id=4596 image_id=2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The flavor_id and image_id are obtained from nova.flavor_list and
nova.image_list
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.flavor_list
salt \(aq*\(aq nova.image_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.delete(instance_id, profile=None)
Delete an instance
.INDENT 7.0
.TP
.B instance_id
ID of the instance to be deleted
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.delete 1138
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.flavor_create(name, flavor_id=0, ram=0, disk=0, vcpus=1, profile=None)
Add a flavor to nova (nova flavor\-create). The following parameters are
required:
.INDENT 7.0
.TP
.B name
Name of the new flavor (must be first)
.TP
.B flavor_id
Unique integer ID for the new flavor
.TP
.B ram
Memory size in MB
.TP
.B disk
Disk size in GB
.TP
.B vcpus
Number of vcpus
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.flavor_create myflavor flavor_id=6 ram=4096 disk=10 vcpus=1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.flavor_delete(flavor_id, profile=None)
Delete a flavor from nova by id (nova flavor\-delete)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.flavor_delete 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.flavor_list(profile=None)
Return a list of available flavors (nova flavor\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.flavor_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.image_list(name=None, profile=None)
Return a list of available images (nova images\-list + nova image\-show)
If a name is provided, only that image will be displayed.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.image_list
salt \(aq*\(aq nova.image_list myimage
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.image_meta_delete(image_id=None, name=None, keys=None, profile=None)
Delete a key=value pair from the metadata for an image
(nova image\-meta set)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.image_meta_delete 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 keys=cheese
salt \(aq*\(aq nova.image_meta_delete name=myimage keys=salad,beans
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.image_meta_set(image_id=None, name=None, profile=None, **kwargs)
Sets a key=value pair in the metadata for an image (nova image\-meta set)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.image_meta_set 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 cheese=gruyere
salt \(aq*\(aq nova.image_meta_set name=myimage salad=pasta beans=baked
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.keypair_add(name, pubfile=None, pubkey=None, profile=None)
Add a keypair to nova (nova keypair\-add)
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.keypair_add mykey pubfile=\(aq/home/myuser/.ssh/id_rsa.pub\(aq
salt \(aq*\(aq nova.keypair_add mykey pubkey=\(aqssh\-rsa <key> myuser@mybox\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.keypair_delete(name, profile=None)
Add a keypair to nova (nova keypair\-delete)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.keypair_delete mykey\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.keypair_list(profile=None)
Return a list of available keypairs (nova keypair\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.keypair_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.list_(profile=None)
To maintain the feel of the nova command line, this function simply calls
the server_list function.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.lock(instance_id, profile=None)
Lock an instance
.INDENT 7.0
.TP
.B instance_id
ID of the instance to be locked
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.lock 1138
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.resume(instance_id, profile=None)
Resume an instance
.INDENT 7.0
.TP
.B instance_id
ID of the instance to be resumed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.resume 1138
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.secgroup_create(name, description, profile=None)
Add a secgroup to nova (nova secgroup\-create)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.secgroup_create mygroup \(aqThis is my security group\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.secgroup_delete(name, profile=None)
Delete a secgroup to nova (nova secgroup\-delete)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.secgroup_delete mygroup
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.secgroup_list(profile=None)
Return a list of available security groups (nova items\-list)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.secgroup_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.server_by_name(name, profile=None)
Return information about a server
.INDENT 7.0
.TP
.B name
Server Name
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.server_by_name myserver profile=openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.server_list(profile=None)
Return list of active servers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.server_list_detailed(profile=None)
Return detailed list of active servers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.server_list_detailed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.server_show(server_id, profile=None)
Return detailed information for an active server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.server_show <server_id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.show(server_id, profile=None)
To maintain the feel of the nova command line, this function simply calls
the server_show function.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.suspend(instance_id, profile=None)
Suspend an instance
.INDENT 7.0
.TP
.B instance_id
ID of the instance to be suspended
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.suspend 1138
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.volume_attach(name, server_name, device=\(aq/dev/xvdb\(aq, profile=None, timeout=300)
Attach a block storage volume
.INDENT 7.0
.TP
.B name
Name of the new volume to attach
.TP
.B server_name
Name of the server to attach to
.TP
.B device
Name of the device on the server
.TP
.B profile
Profile to build on
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.volume_attach myblock slice.example.com profile=openstack
salt \(aq*\(aq nova.volume_attach myblock server.example.com device=\(aq/dev/xvdb\(aq profile=openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.volume_create(name, size=100, snapshot=None, voltype=None, profile=None)
Create a block storage volume
.INDENT 7.0
.TP
.B name
Name of the new volume (must be first)
.TP
.B size
Volume size
.TP
.B snapshot
Block storage snapshot id
.TP
.B voltype
Type of storage
.TP
.B profile
Profile to build on
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.volume_create myblock size=300 profile=openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.volume_delete(name, profile=None)
Destroy the volume
.INDENT 7.0
.TP
.B name
Name of the volume
.TP
.B profile
Profile to build on
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.volume_delete myblock profile=openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.volume_detach(name, profile=None, timeout=300)
Attach a block storage volume
.INDENT 7.0
.TP
.B name
Name of the new volume to attach
.TP
.B server_name
Name of the server to detach from
.TP
.B profile
Profile to build on
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.volume_detach myblock profile=openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.volume_list(search_opts=None, profile=None)
List storage volumes
.INDENT 7.0
.TP
.B search_opts
Dictionary of search options
.TP
.B profile
Profile to use
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.volume_list search_opts=\(aq{"display_name": "myblock"}\(aq profile=openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nova.volume_show(name, profile=None)
Create a block storage volume
.INDENT 7.0
.TP
.B name
Name of the volume
.TP
.B profile
Profile to use
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq nova.volume_show myblock profile=openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.npm
.sp
Manage and query NPM packages.
.INDENT 0.0
.TP
.B salt.modules.npm.install(pkg=None, pkgs=None, dir=None, runas=None, registry=None, env=None)
Install an NPM package.
.sp
If no directory is specified, the package will be installed globally. If
no package is specified, the dependencies (from package.json) of the
package in the given directory will be installed.
.INDENT 7.0
.TP
.B pkg
A package name in any format accepted by NPM, including a version
identifier
.TP
.B pkgs
A list of package names in the same format as the \fBname\fP parameter
.sp
New in version 2014.7.0.
.TP
.B dir
The target directory in which to install the package, or None for
global installation
.TP
.B runas
The user to run NPM with
.TP
.B registry
The NPM registry to install the package from.
.sp
New in version 2014.7.0.
.TP
.B env
Environment variables to set when invoking npm. Uses the same \fBenv\fP
format as the \fBcmd.run\fP execution
function.
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq npm.install coffee\-script
salt \(aq*\(aq npm.install coffee\-script@1.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.npm.list_(pkg=None, dir=None, runas=None, env=None)
List installed NPM packages.
.sp
If no directory is specified, this will return the list of globally\-
installed packages.
.INDENT 7.0
.TP
.B pkg
Limit package listing by name
.TP
.B dir
The directory whose packages will be listed, or None for global
installation
.TP
.B runas
The user to run NPM with
.sp
New in version 2014.7.0.
.TP
.B env
Environment variables to set when invoking npm. Uses the same \fBenv\fP
format as the \fBcmd.run\fP execution
function.
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq npm.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.npm.uninstall(pkg, dir=None, runas=None)
Uninstall an NPM package.
.sp
If no directory is specified, the package will be uninstalled globally.
.INDENT 7.0
.TP
.B pkg
A package name in any format accepted by NPM
.TP
.B dir
The target directory from which to uninstall the package, or None for
global installation
.TP
.B runas
The user to run NPM with
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq npm.uninstall coffee\-script
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.omapi
.sp
This module interacts with an ISC DHCP Server via OMAPI.
server_ip and server_port params may be set in the minion
config or pillar:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
omapi.server_ip: 127.0.0.1
omapi.server_port: 7991
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B depends
pypureomapi Python module
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.omapi.add_host(mac, name=None, ip=None, ddns=False, group=None, supersede_host=False)
Add a host object for the given mac.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt dhcp\-server omapi.add_host ab:ab:ab:ab:ab:ab name=host1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Add ddns\-hostname and a fixed\-ip statements:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt dhcp\-server omapi.add_host ab:ab:ab:ab:ab:ab name=host1 ip=10.1.1.1 ddns=true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.omapi.delete_host(mac=None, name=None)
Delete the host with the given mac or name.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt dhcp\-server omapi.delete_host name=host1
salt dhcp\-server omapi.delete_host mac=ab:ab:ab:ab:ab:ab
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.openbsdpkg
.sp
Package support for OpenBSD
.INDENT 0.0
.TP
.B salt.modules.openbsdpkg.install(name=None, pkgs=None, sources=None, **kwargs)
Install the passed package
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example, Install one package:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example, Install more than one package:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["<package name>", "<package name>"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example, Install more than one package from a alternate source (e.g. salt file\-server, HTTP, FTP, local filesystem):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"<pkg name>": "salt://pkgs/<pkg filename>"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdpkg.latest_version(*names, **kwargs)
The available version of the package in the repository
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdpkg.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdpkg.purge(name=None, pkgs=None, **kwargs)
Package purges are not supported, this function is identical to
\fBremove()\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdpkg.remove(name=None, pkgs=None, **kwargs)
Remove a single package with pkg_delete
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdpkg.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.openbsdservice
.sp
The service module for OpenBSD
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.available(name)
New in version 2014.7.0.
.sp
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.disabled(name)
New in version 2014.7.0.
.sp
Return True if the named service is disabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.enabled(name)
New in version 2014.7.0.
.sp
Return True if the named service is enabled, false otherwise
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.get_all()
New in version 2014.7.0.
.sp
Return all available boot services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.get_disabled()
New in version 2014.7.0.
.sp
Return a set of services that are installed but disabled
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.get_enabled()
New in version 2014.7.0.
.sp
Return a list of service that are enabled on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.missing(name)
New in version 2014.7.0.
.sp
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.reload_(name)
New in version 2014.7.0.
.sp
Reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.status(name, sig=None)
Return the status for a service, returns a bool whether the service is
running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdservice.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.openstack_config
.sp
Modify, retrieve, or delete values from OpenStack configuration files.
.INDENT 0.0
.TP
.B maintainer
Jeffrey C. Ollie <\fI\%jeff@ocjtech.us\fP>
.TP
.B maturity
new
.TP
.B depends
.TP
.B platform
linux
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openstack_config.delete(filename, section, parameter)
Delete a value from an OpenStack configuration file.
.INDENT 7.0
.TP
.B filename
The full path to the configuration file
.TP
.B section
The section from which to delete the parameter
.TP
.B parameter
The parameter to delete
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call openstack_config.delete /etc/keystone/keystone.conf sql connection
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openstack_config.get(filename, section, parameter)
Get a value from an OpenStack configuration file.
.INDENT 7.0
.TP
.B filename
The full path to the configuration file
.TP
.B section
The section from which to search for the parameter
.TP
.B parameter
The parameter to return
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call openstack_config.get /etc/keystone/keystone.conf sql connection
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openstack_config.set_(filename, section, parameter, value)
Set a value in an OpenStack configuration file.
.INDENT 7.0
.TP
.B filename
The full path to the configuration file
.TP
.B section
The section in which the parameter will be set
.TP
.B parameter
The parameter to change
.TP
.B value
The value to set
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call openstack_config.set /etc/keystone/keystone.conf sql connection foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.oracle
.sp
Oracle DataBase connection module
.INDENT 0.0
.TP
.B mainteiner
Vladimir Bormotov <\fI\%bormotov@gmail.com\fP>
.TP
.B maturity
new
.TP
.B depends
cx_Oracle
.TP
.B platform
all
.TP
.B configuration
module provide connections for multiple Oracle DB instances.
.sp
\fBOS Environment\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ORACLE_HOME: path to oracle product
PATH: path to Oracle Client libs need to be in PATH
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBpillar\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
oracle.dbs: list of known based
oracle.dbs.<db>.uri: connection credentials in format:
user/password@host[:port]/sid[ as {sysdba|sysoper}]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.oracle.client_version()
Oracle Client Version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq oracle.client_version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.oracle.run_query(db, query)
Run SQL query and return result
.sp
CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq oracle.run_query my_db "select * from my_table"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.oracle.show_dbs(*dbs)
Show databases configuration from pillar. Filter by args
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq oracle.show_dbs
salt \(aq*\(aq oracle.show_dbs my_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.oracle.show_env()
Show Environment used by Oracle Client
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq oracle.show_env
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
at first _connect() \fBNLS_LANG\fP will forced to \(aq.AL32UTF8\(aq
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.oracle.show_pillar(item=None)
Show Pillar segment oracle.* and subitem with notation "item:subitem"
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq oracle.show_pillar
salt \(aq*\(aq oracle.show_pillar dbs:my_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.oracle.version(*dbs)
Server Version (select banner from v$version)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq oracle.version
salt \(aq*\(aq oracle.version my_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.osxdesktop
.sp
Mac OS X implementations of various commands in the "desktop" interface
.INDENT 0.0
.TP
.B salt.modules.osxdesktop.get_output_volume()
Get the output volume (range 0 to 100)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq desktop.get_output_volume
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.osxdesktop.lock()
Lock the desktop session
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq desktop.lock
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.osxdesktop.say(*words)
Say some words.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq desktop.say <word0> <word1> ... <wordN>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.osxdesktop.screensaver()
Launch the screensaver
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq desktop.screensaver
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.osxdesktop.set_output_volume(volume)
Set the volume of sound (range 0 to 100)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq desktop.set_output_volume <volume>
.ft P
.fi
.UNINDENT
.UNINDENT
.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.file_dict(*packages)
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of _every_ file on the system\(aqs
package database (not generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.file_list(*packages)
List the files that belong to a package. Not specifying any packages will
return a list of _every_ file on the system\(aqs package database (not
generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.install(name=None, refresh=False, sysupgrade=False, pkgs=None, sources=None, **kwargs)
Install (pacman \-S) the passed package, add refresh=True to install with
\-y, add sysupgrade=True to install with \-u.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Note that this parameter is
ignored if either "pkgs" or "sources" is passed. Additionally, please
note that this option can only be used to install packages from a
software repository. To install a package file manually, use the
"sources" option.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B refresh
Whether or not to refresh the package database before installing.
.TP
.B sysupgrade
Whether or not to upgrade the system packages before installing.
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from a software repository. Must be
passed as a python list. A specific version number can be specified
by using a single\-element dict representing the package and its
version. As with the \fBversion\fP parameter above, comparison operators
can be used to target a specific version of a package.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-4"}]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "<1.2.3\-4"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B sources
A list of packages to install. Must be passed as a list of dicts,
with the keys being package names, and the values being the source URI
or local path to the package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.pkg.tar.xz"}, {"bar": "salt://bar.pkg.tar.xz"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.list_upgrades(refresh=False)
List all available package upgrades on this system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.owner(*paths)
New in version 2014.7.0.
.sp
Return the name of the package that owns the file. Multiple file paths can
be passed. Like \fBpkg.version <salt.modules.yumpkg.version\fP, if a
single path is passed, a string will be returned, and if multiple paths are
passed, a dictionary of file/package name pairs will be returned.
.sp
If the file is not owned by a package, or is not present on the minion,
then an empty string will be returned for that path.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq pkg.owner /usr/bin/apachectl
salt \(aq*\(aq pkg.owner /usr/bin/apachectl /usr/bin/zsh
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.purge(name=None, pkgs=None, **kwargs)
Recursively remove a package and all dependencies which were installed
with it, this will call a \fBpacman \-Rsc\fP
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.refresh_db()
Just run a \fBpacman \-Sy\fP, return a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<database name>\(aq: Bool}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.remove(name=None, pkgs=None, **kwargs)
Remove packages with \fBpacman \-R\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.upgrade(refresh=False)
Run a full system upgrade, a pacman \-Syu
.INDENT 7.0
.TP
.B refresh
Whether or not to refresh the package database before installing.
.UNINDENT
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.upgrade_available(name)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pacman.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pagerduty
.sp
Module for Firing Events via PagerDuty
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B configuration
This module can be used by specifying the name of a
configuration profile in the minion config, minion pillar, or master
config.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
my\-pagerduty\-account:
pagerduty.api_key: F3Rbyjbve43rfFWf2214
pagerduty.subdomain: mysubdomain
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pagerduty.create_event(service_key=None, description=None, details=None, incident_key=None, profile=None)
.INDENT 7.0
.INDENT 3.5
Create an event in PagerDuty. Designed for use in states.
.sp
CLI Example:
.INDENT 0.0
.INDENT 3.5
pagerduty.create_event <service_key> <description> <details> profile=my\-pagerduty\-account
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B :
The following parameters are required:
.INDENT 7.0
.TP
.B service_key
This key can be found by using pagerduty.list_services.
.TP
.B description
This is a short description of the event.
.TP
.B details
This can be a more detailed description of the event.
.TP
.B profile
This refers to the configuration profile to use to connect to the
PagerDuty service.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pagerduty.list_incidents(profile=None, api_key=None)
List services belonging to this account
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
pagerduty.list_incidents my\-pagerduty\-account
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pagerduty.list_services(profile=None, api_key=None)
List services belonging to this account
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
pagerduty.list_services my\-pagerduty\-account
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pam
.sp
Support for pam
.INDENT 0.0
.TP
.B salt.modules.pam.read_file(file_name)
This is just a test function, to make sure parsing works
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pam.read_file /etc/pam.d/login
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.parted
.sp
Module for managing partitions on POSIX\-like systems.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
parted, partprobe, lsblk (usually parted and util\-linux packages)
.UNINDENT
.UNINDENT
.sp
Some functions may not be available, depending on your version of parted.
.sp
Check the manpage for \fBparted(8)\fP for more information, or the online docs
at:
.sp
\fI\%http://www.gnu.org/software/parted/manual/html_chapter/parted_2.html\fP
.sp
In light of parted not directly supporting partition IDs, some of this module
has been written to utilize sfdisk instead. For further information, please
reference the man page for \fBsfdisk(8)\fP\&.
.INDENT 0.0
.TP
.B salt.modules.parted.align_check(device, part_type, partition)
partition.align_check device part_type partition
.sp
Check if partition satisfies the alignment constraint of part_type.
Type must be "minimal" or "optimal".
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.align_check /dev/sda minimal 1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.check(device, minor)
partition.check device minor
.sp
Checks if the file system on partition <minor> has any errors.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.check 1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.cp(device, from_minor, to_minor)
partition.check device from_minor to_minor
.INDENT 7.0
.TP
.B Copies the file system on the partition <from\-minor> to partition
<to\-minor>, deleting the original contents of the destination
partition.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.cp /dev/sda 2 3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.exists(device=\(aq\(aq)
partition.exists device
.sp
Check to see if the partition exists
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.exists /dev/sdb1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.get_block_device()
Retrieve a list of disk devices
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.get_block_device
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.get_id(device, minor)
Prints the system ID for the partition. Some typical values are:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
b: FAT32 (vfat)
7: HPFS/NTFS
82: Linux Swap
83: Linux
8e: Linux LVM
fd: Linux RAID Auto
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.get_id /dev/sda 1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.list_(device, unit=None)
partition.list device unit
.sp
Prints partition information of given <device>
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.list /dev/sda
salt \(aq*\(aq partition.list /dev/sda unit=s
salt \(aq*\(aq partition.list /dev/sda unit=kB
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.mkfs(device, fs_type)
partition.mkfs device fs_type
.INDENT 7.0
.TP
.B Makes a file system <fs_type> on partition <device>, destroying all data
that resides on that partition. <fs_type> must be one of "ext2",
"fat32", "fat16", "linux\-swap" or "reiserfs" (if libreiserfs is
installed)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.mkfs /dev/sda2 fat32
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.mklabel(device, label_type)
partition.mklabel device label_type
.sp
Create a new disklabel (partition table) of label_type.
Type should be one of "aix", "amiga", "bsd", "dvh", "gpt", "loop", "mac",
"msdos", "pc98", or "sun".
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.mklabel /dev/sda msdos
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.mkpart(device, part_type, fs_type=None, start=None, end=None)
partition.mkpart device part_type fs_type start end
.INDENT 7.0
.TP
.B Make a part_type partition for filesystem fs_type, beginning at start and
ending at end (by default in megabytes). part_type should be one of
"primary", "logical", or "extended".
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.mkpart /dev/sda primary fs_type=fat32 start=0 end=639
salt \(aq*\(aq partition.mkpart /dev/sda primary start=0 end=639
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.mkpartfs(device, part_type, fs_type, start, end)
partition.mkpartfs device part_type fs_type start end
.INDENT 7.0
.TP
.B Make a <part_type> partition with a new filesystem of <fs_type>, beginning
at <start> and ending at <end> (by default in megabytes). <part_type>
should be one of "primary", "logical", or "extended". <fs_type> must be
one of "ext2", "fat32", "fat16", "linux\-swap" or "reiserfs" (if
libreiserfs is installed)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.mkpartfs /dev/sda logical ext2 440 670
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.name(device, partition, name)
partition.name device partition name
.INDENT 7.0
.TP
.B Set the name of partition to name. This option works only on Mac, PC98,
and GPT disklabels. The name can be placed in quotes, if necessary.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.name /dev/sda 1 \(aqMy Documents\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.part_list(device, unit=None)
Deprecated. Calls partition.list.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.part_list /dev/sda
salt \(aq*\(aq partition.part_list /dev/sda unit=s
salt \(aq*\(aq partition.part_list /dev/sda unit=kB
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.probe(device=\(aq\(aq)
Ask the kernel to update its local partition data
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.probe
salt \(aq*\(aq partition.probe /dev/sda
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.rescue(device, start, end)
partition.rescue device start end
.INDENT 7.0
.TP
.B Rescue a lost partition that was located somewhere between start and end.
If a partition is found, parted will ask if you want to create an
entry for it in the partition table.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.rescue /dev/sda 0 8056
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.resize(device, minor, start, end)
partition.resize device minor, start, end
.INDENT 7.0
.TP
.B Resizes the partition with number <minor>. The partition will start <start>
from the beginning of the disk, and end <end> from the beginning of the
disk. resize never changes the minor number. Extended partitions can be
resized, so long as the new extended partition completely contains all
logical partitions.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.resize /dev/sda 3 200 850
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.rm(device, minor)
partition.rm device minor
.sp
Removes the partition with number <minor>.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.rm /dev/sda 5
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.set_(device, minor, flag, state)
partition.set device minor flag state
.INDENT 7.0
.TP
.B Changes a flag on the partition with number <minor>. A flag can be either
"on" or "off". Some or all of these flags will be available, depending
on what disk label you are using.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.set /dev/sda 1 boot on
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.set_id(device, minor, system_id)
Sets the system ID for the partition. Some typical values are:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
b: FAT32 (vfat)
7: HPFS/NTFS
82: Linux Swap
83: Linux
8e: Linux LVM
fd: Linux RAID Auto
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.set_id /dev/sda 1 83
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.system_types()
List the system types that are supported by the installed version of sfdisk
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.system_types
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parted.toggle(device, partition, flag)
partition.toggle device partition flag
.sp
Toggle the state of <flag> on <partition>
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq partition.name /dev/sda 1 boot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pecl
.sp
Manage PHP pecl extensions.
.INDENT 0.0
.TP
.B salt.modules.pecl.install(pecls, defaults=False, force=False, preferred_state=\(aqstable\(aq)
New in version 0.17.0.
.sp
Installs one or several pecl extensions.
.INDENT 7.0
.TP
.B pecls
The pecl extensions to install.
.TP
.B defaults
Use default answers for extensions such as pecl_http which ask
questions before installation. Without this option, the pecl.installed
state will hang indefinitely when trying to install these extensions.
.TP
.B force
Whether to force the installed version or not
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pecl.install fuse
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pecl.list_(channel=None)
List installed pecl extensions.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pecl.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pecl.uninstall(pecls)
Uninstall one or several pecl extensions.
.INDENT 7.0
.TP
.B pecls
The pecl extensions to uninstall.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pecl.uninstall fuse
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pecl.update(pecls)
Update one or several pecl extensions.
.INDENT 7.0
.TP
.B pecls
The pecl extensions to update.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pecl.update fuse
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pillar
.sp
Extract the pillar data for this minion
.INDENT 0.0
.TP
.B salt.modules.pillar.ext(external)
Generate the pillar and apply an explicit external pillar
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.ext \(aq{libvirt: _}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pillar.get(key, default=\(aq\(aq, merge=False, delimiter=\(aq:\(aq)
New in version 0.14.
.sp
Attempt to retrieve the named value from pillar, if the named value is not
available return the passed default. The default return is an empty string.
.sp
If the merge parameter is set to \fBTrue\fP, the default will be recursively
merged into the returned pillar data.
.sp
The value can also represent a value in a nested dict using a ":" delimiter
for the dict. This means that if a dict in pillar looks like this:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To retrieve the value associated with the apache key in the pkg dict this
key can be passed:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B merge
Specify whether or not the retrieved values should be recursively
merged into the passed default.
.sp
New in version 2014.7.0.
.TP
.B delimiter
Specify an alternate delimiter to use when traversing a nested dict
.sp
New in version 2014.7.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.get pkg:apache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pillar.item(*args)
New in version 0.16.2.
.sp
Return one ore more pillar entries
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.item foo
salt \(aq*\(aq pillar.item foo bar baz
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pillar.items(*args)
Calls the master for a fresh pillar and generates the pillar data on the
fly
.sp
Contrast with \fI\%raw()\fP which returns the pillar data that is
currently loaded into the minion.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.items
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pillar.raw(key=None)
Return the raw pillar data that is currently loaded into the minion.
.sp
Contrast with \fI\%items()\fP which calls the master to fetch the most
up\-to\-date Pillar.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.raw
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With the optional key argument, you can select a subtree of the
pillar raw data.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pillar.raw key=\(aqroles\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pip
.sp
Install Python packages with pip to either the system or a virtualenv
.INDENT 0.0
.TP
.B salt.modules.pip.freeze(bin_env=None, user=None, runas=None, cwd=None)
Return a list of installed packages either globally or in the specified
virtualenv
.INDENT 7.0
.TP
.B bin_env
path to pip bin or path to virtualenv. If doing an uninstall from
the system python and want to use a specific pip bin (pip\-2.7,
pip\-2.6, etc..) just specify the pip bin you want.
If uninstalling from a virtualenv, just use the path to the virtualenv
(/home/code/path/to/virtualenv/)
.TP
.B user
The user under which to run pip
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fBrunas\fP argument is deprecated as of 0.16.2. \fBuser\fP should be
used instead.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B cwd
Current working directory to run pip from
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.freeze /home/code/path/to/virtualenv/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pip.install(pkgs=None, requirements=None, env=None, bin_env=None, use_wheel=False, no_use_wheel=False, log=None, proxy=None, timeout=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, exists_action=None, no_deps=False, no_install=False, no_download=False, global_options=None, install_options=None, user=None, runas=None, no_chown=False, cwd=None, activate=False, pre_releases=False, cert=None, allow_all_external=False, allow_external=None, allow_unverified=None, process_dependency_links=False, __env__=None, saltenv=\(aqbase\(aq)
Install packages with pip
.sp
Install packages individually or from a pip requirements file. Install
packages globally or to a virtualenv.
.INDENT 7.0
.TP
.B pkgs
Comma separated list of packages to install
.TP
.B requirements
Path to requirements
.TP
.B bin_env
Path to pip bin or path to virtualenv. If doing a system install,
and want to use a specific pip bin (pip\-2.7, pip\-2.6, etc..) just
specify the pip bin you want.
If installing into a virtualenv, just use the path to the virtualenv
(/home/code/path/to/virtualenv/)
.TP
.B env
Deprecated, use bin_env now
.TP
.B use_wheel
Prefer wheel archives (requires pip>=1.4)
.TP
.B no_use_wheel
Force to not use wheel archives (requires pip>=1.4)
.TP
.B log
Log file where a complete (maximum verbosity) record will be kept
.TP
.B proxy
Specify a proxy in the form
user:passwd@proxy.server:port. Note that the
user:password@ is optional and required only if you
are behind an authenticated proxy. If you provide
user@proxy.server:port then you will be prompted for a
password.
.TP
.B timeout
Set the socket timeout (default 15 seconds)
.TP
.B editable
install something editable (i.e.
git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed)
.TP
.B find_links
URL to look for packages at
.TP
.B index_url
Base URL of Python Package Index
.TP
.B extra_index_url
Extra URLs of package indexes to use in addition to \fBindex_url\fP
.TP
.B no_index
Ignore package index
.TP
.B mirrors
Specific mirror URL(s) to query (automatically adds \-\-use\-mirrors)
.TP
.B build
Unpack packages into \fBbuild\fP dir
.TP
.B target
Install packages into \fBtarget\fP dir
.TP
.B download
Download packages into \fBdownload\fP instead of installing them
.TP
.B download_cache
Cache downloaded packages in \fBdownload_cache\fP dir
.TP
.B source
Check out \fBeditable\fP packages into \fBsource\fP dir
.TP
.B upgrade
Upgrade all packages to the newest available version
.TP
.B force_reinstall
When upgrading, reinstall all packages even if they are already
up\-to\-date.
.TP
.B ignore_installed
Ignore the installed packages (reinstalling instead)
.TP
.B exists_action
Default action when a path already exists: (s)witch, (i)gnore, (w)ipe,
(b)ackup
.TP
.B no_deps
Ignore package dependencies
.TP
.B no_install
Download and unpack all packages, but don\(aqt actually install them
.TP
.B no_download
Don\(aqt download any packages, just install the ones
already downloaded (completes an install run with
\-\-no\-install)
.TP
.B install_options
Extra arguments to be supplied to the setup.py install
command (use like \-\-install\-option="\-\-install\-
scripts=/usr/local/bin"). Use multiple \-\-install\-
option options to pass multiple options to setup.py
install. If you are using an option with a directory
path, be sure to use absolute path.
.TP
.B global_options
Extra global options to be supplied to the setup.py call before the
install command.
.TP
.B user
The user under which to run pip
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fBrunas\fP argument is deprecated as of 0.16.2. \fBuser\fP should be
used instead.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B no_chown
When user is given, do not attempt to copy and chown
a requirements file
.TP
.B cwd
Current working directory to run pip from
.TP
.B activate
Activates the virtual environment, if given via bin_env,
before running install.
.sp
Deprecated since version 2014.7.2: If \fIbin_env\fP is given, pip will already be sourced from that
virualenv, making \fIactivate\fP effectively a noop.
.TP
.B pre_releases
Include pre\-releases in the available versions
.TP
.B cert
Provide a path to an alternate CA bundle
.TP
.B allow_all_external
Allow the installation of all externally hosted files
.TP
.B allow_external
Allow the installation of externally hosted files (comma separated list)
.TP
.B allow_unverified
Allow the installation of insecure and unverifiable files (comma separated list)
.TP
.B process_dependency_links
Enable the processing of dependency links
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.install <package name>,<package2 name>
salt \(aq*\(aq pip.install requirements=/path/to/requirements.txt
salt \(aq*\(aq pip.install <package name> bin_env=/path/to/virtualenv
salt \(aq*\(aq pip.install <package name> bin_env=/path/to/pip_bin
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Complicated CLI example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.install markdown,django editable=git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed upgrade=True no_deps=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pip.list_(prefix=None, bin_env=None, user=None, runas=None, cwd=None)
Filter list of installed apps from \fBfreeze\fP and check to see if
\fBprefix\fP exists in the list of packages installed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.list salt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pip.uninstall(pkgs=None, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, user=None, runas=None, no_chown=False, cwd=None, __env__=None, saltenv=\(aqbase\(aq)
Uninstall packages with pip
.sp
Uninstall packages individually or from a pip requirements file. Uninstall
packages globally or from a virtualenv.
.INDENT 7.0
.TP
.B pkgs
comma separated list of packages to install
.TP
.B requirements
path to requirements.
.TP
.B bin_env
path to pip bin or path to virtualenv. If doing an uninstall from
the system python and want to use a specific pip bin (pip\-2.7,
pip\-2.6, etc..) just specify the pip bin you want.
If uninstalling from a virtualenv, just use the path to the virtualenv
(/home/code/path/to/virtualenv/)
.TP
.B log
Log file where a complete (maximum verbosity) record will be kept
.TP
.B proxy
Specify a proxy in the form
user:passwd@proxy.server:port. Note that the
user:password@ is optional and required only if you
are behind an authenticated proxy. If you provide
user@proxy.server:port then you will be prompted for a
password.
.TP
.B timeout
Set the socket timeout (default 15 seconds)
.TP
.B user
The user under which to run pip
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fBrunas\fP argument is deprecated as of 0.16.2. \fBuser\fP should be
used instead.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B no_chown
When user is given, do not attempt to copy and chown
a requirements file
.TP
.B cwd
Current working directory to run pip from
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.uninstall <package name>,<package2 name>
salt \(aq*\(aq pip.uninstall requirements=/path/to/requirements.txt
salt \(aq*\(aq pip.uninstall <package name> bin_env=/path/to/virtualenv
salt \(aq*\(aq pip.uninstall <package name> bin_env=/path/to/pip_bin
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pip.version(bin_env=None)
New in version 0.17.0.
.sp
Returns the version of pip. Use \fBbin_env\fP to specify the path to a
virtualenv and get the version of pip in that virtualenv.
.sp
If unable to detect the pip version, returns \fBNone\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pip.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pkg_resource
.sp
Resources needed by pkg providers
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.add_pkg(pkgs, name, version)
Add a package to a dict of installed packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.add_pkg \(aq{}\(aq bind 9
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.check_extra_requirements(pkgname, pkgver)
Check if the installed package already has the given requirements.
This function will simply try to call "pkg.check_extra_requirements".
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.check_extra_requirements <pkgname> <extra_requirements>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.pack_sources(sources)
Accepts list of dicts (or a string representing a list of dicts) and packs
the key/value pairs into a single dict.
.sp
\fB\(aq[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]\(aq\fP would become
\fB{"foo": "salt://foo.rpm", "bar": "salt://bar.rpm"}\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.pack_sources \(aq[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.parse_targets(name=None, pkgs=None, sources=None, saltenv=\(aqbase\(aq, normalize=True, **kwargs)
Parses the input to pkg.install and returns back the package(s) to be
installed. Returns a list of packages, as well as a string noting whether
the packages are to come from a repository or a binary package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.parse_targets
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.sort_pkglist(pkgs)
Accepts a dict obtained from pkg.list_pkgs() and sorts in place the list of
versions for any packages that have multiple versions installed, so that
two package lists can be compared to one another.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.sort_pkglist \(aq["3.45", "2.13"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.stringify(pkgs)
Takes a dict of package name/version information and joins each list of
installed versions into a string.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.stringify \(aqvim: 7.127\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.version(*names, **kwargs)
Common interface for obtaining the version of installed packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.version vim
salt \(aq*\(aq pkg_resource.version foo bar baz
salt \(aq*\(aq pkg_resource.version \(aqpython*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkg_resource.version_clean(version)
Clean the version string removing extra data.
This function will simply try to call \fBpkg.version_clean\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg_resource.version_clean <version_string>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pkgin
.sp
Package support for pkgin based systems, inspired from freebsdpkg module
.INDENT 0.0
.TP
.B salt.modules.pkgin.available_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.file_dict(package)
List the files that belong to a package.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list nginx
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.file_list(package)
List the files that belong to a package.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list nginx
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs)
Install the passed package
.INDENT 7.0
.TP
.B name
The name of the package to be installed.
.TP
.B refresh
Whether or not to refresh the package database before installing.
.TP
.B fromrepo
Specify a package repository to install from.
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from a software repository. Must be
passed as a python list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B sources
A list of packages to install. Must be passed as a list of dicts,
with the keys being package names, and the values being the source URI
or local path to the package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.purge(name=None, pkgs=None, **kwargs)
Package purges are not supported, this function is identical to
\fBremove()\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.refresh_db()
Use pkg update to get latest pkg_summary
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.remove(name=None, pkgs=None, **kwargs)
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a list containing the removed packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.search(pkg_name)
Searches for an exact match using pkgin ^package$
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search \(aqmysql\-server\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.upgrade()
Run pkg upgrade, if pkgin used. Otherwise do nothing
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgin.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pkgng
.sp
Support for \fBpkgng\fP, the new package manager for FreeBSD
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This module has been completely rewritten. Up to and including version
0.17.x, it was available as the \fBpkgng\fP module, (\fBpkgng.install\fP,
\fBpkgng.delete\fP, etc.), but moving forward this module will no longer be
available as \fBpkgng\fP, as it will behave like a normal Salt \fBpkg\fP
provider. The documentation below should not be considered to apply to this
module in versions <= 0.17.x. If your minion is running a 0.17.x release or
older, then the documentation for this module can be viewed using the
\fBsys.doc\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt bsdminion sys.doc pkgng
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This module provides an interface to \fBpkg(8)\fP\&. It acts as the default
package provider for FreeBSD 10 and newer. For FreeBSD hosts which have
been upgraded to use pkgng, you will need to override the \fBpkg\fP provider
by setting the \fBproviders\fP parameter in your Minion config
file, in order to use this module to manage packages, like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
providers:
pkg: pkgng
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.audit(jail=None, chroot=None)
Audits installed packages against known vulnerabilities
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.audit
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Audit packages within the specified jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.audit jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Audit packages within the specified chroot (ignored if \fBjail\fP is
specified)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.audit chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.autoremove(jail=None, chroot=None, dryrun=False)
Delete packages which were automatically installed as dependencies and are
not required anymore.
.INDENT 7.0
.TP
.B dryrun
Dry\-run mode. The list of changes to packages is always printed,
but no changes are actually made.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.autoremove
salt \(aq*\(aq pkg.autoremove jail=<jail name or id>
salt \(aq*\(aq pkg.autoremove dryrun=True
salt \(aq*\(aq pkg.autoremove jail=<jail name or id> dryrun=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.backup(file_name, jail=None, chroot=None)
Export installed packages into yaml+mtree file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.backup /tmp/pkg
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Backup packages from the specified jail. Note that this will run the
command within the jail, and so the path to the backup file will be
relative to the root of the jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.backup /tmp/pkg jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Backup packages from the specified chroot (ignored if \fBjail\fP is
specified). Note that this will run the command within the chroot, and
so the path to the backup file will be relative to the root of the
chroot.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.backup /tmp/pkg chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.check(jail=None, chroot=None, depends=False, recompute=False, checksum=False)
Sanity checks installed packages
.INDENT 7.0
.TP
.B jail
Perform the sanity check in the specified jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Perform the sanity check in the specified chroot (ignored if \fBjail\fP
is specified)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Of the below, at least one must be set to \fBTrue\fP\&.
.INDENT 7.0
.TP
.B depends
Check for and install missing dependencies.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check recompute=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B recompute
Recompute sizes and checksums of installed packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check depends=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B checksum
Find invalid checksums for installed packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check checksum=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.clean(jail=None, chroot=None)
Cleans the local cache of fetched remote packages
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.clean
salt \(aq*\(aq pkg.clean jail=<jail name or id>
salt \(aq*\(aq pkg.clean chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.fetch(name, jail=None, chroot=None, fetch_all=False, quiet=False, fromrepo=None, glob=True, regex=False, pcre=False, local=False, depends=False)
Fetches remote packages
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Fetch package in the specified jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Fetch package in the specified chroot (ignored if \fBjail\fP is
specified)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B fetch_all
Fetch all packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> fetch_all=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B quiet
Quiet mode. Show less output.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> quiet=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B fromrepo
Fetches packages from the given repo if multiple repo support
is enabled. See \fBpkg.conf(5)\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> fromrepo=repo
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B glob
Treat pkg_name as a shell glob pattern.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> glob=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B regex
Treat pkg_name as a regular expression.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <regular expression> regex=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B pcre
Treat pkg_name is an extended regular expression.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <extended regular expression> pcre=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B local
Skip updating the repository catalogs with pkg\-update(8). Use the
local cache only.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> local=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B depends
Fetch the package and its dependencies as well.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.fetch <package name> depends=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.install(name=None, fromrepo=None, pkgs=None, sources=None, jail=None, chroot=None, orphan=False, force=False, glob=False, local=False, dryrun=False, quiet=False, reinstall_requires=False, regex=False, pcre=False, **kwargs)
Install package(s) from a repository
.INDENT 7.0
.TP
.B name
The name of the package to install
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B jail
Install the package into the specified jail
.TP
.B chroot
Install the package into the specified chroot (ignored if \fBjail\fP is
specified)
.TP
.B orphan
Mark the installed package as orphan. Will be automatically removed
if no other packages depend on them. For more information please
refer to \fBpkg\-autoremove(8)\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> orphan=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B force
Force the reinstallation of the package if already installed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B glob
Treat the package names as shell glob patterns.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> glob=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B local
Do not update the repository catalogs with \fBpkg\-update(8)\fP\&. A
value of \fBTrue\fP here is equivalent to using the \fB\-U\fP flag with
\fBpkg install\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> local=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B dryrun
Dru\-run mode. The list of changes to packages is always printed,
but no changes are actually made.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> dryrun=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B quiet
Force quiet output, except when dryrun is used, where pkg install
will always show packages to be installed, upgraded or deleted.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> quiet=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B reinstall_requires
When used with force, reinstalls any packages that require the
given package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> reinstall_requires=True force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.7.0: \fBrequire\fP kwarg renamed to \fBreinstall_requires\fP
.TP
.B fromrepo
In multi\-repo mode, override the pkg.conf ordering and only attempt
to download packages from the named repository.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name> fromrepo=repo
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B regex
Treat the package names as a regular expression
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <regular expression> regex=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B pcre
Treat the package names as extended regular expressions.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <extended regular expression> pcre=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package name> jail=<jail name or id>
salt \(aq*\(aq pkg.latest_version <package name> chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.list_pkgs(versions_as_list=False, jail=None, chroot=None, with_origin=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
List the packages in the specified jail
.TP
.B chroot
List the packages in the specified chroot (ignored if \fBjail\fP is
specified)
.TP
.B with_origin
False
Return a nested dictionary containing both the origin name and version
for each installed package.
.sp
New in version 2014.1.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
salt \(aq*\(aq pkg.list_pkgs jail=<jail name or id>
salt \(aq*\(aq pkg.list_pkgs chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.parse_config(file_name=\(aq/usr/local/etc/pkg.conf\(aq)
Return dict of uncommented global variables.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.parse_config
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP not working properly right now
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.refresh_db(jail=None, chroot=None, force=False)
Refresh PACKAGESITE contents
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function can accessed using \fBpkg.update\fP in addition to
\fBpkg.refresh_db\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Refresh the pkg database within the specified jail
.TP
.B chroot
Refresh the pkg database within the specified chroot (ignored if
\fBjail\fP is specified)
.TP
.B force
Force a full download of the repository catalog without regard to the
respective ages of the local and remote copies of the catalog.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.remove(name=None, pkgs=None, jail=None, chroot=None, all_installed=False, force=False, glob=False, dryrun=False, recurse=False, regex=False, pcre=False, **kwargs)
Remove a package from the database and system
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function can accessed using \fBpkg.delete\fP in addition to
\fBpkg.remove\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
The package to remove
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B jail
Delete the package from the specified jail
.TP
.B chroot
Delete the package from the specified chroot (ignored if \fBjail\fP is
specified)
.TP
.B all_installed
Deletes all installed packages from the system and empties the
database. USE WITH CAUTION!
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove all all_installed=True force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B force
Forces packages to be removed despite leaving unresolved
dependencies.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name> force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B glob
Treat the package names as shell glob patterns.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name> glob=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B dryrun
Dry run mode. The list of packages to delete is always printed, but
no packages are actually deleted.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name> dryrun=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B recurse
Delete all packages that require the listed package as well.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name> recurse=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B regex
Treat the package names as regular expressions.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <regular expression> regex=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B pcre
Treat the package names as extended regular expressions.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <extended regular expression> pcre=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.restore(file_name, jail=None, chroot=None)
Reads archive created by pkg backup \-d and recreates the database.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.restore /tmp/pkg
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Restore database to the specified jail. Note that this will run the
command within the jail, and so the path to the file from which the pkg
database will be restored is relative to the root of the jail.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.restore /tmp/pkg jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Restore database to the specified chroot (ignored if \fBjail\fP is
specified). Note that this will run the command within the chroot, and
so the path to the file from which the pkg database will be restored is
relative to the root of the chroot.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.restore /tmp/pkg chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.search(name, jail=None, chroot=None, exact=False, glob=False, regex=False, pcre=False, comment=False, desc=False, full=False, depends=False, size=False, quiet=False, origin=False, prefix=False)
Searches in remote package repositories
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Perform the search using the \fBpkg.conf(5)\fP from the specified jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Perform the search using the \fBpkg.conf(5)\fP from the specified chroot
(ignored if \fBjail\fP is specified)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B exact
Treat pattern as exact pattern.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern exact=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B glob
Treat pattern as a shell glob pattern.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern glob=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B regex
Treat pattern as a regular expression.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern regex=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B pcre
Treat pattern as an extended regular expression.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern pcre=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B comment
Search for pattern in the package comment one\-line description.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern comment=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B desc
Search for pattern in the package description.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern desc=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B full
Displays full information about the matching packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern full=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B depends
Displays the dependencies of pattern.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern depends=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B size
Displays the size of the package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern size=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B quiet
Be quiet. Prints only the requested information without displaying
many hints.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern quiet=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B origin
Displays pattern origin.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern origin=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B prefix
Displays the installation prefix for each package matching pattern.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.search pattern prefix=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.stats(local=False, remote=False, jail=None, chroot=None)
Return pkgng stats.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.stats
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B local
Display stats only for the local package database.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.stats local=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B remote
Display stats only for the remote package database(s).
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.stats remote=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B jail
Retrieve stats from the specified jail.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.stats jail=<jail name or id>
salt \(aq*\(aq pkg.stats jail=<jail name or id> local=True
salt \(aq*\(aq pkg.stats jail=<jail name or id> remote=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Retrieve stats from the specified chroot (ignored if \fBjail\fP is
specified).
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.stats chroot=/path/to/chroot
salt \(aq*\(aq pkg.stats chroot=/path/to/chroot local=True
salt \(aq*\(aq pkg.stats chroot=/path/to/chroot remote=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.update_package_site(new_url)
Updates remote package repo URL, PACKAGESITE var to be exact.
.sp
Must use \fBhttp://\fP, \fBftp://\fP, or \fBhttps://\fP protocol
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.update_package_site http://127.0.0.1/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.updating(name, jail=None, chroot=None, filedate=None, filename=None)
\(aq
Displays UPDATING entries of software packages
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.updating foo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Perform the action in the specified jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.updating foo jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Perform the action in the specified chroot (ignored if \fBjail\fP is
specified)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.updating foo chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B filedate
Only entries newer than date are shown. Use a YYYYMMDD date format.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.updating foo filedate=20130101
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B filename
Defines an alternative location of the UPDATING file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.updating foo filename=/tmp/UPDATING
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.upgrade(jail=None, chroot=None, force=False, local=False, dryrun=False)
Upgrade all packages (run a \fBpkg upgrade\fP)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Audit packages within the specified jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Audit packages within the specified chroot (ignored if \fBjail\fP is
specified)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Any of the below options can also be used with \fBjail\fP or \fBchroot\fP\&.
.INDENT 7.0
.TP
.B force
Force reinstalling/upgrading the whole set of packages.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B local
Do not update the repository catalogs with \fBpkg\-update(8)\fP\&. A value
of \fBTrue\fP here is equivalent to using the \fB\-U\fP flag with \fBpkg
upgrade\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade local=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B dryrun
Dry\-run mode: show what packages have updates available, but do not
perform any upgrades. Repository catalogs will be updated as usual
unless the local option is also given.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade dryrun=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function can accessed using \fBpkg.info\fP in addition to
\fBpkg.version\fP, to more closely match the CLI usage of \fBpkg(8)\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Get package version information for the specified jail
.TP
.B chroot
Get package version information for the specified chroot (ignored if
\fBjail\fP is specified)
.TP
.B with_origin
False
Return a nested dictionary containing both the origin name and version
for each specified package.
.sp
New in version 2014.1.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package name> jail=<jail name or id>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgng.which(path, jail=None, chroot=None, origin=False, quiet=False)
Displays which package installed a specific file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.which <file name>
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B jail
Perform the check in the specified jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.which <file name> jail=<jail name or id>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B chroot
Perform the check in the specified chroot (ignored if \fBjail\fP is
specified)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.which <file name> chroot=/path/to/chroot
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B origin
Shows the origin of the package instead of name\-version.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.which <file name> origin=True
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B quiet
Quiet output.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.which <file name> quiet=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pkgutil
.sp
Pkgutil support for Solaris
.INDENT 0.0
.TP
.B salt.modules.pkgutil.install(name=None, refresh=False, version=None, pkgs=None, **kwargs)
Install packages using the pkgutil tool.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package_name>
salt \(aq*\(aq pkg.install SMClgcc346
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from OpenCSW. Must be passed as a python
list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkgutil.latest_version CSWpython
salt \(aq*\(aq pkgutil.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
salt \(aq*\(aq pkg.list_pkgs versions_as_list=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.list_upgrades(refresh=True)
List all available package upgrades on this system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkgutil.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.purge(name=None, pkgs=None, **kwargs)
Package purges are not supported, this function is identical to
\fBremove()\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.refresh_db()
Updates the pkgutil repo database (pkgutil \-U)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkgutil.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.remove(name=None, pkgs=None, **kwargs)
Remove a package and all its dependencies which are not in use by other
packages.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.upgrade(refresh=True)
Upgrade all of the packages to the latest available version.
.sp
Returns a dict containing the changes:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkgutil.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.upgrade_available(name)
Check if there is an upgrade available for a certain package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkgutil.upgrade_available CSWpython
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pkgutil.version(*names, **kwargs)
Returns a version if the package is installed, else returns an empty string
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkgutil.version CSWpython
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.portage_config
.sp
Configure \fBportage(5)\fP
.INDENT 0.0
.TP
.B salt.modules.portage_config.append_to_package_conf(conf, atom=\(aq\(aq, flags=None, string=\(aq\(aq, overwrite=False)
Append a string or a list of flags for a given package or DEPEND atom to a
given configuration file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.append_to_package_conf use string="app\-admin/salt ldap \-libvirt"
salt \(aq*\(aq portage_config.append_to_package_conf use atom="> = app\-admin/salt\-0.14.1" flags="[\(aqldap\(aq, \(aq\-libvirt\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.portage_config.append_use_flags(atom, uses=None, overwrite=False)
Append a list of use flags for a given package or DEPEND atom
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.append_use_flags "app\-admin/salt[ldap, \-libvirt]"
salt \(aq*\(aq portage_config.append_use_flags ">=app\-admin/salt\-0.14.1" "[\(aqldap\(aq, \(aq\-libvirt\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.portage_config.enforce_nice_config()
Enforce a nice tree structure for /etc/portage/package.* configuration
files.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBsalt.modules.ebuild.ex_mod_init()\fP
for information on automatically running this when pkg is used.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.enforce_nice_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.portage_config.get_flags_from_package_conf(conf, atom)
Get flags for a given package or DEPEND atom.
Warning: This only works if the configuration files tree is in the correct
format (the one enforced by enforce_nice_config)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.get_flags_from_package_conf license salt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.portage_config.get_missing_flags(conf, atom, flags)
Find out which of the given flags are currently not set.
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.get_missing_flags use salt "[\(aqldap\(aq, \(aq\-libvirt\(aq, \(aqopenssl\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.portage_config.has_flag(conf, atom, flag)
Verify if the given package or DEPEND atom has the given flag.
Warning: This only works if the configuration files tree is in the correct
format (the one enforced by enforce_nice_config)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.has_flag license salt Apache\-2.0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.portage_config.has_use(atom, use)
Verify if the given package or DEPEND atom has the given use flag.
Warning: This only works if the configuration files tree is in the correct
format (the one enforced by enforce_nice_config)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.has_use salt libvirt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.portage_config.is_present(conf, atom)
Tell if a given package or DEPEND atom is present in the configuration
files tree.
Warning: This only works if the configuration files tree is in the correct
format (the one enforced by enforce_nice_config)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq portage_config.is_present unmask salt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.postfix
.sp
Support for Postfix
.sp
This module is currently little more than a config file viewer and editor. It
is able to read the master.cf file (which is one style) and files in the style
of main.cf (which is a different style, that is used in multiple postfix
configuration files).
.sp
The design of this module is such that when files are edited, a minimum of
changes are made to them. Each file should look as if it has been edited by
hand; order, comments and whitespace are all preserved.
.INDENT 0.0
.TP
.B salt.modules.postfix.set_main(key, value, path=\(aq/etc/postfix/main.cf\(aq)
Set a single config value in the main.cf file. If the value does not already
exist, it will be appended to the end.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt <minion> postfix.set_main mailq_path /usr/bin/mailq
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postfix.set_master(service, conn_type, private=\(aqy\(aq, unpriv=\(aqy\(aq, chroot=\(aqy\(aq, wakeup=\(aqn\(aq, maxproc=\(aq100\(aq, command=\(aq\(aq, write_conf=True, path=\(aq/etc/postfix/master.cf\(aq)
Set a single config value in the master.cf file. If the value does not
already exist, it will be appended to the end.
.sp
Because of shell parsing issues, \(aq\-\(aq cannot be set as a value, as is normal
in the master.cf file; either \(aqy\(aq, \(aqn\(aq or a number should be used when
calling this function from the command line. If the value used matches the
default, it will internally be converted to a \(aq\-\(aq. Calling this function
from the Python API is not affected by this limitation
.sp
The settings and their default values, in order, are: service (required),
conn_type (required), private (y), unpriv (y), chroot (y), wakeup (n),
maxproc (100), command (required).
.sp
By default, this function will write out the changes to the master.cf file,
and then returns the full contents of the file. By setting the
\fBwrite_conf\fP option to \fBFalse\fP, it will skip writing the file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt <minion> postfix.set_master smtp inet n y n n 100 smtpd
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postfix.show_main(path=\(aq/etc/postfix/main.cf\(aq)
Return a dict of active config values. This does not include comments,
spacing or order. Bear in mind that order is functionally important in the
main.cf file, since keys can be referred to as variables. This means that
the data returned from this function should not be used for direct
modification of the main.cf file; other functions are available for that.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
salt <minion> postfix.show_main
salt <minion> postfix.show_main path=/path/to/main.cf
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postfix.show_master(path=\(aq/etc/postfix/master.cf\(aq)
Return a dict of active config values. This does not include comments,
spacing or order.
.sp
The data returned from this function should not be used for direct
modification of the main.cf file; other functions are available for that.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
salt <minion> postfix.show_master
salt <minion> postfix.show_master path=/path/to/master.cf
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.postgres
.sp
Module to provide Postgres compatibility to salt.
.INDENT 0.0
.TP
.B configuration
In order to connect to Postgres, certain configuration is
required in /etc/salt/minion on the relevant minions. Some sample configs
might look like:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
postgres.host: \(aqlocalhost\(aq
postgres.port: \(aq5432\(aq
postgres.user: \(aqpostgres\(aq \-> db user
postgres.pass: \(aq\(aq
postgres.maintenance_db: \(aqpostgres\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The default for the maintenance_db is \(aqpostgres\(aq and in most cases it can
be left at the default setting.
This data can also be passed into pillar. Options passed into opts will
overwrite options passed into pillar
.TP
.B note
This module uses MD5 hashing which may not be compliant with certain
security audits.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.available_extensions(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
List available postgresql extensions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.available_extensions
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.create_extension(name, if_not_exists=None, schema=None, ext_version=None, from_version=None, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Install a postgresql extension
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.create_extension \(aqadminpack\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.create_metadata(name, ext_version=None, schema=None, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Get lifecycle informations about an extension
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.create_metadata adminpack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.db_alter(name, user=None, host=None, port=None, maintenance_db=None, password=None, tablespace=None, owner=None, runas=None)
Change tablespace or/and owner of database.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.db_alter dbname owner=otheruser
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.db_create(name, user=None, host=None, port=None, maintenance_db=None, password=None, tablespace=None, encoding=None, lc_collate=None, lc_ctype=None, owner=None, template=None, runas=None)
Adds a databases to the Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.db_create \(aqdbname\(aq
salt \(aq*\(aq postgres.db_create \(aqdbname\(aq template=template_postgis
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.db_exists(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Checks if a database exists on the Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.db_exists \(aqdbname\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.db_list(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Return dictionary with information about databases of a Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.db_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.db_remove(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Removes a databases from the Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.db_remove \(aqdbname\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.drop_extension(name, if_exists=None, restrict=None, cascade=None, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Drop an installed postgresql extension
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.drop_extension \(aqadminpack\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.get_available_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Get info about an available postgresql extension
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.get_available_extension plpgsql
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.get_installed_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Get info about an installed postgresql extension
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.get_installed_extension plpgsql
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.group_create(groupname, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createuser=None, createroles=None, encrypted=None, login=None, inherit=None, superuser=None, replication=None, rolepassword=None, groups=None, runas=None)
Creates a Postgres group. A group is postgres is similar to a user, but
cannot login.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.group_create \(aqgroupname\(aq user=\(aquser\(aq \e
host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e
rolepassword=\(aqrolepassword\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.group_remove(groupname, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Removes a group from the Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.group_remove \(aqgroupname\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.group_update(groupname, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createroles=None, createuser=None, encrypted=None, inherit=None, login=None, superuser=None, replication=None, rolepassword=None, groups=None, runas=None)
Updated a postgres group
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.group_update \(aqusername\(aq user=\(aquser\(aq \e
host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e
rolepassword=\(aqrolepassword\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.installed_extensions(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
List installed postgresql extensions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.installed_extensions
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.is_available_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Test if a specific extension is installed
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.is_installed_extension
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.is_installed_extension(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Test if a specific extension is installed
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.is_installed_extension
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.owner_to(dbname, ownername, user=None, host=None, port=None, password=None, runas=None)
Set the owner of all schemas, functions, tables, views and sequences to
the given username.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.owner_to \(aqdbname\(aq \(aqusername\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.psql_query(query, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Run an SQL\-Query and return the results as a list. This command
only supports SELECT statements. This limitation can be worked around
with a query like this:
.sp
WITH updated AS (UPDATE pg_authid SET rolconnlimit = 2000 WHERE
rolname = \(aqrolename\(aq RETURNING rolconnlimit) SELECT * FROM updated;
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.psql_query \(aqselect * from pg_stat_activity\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.role_get(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None, return_password=False)
Return a dict with information about users of a Postgres server.
.sp
Set return_password to True to get password hash in the result.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.role_get postgres
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.user_create(username, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createuser=None, createroles=None, inherit=None, login=None, encrypted=None, superuser=None, replication=None, rolepassword=None, groups=None, runas=None)
Creates a Postgres user.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.user_create \(aqusername\(aq user=\(aquser\(aq \e
host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e
rolepassword=\(aqrolepassword\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.user_exists(name, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Checks if a user exists on the Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.user_exists \(aqusername\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.user_list(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None, return_password=False)
Return a dict with information about users of a Postgres server.
.sp
Set return_password to True to get password hash in the result.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.user_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.user_remove(username, user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Removes a user from the Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.user_remove \(aqusername\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.user_update(username, user=None, host=None, port=None, maintenance_db=None, password=None, createdb=None, createuser=None, createroles=None, encrypted=None, superuser=None, inherit=None, login=None, replication=None, rolepassword=None, groups=None, runas=None)
Updates a Postgres user.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.user_update \(aqusername\(aq user=\(aquser\(aq \e
host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq \e
rolepassword=\(aqrolepassword\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.postgres.version(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
Return the version of a Postgres server.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq postgres.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.poudriere
.sp
Support for poudriere
.INDENT 0.0
.TP
.B salt.modules.poudriere.bulk_build(jail, pkg_file, keep=False)
Run bulk build on poudriere server.
.sp
Return number of pkg builds, failures, and errors, on error dump to CLI
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-N buildbox_group poudriere.bulk_build 90amd64 /root/pkg_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.create_jail(name, arch, version=\(aq9.0\-RELEASE\(aq)
Creates a new poudriere jail if one does not exist
.sp
\fINOTE\fP creating a new jail will take some time the master is not hanging
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.create_jail 90amd64 amd64
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.create_ports_tree()
Not working need to run portfetch non interactive
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.delete_jail(name)
Deletes poudriere jail with \fIname\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.delete_jail 90amd64
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.is_jail(name)
Return True if jail exists False if not
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.is_jail <jail name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.list_jails()
Return a list of current jails managed by poudriere
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.list_jails
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.list_ports()
Return a list of current port trees managed by poudriere
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.list_ports
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.make_pkgng_aware(jname)
Make jail \fBjname\fP pkgng aware
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.make_pkgng_aware <jail name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.parse_config(config_file=None)
Returns a dict of poudriere main configuration definitions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.parse_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.update_jail(name)
Run freebsd\-update on \fIname\fP poudriere jail
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.update_jail freebsd:10:x86:64
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.update_ports_tree(ports_tree)
Updates the ports tree, either the default or the \fIports_tree\fP specified
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.update_ports_tree staging
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.poudriere.version()
Return poudriere version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq poudriere.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.powerpath
.sp
powerpath support.
.sp
Assumes RedHat
.INDENT 0.0
.TP
.B salt.modules.powerpath.add_license(key)
Add a license
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.powerpath.has_powerpath()
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.powerpath.list_licenses()
returns a list of applied powerpath license keys
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.powerpath.remove_license(key)
Remove a license
.UNINDENT
.SS salt.modules.ps
.sp
A salt interface to psutil, a system and process library.
See \fI\%http://code.google.com/p/psutil\fP\&.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
psutil Python module, version 0.3.0 or later
.IP \(bu 2
python\-utmp package (optional)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.boot_time(time_format=None)
Return the boot time in number of seconds since the epoch began.
.sp
CLI Example:
.INDENT 7.0
.TP
.B time_format
Optionally specify a \fI\%strftime\fP format string. Use
\fBtime_format=\(aq%c\(aq\fP to get a nicely\-formatted locale specific date and
time (i.e. \fBFri May 2 19:08:32 2014\fP).
.sp
New in version 2014.1.4.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.boot_time
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.cpu_percent(interval=0.1, per_cpu=False)
Return the percent of time the CPU is busy.
.INDENT 7.0
.TP
.B interval
the number of seconds to sample CPU usage over
.TP
.B per_cpu
if True return an array of CPU percent busy for each CPU, otherwise
aggregate all percents into one number
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.cpu_percent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.cpu_times(per_cpu=False)
Return the percent of time the CPU spends in each state,
e.g. user, system, idle, nice, iowait, irq, softirq.
.INDENT 7.0
.TP
.B per_cpu
if True return an array of percents for each CPU, otherwise aggregate
all percents into one number
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.cpu_times
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.disk_io_counters(device=None)
Return disk I/O statistics.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.disk_io_counters
salt \(aq*\(aq ps.disk_io_counters device=sda1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.disk_partition_usage(all=False)
Return a list of disk partitions plus the mount point, filesystem and usage
statistics.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.disk_partition_usage
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.disk_partitions(all=False)
Return a list of disk partitions and their device, mount point, and
filesystem type.
.INDENT 7.0
.TP
.B all
if set to False, only return local, physical partitions (hard disk,
USB, CD/DVD partitions). If True, return all filesystems.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.disk_partitions
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.disk_usage(path)
Given a path, return a dict listing the total available space as well as
the free space, and used space.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.disk_usage /home
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.get_pid_list()
Return a list of process ids (PIDs) for all running processes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.get_pid_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.get_users()
Return logged\-in users.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.get_users
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.kill_pid(pid, signal=15)
Kill a process by PID.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq ps.kill_pid pid [signal=signal_number]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B pid
PID of process to kill.
.TP
.B signal
Signal to send to the process. See manpage entry for kill
for possible values. Default: 15 (SIGTERM).
.UNINDENT
.sp
\fBExample:\fP
.sp
Send SIGKILL to process with PID 2000:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq ps.kill_pid 2000 signal=9
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.network_io_counters(interface=None)
Return network I/O statistics.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.network_io_counters
salt \(aq*\(aq ps.network_io_counters interface=eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.num_cpus()
Return the number of CPUs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.num_cpus
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.pgrep(pattern, user=None, full=False)
Return the pids for processes matching a pattern.
.sp
If full is true, the full command line is searched for a match,
otherwise only the name of the command is searched.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.pgrep pattern [user=username] [full=(true|false)]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B pattern
Pattern to search for in the process list.
.TP
.B user
Limit matches to the given username. Default: All users.
.TP
.B full
A boolean value indicating whether only the name of the command or
the full command line should be matched against the pattern.
.UNINDENT
.sp
\fBExamples:\fP
.sp
Find all httpd processes on all \(aqwww\(aq minions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqwww.*\(aq ps.pgrep httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Find all bash processes owned by user \(aqtom\(aq:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.pgrep bash user=tom
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.pkill(pattern, user=None, signal=15, full=False)
Kill processes matching a pattern.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.pkill pattern [user=username] [signal=signal_number] \e
[full=(true|false)]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B pattern
Pattern to search for in the process list.
.TP
.B user
Limit matches to the given username. Default: All users.
.TP
.B signal
Signal to send to the process(es). See manpage entry for kill
for possible values. Default: 15 (SIGTERM).
.TP
.B full
A boolean value indicating whether only the name of the command or
the full command line should be matched against the pattern.
.UNINDENT
.sp
\fBExamples:\fP
.sp
Send SIGHUP to all httpd processes on all \(aqwww\(aq minions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqwww.*\(aq ps.pkill httpd signal=1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Send SIGKILL to all bash processes owned by user \(aqtom\(aq:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.pkill bash signal=9 user=tom
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.swap_memory()
New in version 2014.7.0.
.sp
Return a dict that describes swap memory statistics.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function is only available in psutil version 0.6.0 and above.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.swap_memory
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.top(num_processes=5, interval=3)
Return a list of top CPU consuming processes during the interval.
num_processes = return the top N CPU consuming processes
interval = the number of seconds to sample CPU usage over
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.top
salt \(aq*\(aq ps.top 5 10
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.total_physical_memory()
Return the total number of bytes of physical memory.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.total_physical_memory
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ps.virtual_memory()
New in version 2014.7.0.
.sp
Return a dict that describes statistics about system memory usage.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function is only available in psutil version 0.6.0 and above.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ps.virtual_memory
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.publish
.sp
Publish a command from a minion to a target
.INDENT 0.0
.TP
.B salt.modules.publish.full_data(tgt, fun, arg=None, expr_form=\(aqglob\(aq, returner=\(aq\(aq, timeout=5)
Return the full data about the publication, this is invoked in the same
way as the publish function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt system.example.com publish.full_data \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
If you need to pass a value to a function argument and that value
contains an equal sign, you \fBmust\fP include the argument name.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq publish.full_data test.kwarg arg=\(aqcheese=spam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.publish.publish(tgt, fun, arg=None, expr_form=\(aqglob\(aq, returner=\(aq\(aq, timeout=5)
Publish a command from the minion out to other minions.
.sp
Publications need to be enabled on the Salt master and the minion
needs to have permission to publish the command. The Salt master
will also prevent a recursive publication loop, this means that a
minion cannot command another minion to command another minion as
that would create an infinite command loop.
.sp
The expr_form argument is used to pass a target other than a glob into
the execution, the available options are:
.INDENT 7.0
.IP \(bu 2
glob
.IP \(bu 2
pcre
.IP \(bu 2
grain
.IP \(bu 2
grain_pcre
.IP \(bu 2
pillar
.IP \(bu 2
ipcidr
.IP \(bu 2
range
.IP \(bu 2
compound
.UNINDENT
.sp
Note that for pillar matches must be exact, both in the pillar matcher
and the compound matcher. No globbing is supported.
.sp
The arguments sent to the minion publish function are separated with
commas. This means that for a minion executing a command with multiple
args it will look like this:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt system.example.com publish.publish \(aq*\(aq user.add \(aqfoo,1020,1020\(aq
salt system.example.com publish.publish \(aqos:Fedora\(aq network.interfaces \(aq\(aq grain
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt system.example.com publish.publish \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
If you need to pass a value to a function argument and that value
contains an equal sign, you \fBmust\fP include the argument name.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq publish.publish test.kwarg arg=\(aqcheese=spam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.publish.runner(fun, arg=None, timeout=5)
Execute a runner on the master and return the data from the runner
function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt publish.runner manage.down
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.puppet
.sp
Execute puppet routines
.INDENT 0.0
.TP
.B salt.modules.puppet.disable()
New in version 2014.7.0.
.sp
Disable the puppet agent
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.disable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.puppet.enable()
New in version 2014.7.0.
.sp
Enable the puppet agent
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.disable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.puppet.fact(name, puppet=False)
Run facter for a specific fact
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.fact kernel
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.puppet.facts(puppet=False)
Run facter and return the results
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.facts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.puppet.noop(*args, **kwargs)
Execute a puppet noop run and return a dict with the stderr, stdout,
return code, etc. Usage is the same as for puppet.run.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.noop
salt \(aq*\(aq puppet.noop tags=basefiles::edit,apache::server
salt \(aq*\(aq puppet.noop debug
salt \(aq*\(aq puppet.noop apply /a/b/manifest.pp modulepath=/a/b/modules tags=basefiles::edit,apache::server
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.puppet.run(*args, **kwargs)
Execute a puppet run and return a dict with the stderr, stdout,
return code, etc. The first positional argument given is checked as a
subcommand. Following positional arguments should be ordered with arguments
required by the subcommand first, followed by non\-keyword arguments.
Tags are specified by a tag keyword and comma separated list of values. \-\-
\fI\%http://docs.puppetlabs.com/puppet/latest/reference/lang_tags.html\fP
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.run
salt \(aq*\(aq puppet.run tags=basefiles::edit,apache::server
salt \(aq*\(aq puppet.run agent onetime no\-daemonize no\-usecacheonfailure no\-splay ignorecache
salt \(aq*\(aq puppet.run debug
salt \(aq*\(aq puppet.run apply /a/b/manifest.pp modulepath=/a/b/modules tags=basefiles::edit,apache::server
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.puppet.status()
New in version 2014.7.0.
.sp
Display puppet agent status
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.puppet.summary()
New in version 2014.7.0.
.sp
Show a summary of the last puppet agent run
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq puppet.summary
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pw_group
.sp
Manage groups on FreeBSD
.INDENT 0.0
.TP
.B salt.modules.pw_group.add(name, gid=None, **kwargs)
Add the specified group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.add foo 3456
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.chgid(name, gid)
Change the gid for a named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.delete(name)
Remove the named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.delete foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.getent(refresh=False)
Return info on all groups
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_group.info(name)
Return information about a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.info foo
.ft P
.fi
.UNINDENT
.UNINDENT
.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=None, shell=None, unique=True, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True, **kwargs)
Add a user to the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chfullname(name, fullname)
Change the user\(aqs Full Name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chfullname foo "Foo Bar"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chgid(name, gid)
Change the default group of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgroups foo wheel,root True
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhome foo /home/users/foo True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chhomephone(name, homephone)
Change the user\(aqs Home Phone
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhomephone foo "7735551234"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chroomnumber(name, roomnumber)
Change the user\(aqs Room Number
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chroomnumber foo 123
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chshell(name, shell)
Change the default shell of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chshell foo /bin/zsh
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chuid(name, uid)
Change the uid for a named user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chuid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.chworkphone(name, workphone)
Change the user\(aqs Work Phone
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chworkphone foo "7735550123"
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.delete name remove=True force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.getent(refresh=False)
Return the list of all info for all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.info(name)
Return user information
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_groups foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pw_user.list_users()
Return a list of all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_users
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.pyenv
.sp
Manage python installations with pyenv.
.sp
New in version v2014.04.
.INDENT 0.0
.TP
.B salt.modules.pyenv.default(python=None, runas=None)
Returns or sets the currently defined default python.
.INDENT 7.0
.TP
.B python=None
The version to set as the default. Should match one of the versions
listed by \fI\%pyenv.versions\fP\&. Leave
blank to return the current default.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.default
salt \(aq*\(aq pyenv.default 2.0.0\-p0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.do(cmdline=None, runas=None)
Execute a python command with pyenv\(aqs shims from the user or the system.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.do \(aqgem list bundler\(aq
salt \(aq*\(aq pyenv.do \(aqgem list bundler\(aq deploy
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.do_with_python(python, cmdline, runas=None)
Execute a python command with pyenv\(aqs shims using a specific python version.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.do_with_python 2.0.0\-p0 \(aqgem list bundler\(aq
salt \(aq*\(aq pyenv.do_with_python 2.0.0\-p0 \(aqgem list bundler\(aq deploy
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.install(runas=None, path=None)
Install pyenv systemwide
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.install
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.install_python(python, runas=None)
Install a python implementation.
.INDENT 7.0
.TP
.B python
The version of python to install, should match one of the
versions listed by pyenv.list
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.install_python 2.0.0\-p0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.is_installed(runas=None)
Check if pyenv is installed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.is_installed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.list_(runas=None)
List the installable versions of python.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.rehash(runas=None)
Run pyenv rehash to update the installed shims.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.rehash
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.uninstall_python(python, runas=None)
Uninstall a python implementation.
.INDENT 7.0
.TP
.B python
The version of python to uninstall. Should match one of the versions
listed by \fI\%pyenv.versions\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.uninstall_python 2.0.0\-p0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.update(runas=None, path=None)
Updates the current versions of pyenv and python\-Build
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.update
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pyenv.versions(runas=None)
List the installed versions of python.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pyenv.versions
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.qemu_img
.SS Qemu\-img Command Wrapper
.sp
The qemu img command is wrapped for specific functions
.INDENT 0.0
.TP
.B depends
qemu\-img
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.qemu_img.make_image(location, size, fmt)
Create a blank virtual machine image file of the specified size in
megabytes. The image can be created in any format supported by qemu
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq qemu_img.make_image /tmp/image.qcow 2048 qcow2
salt \(aq*\(aq qemu_img.make_image /tmp/image.raw 10240 raw
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.qemu_nbd
.SS Qemu Command Wrapper
.sp
The qemu system comes with powerful tools, such as qemu\-img and qemu\-nbd which
are used here to build up kvm images.
.INDENT 0.0
.TP
.B salt.modules.qemu_nbd.clear(mnt)
Pass in the mnt dict returned from nbd_mount to unmount and disconnect
the image from nbd. If all of the partitions are unmounted return an
empty dict, otherwise return a dict containing the still mounted
partitions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq qemu_nbd.clear \(aq{"/mnt/foo": "/dev/nbd0p1"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.qemu_nbd.connect(image)
Activate nbd for an image file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq qemu_nbd.connect /tmp/image.raw
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.qemu_nbd.init(image)
Mount the named image via qemu\-nbd and return the mounted roots
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq qemu_nbd.init /srv/image.qcow2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.qemu_nbd.mount(nbd)
Pass in the nbd connection device location, mount all partitions and return
a dict of mount points
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq qemu_nbd.mount /dev/nbd0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.quota
.sp
Module for managing quotas on POSIX\-like systems.
.INDENT 0.0
.TP
.B salt.modules.quota.get_mode(device)
Report whether the quota system for this device is on or off
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq quota.get_mode
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.quota.off(device)
Turns off the quota system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq quota.off
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.quota.on(device)
Turns on the quota system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq quota.on
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.quota.report(mount)
Report on quotas for a specific volume
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq quota.report /media/data
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.quota.set_(device, **kwargs)
Calls out to setquota, for a specific user or group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq quota.set /media/data user=larry block\-soft\-limit=1048576
salt \(aq*\(aq quota.set /media/data group=painters file\-hard\-limit=1000
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.quota.stats()
Runs the quotastats command, and returns the parsed output
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq quota.stats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.quota.warn()
Runs the warnquota command, to send warning emails to users who
are over their quota limit.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq quota.warn
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rabbitmq
.sp
Module to provide RabbitMQ compatibility to Salt.
Todo: A lot, need to add cluster support, logging, and minion configuration
data.
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.add_user(name, password=None, runas=None)
Add a rabbitMQ user via rabbitmqctl user_add <user> <password>
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.add_user rabbit_user password
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.add_vhost(vhost, runas=None)
Adds a vhost via rabbitmqctl add_vhost.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq add_vhost \(aq<vhost_name>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.change_password(name, password, runas=None)
Changes a user\(aqs password.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.change_password rabbit_user password
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.clear_password(name, runas=None)
Removes a user\(aqs password.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.clear_password rabbit_user
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.cluster_status(runas=None)
return rabbitmq cluster_status
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.cluster_status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.delete_policy(vhost, name, runas=None)
Delete a policy based on rabbitmqctl clear_policy.
.sp
Reference: \fI\%http://www.rabbitmq.com/ha.html\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.delete_policy / HA\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.delete_user(name, runas=None)
Deletes a user via rabbitmqctl delete_user.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.delete_user rabbit_user
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.delete_vhost(vhost, runas=None)
Deletes a vhost rabbitmqctl delete_vhost.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.delete_vhost \(aq<vhost_name>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.disable_plugin(name, runas=None)
Disable a RabbitMQ plugin via the rabbitmq\-plugins command.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.disable_plugin foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.enable_plugin(name, runas=None)
Enable a RabbitMQ plugin via the rabbitmq\-plugins command.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.enable_plugin foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.force_reset(runas=None)
Forcefully Return a RabbitMQ node to its virgin state
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.force_reset
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.join_cluster(host, user=\(aqrabbit\(aq, runas=None)
Join a rabbit cluster
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.join_cluster \(aqrabbit\(aq \(aqrabbit.example.com\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.list_permissions(vhost, runas=None)
Lists permissions for vhost via rabbitmqctl list_permissions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.list_permissions \(aq/myvhost\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.list_policies(runas=None)
Return a dictionary of policies nested by vhost and name
based on the data returned from rabbitmqctl list_policies.
.sp
Reference: \fI\%http://www.rabbitmq.com/ha.html\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.list_policies\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.list_queues(runas=None, *kwargs)
Returns queue details of the / virtual host
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.list_queues messages consumers
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.list_queues_vhost(vhost, runas=None, *kwargs)
Returns queue details of specified virtual host. This command will consider
first parameter as the vhost name and rest will be treated as
queueinfoitem. For getting details on vhost \fB/\fP, use \fI\%list_queues\fP instead).
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.list_queues messages consumers
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.list_user_permissions(name, runas=None)
List permissions for a user via rabbitmqctl list_user_permissions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.list_user_permissions \(aquser\(aq.
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.list_users(runas=None)
Return a list of users based off of rabbitmqctl user_list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.list_users
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.list_vhosts(runas=None)
Return a list of vhost based on rabbitmqctl list_vhosts.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.list_vhosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.plugin_is_enabled(name, runas=None)
Return whether the plugin is enabled.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.plugin_is_enabled foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.policy_exists(vhost, name, runas=None)
Return whether the policy exists based on rabbitmqctl list_policies.
.sp
Reference: \fI\%http://www.rabbitmq.com/ha.html\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.policy_exists / HA
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.reset(runas=None)
Return a RabbitMQ node to its virgin state
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.reset
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.set_permissions(vhost, user, conf=\(aq.*\(aq, write=\(aq.*\(aq, read=\(aq.*\(aq, runas=None)
Sets permissions for vhost via rabbitmqctl set_permissions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.set_permissions \(aqmyvhost\(aq \(aqmyuser\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.set_policy(vhost, name, pattern, definition, priority=None, runas=None)
Set a policy based on rabbitmqctl set_policy.
.sp
Reference: \fI\%http://www.rabbitmq.com/ha.html\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.set_policy / HA \(aq.*\(aq \(aq{"ha\-mode": "all"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.set_user_tags(name, tags, runas=None)
Add user tags via rabbitmqctl set_user_tags
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.set_user_tags \(aqmyadmin\(aq \(aqadministrator\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.start_app(runas=None)
Start the RabbitMQ application.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.start_app
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.status(runas=None)
return rabbitmq status
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.stop_app(runas=None)
Stops the RabbitMQ application, leaving the Erlang node running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.stop_app
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.user_exists(name, runas=None)
Return whether the user exists based on rabbitmqctl list_users.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.user_exists rabbit_user
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rabbitmq.vhost_exists(name, runas=None)
Return whether the vhost exists based on rabbitmqctl list_vhosts.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rabbitmq.vhost_exists rabbit_host
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.raet_publish
.sp
Publish a command from a minion to a target
.INDENT 0.0
.TP
.B salt.modules.raet_publish.full_data(tgt, fun, arg=None, expr_form=\(aqglob\(aq, returner=\(aq\(aq, timeout=5)
Return the full data about the publication, this is invoked in the same
way as the publish function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt system.example.com publish.full_data \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
If you need to pass a value to a function argument and that value
contains an equal sign, you \fBmust\fP include the argument name.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq publish.full_data test.kwarg arg=\(aqcheese=spam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.raet_publish.publish(tgt, fun, arg=None, expr_form=\(aqglob\(aq, returner=\(aq\(aq, timeout=5)
Publish a command from the minion out to other minions.
.sp
Publications need to be enabled on the Salt master and the minion
needs to have permission to publish the command. The Salt master
will also prevent a recursive publication loop, this means that a
minion cannot command another minion to command another minion as
that would create an infinite command loop.
.sp
The expr_form argument is used to pass a target other than a glob into
the execution, the available options are:
.INDENT 7.0
.IP \(bu 2
glob
.IP \(bu 2
pcre
.IP \(bu 2
grain
.IP \(bu 2
grain_pcre
.IP \(bu 2
pillar
.IP \(bu 2
ipcidr
.IP \(bu 2
range
.IP \(bu 2
compound
.UNINDENT
.sp
The arguments sent to the minion publish function are separated with
commas. This means that for a minion executing a command with multiple
args it will look like this:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt system.example.com publish.publish \(aq*\(aq user.add \(aqfoo,1020,1020\(aq
salt system.example.com publish.publish \(aqos:Fedora\(aq network.interfaces \(aq\(aq grain
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt system.example.com publish.publish \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
If you need to pass a value to a function argument and that value
contains an equal sign, you \fBmust\fP include the argument name.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq publish.publish test.kwarg arg=\(aqcheese=spam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.raet_publish.runner(fun, arg=None, timeout=5)
Execute a runner on the master and return the data from the runner
function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt publish.runner manage.down
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rbenv
.sp
Manage ruby installations with rbenv.
.sp
New in version 0.16.0.
.INDENT 0.0
.TP
.B salt.modules.rbenv.default(ruby=None, runas=None)
Returns or sets the currently defined default ruby.
.INDENT 7.0
.TP
.B ruby=None
The version to set as the default. Should match one of the versions
listed by \fI\%rbenv.versions\fP\&. Leave
blank to return the current default.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.default
salt \(aq*\(aq rbenv.default 2.0.0\-p0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.do(cmdline=None, runas=None)
Execute a ruby command with rbenv\(aqs shims from the user or the system.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.do \(aqgem list bundler\(aq
salt \(aq*\(aq rbenv.do \(aqgem list bundler\(aq deploy
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.do_with_ruby(ruby, cmdline, runas=None)
Execute a ruby command with rbenv\(aqs shims using a specific ruby version.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.do_with_ruby 2.0.0\-p0 \(aqgem list bundler\(aq
salt \(aq*\(aq rbenv.do_with_ruby 2.0.0\-p0 \(aqgem list bundler\(aq deploy
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.install(runas=None, path=None)
Install Rbenv systemwide
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.install
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.install_ruby(ruby, runas=None)
Install a ruby implementation.
.INDENT 7.0
.TP
.B ruby
The version of Ruby to install, should match one of the
versions listed by rbenv.list
.UNINDENT
.sp
Additional environment variables can be configured in pillar /
grains / master:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
rbenv:
build_env: \(aqCONFIGURE_OPTS="\-\-no\-tcmalloc" CFLAGS="\-fno\-tree\-dce"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.install_ruby 2.0.0\-p0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.is_installed(runas=None)
Check if Rbenv is installed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.is_installed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.list_(runas=None)
List the installable versions of ruby.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.rehash(runas=None)
Run rbenv rehash to update the installed shims.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.rehash
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.uninstall_ruby(ruby, runas=None)
Uninstall a ruby implementation.
.INDENT 7.0
.TP
.B ruby
The version of ruby to uninstall. Should match one of the versions
listed by \fI\%rbenv.versions\fP
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.uninstall_ruby 2.0.0\-p0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.update(runas=None, path=None)
Updates the current versions of Rbenv and Ruby\-Build
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.update
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.versions(runas=None)
List the installed versions of ruby.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rbenv.versions
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rdp
.sp
Manage RDP Service on Windows servers
.INDENT 0.0
.TP
.B salt.modules.rdp.disable()
Disable RDP the service on the server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rdp.disable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rdp.enable()
Enable RDP the service on the server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rdp.enable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rdp.status()
Show if rdp is enabled on the server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rdp.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.redis
.sp
Module to provide redis functionality to Salt
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B configuration
This module requires the redis python module and uses the
following defaults which may be overridden in the minion configuration:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
redis.host: \(aqlocalhost\(aq
redis.port: 6379
redis.db: 0
redis.password: None
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.bgrewriteaof(host=None, port=None, db=None, password=None)
Asynchronously rewrite the append\-only file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.bgrewriteaof
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.bgsave(host=None, port=None, db=None, password=None)
Asynchronously save the dataset to disk
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.bgsave
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.config_get(pattern=\(aq*\(aq, host=None, port=None, db=None, password=None)
Get redis server configuration values
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.config_get
salt \(aq*\(aq redis.config_get port
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.config_set(name, value, host=None, port=None, db=None, password=None)
Set redis server configuration values
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.config_set masterauth luv_kittens
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.dbsize(host=None, port=None, db=None, password=None)
Return the number of keys in the selected database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.dbsize
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.delete(*keys, **connection_args)
Deletes the keys from redis, returns number of keys deleted
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.delete foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.exists(key, host=None, port=None, db=None, password=None)
Return true if the key exists in redis
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.exists foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.expire(key, seconds, host=None, port=None, db=None, password=None)
Set a keys time to live in seconds
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.expire foo 300
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.expireat(key, timestamp, host=None, port=None, db=None, password=None)
Set a keys expire at given UNIX time
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.expireat foo 1400000000
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.flushall(host=None, port=None, db=None, password=None)
Remove all keys from all databases
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.flushall
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.flushdb(host=None, port=None, db=None, password=None)
Remove all keys from the selected database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.flushdb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.get_key(key, host=None, port=None, db=None, password=None)
Get redis key value
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.get_key foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.hget(key, field, host=None, port=None, db=None, password=None)
Get specific field value from a redis hash, returns dict
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.hget foo_hash bar_field
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.hgetall(key, host=None, port=None, db=None, password=None)
Get all fields and values from a redis hash, returns dict
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.hgetall foo_hash
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.info(host=None, port=None, db=None, password=None)
Get information and statistics about the server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.key_type(key, host=None, port=None, db=None, password=None)
Get redis key type
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.type foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.keys(pattern=\(aq*\(aq, host=None, port=None, db=None, password=None)
Get redis keys, supports glob style patterns
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.keys
salt \(aq*\(aq redis.keys test*
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.lastsave(host=None, port=None, db=None, password=None)
Get the UNIX time in seconds of the last successful save to disk
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.lastsave
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.llen(key, host=None, port=None, db=None, password=None)
Get the length of a list in Redis
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.llen foo_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.lrange(key, start, stop, host=None, port=None, db=None, password=None)
Get a range of values from a list in Redis
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.lrange foo_list 0 10
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.ping(host=None, port=None, db=None, password=None)
Ping the server, returns False on connection errors
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.save(host=None, port=None, db=None, password=None)
Synchronously save the dataset to disk
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.save
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.set_key(key, value, host=None, port=None, db=None, password=None)
Set redis key value
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.set_key foo bar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.shutdown(host=None, port=None, db=None, password=None)
Synchronously save the dataset to disk and then shut down the server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.shutdown
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.slaveof(master_host=None, master_port=None, host=None, port=None, db=None, password=None)
Make the server a slave of another instance, or promote it as master
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Become slave of redis\-n01.example.com:6379
salt \(aq*\(aq redis.slaveof redis\-n01.example.com 6379
salt \(aq*\(aq redis.slaveof redis\-n01.example.com
# Become master
salt \(aq*\(aq redis.slaveof
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.smembers(key, host=None, port=None, db=None, password=None)
Get members in a Redis set
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.smembers foo_set
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.time(host=None, port=None, db=None, password=None)
Return the current server UNIX time in seconds
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.time
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.zcard(key, host=None, port=None, db=None, password=None)
Get the length of a sorted set in Redis
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.zcard foo_sorted
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.redismod.zrange(key, start, stop, host=None, port=None, db=None, password=None)
Get a range of values from a sorted set in Redis by index
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq redis.zrange foo_sorted 0 10
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.reg
.sp
Manage the registry on Windows
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
winreg Python module
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.modules.reg.Registry
Delay \(aq_winreg\(aq usage until this module is used
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.reg.create_key(hkey, path, key, value=None, reflection=True)
Create a registry key
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq reg.create_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq \(aq0.97\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.reg.delete_key(hkey, path, key, reflection=True)
Delete a registry key
.sp
Note: This cannot delete a key with subkeys
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq reg.delete_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.reg.read_key(hkey, path, key, reflection=True)
Read registry key value
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq reg.read_key HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.reg.set_key(hkey, path, key, value, vtype=\(aqREG_DWORD\(aq, reflection=True)
Set a registry key
vtype: \fI\%http://docs.python.org/2/library/_winreg.html#value\-types\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq reg.set_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq \(aq0.97\(aq REG_DWORD
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rest_package
.sp
Service support for the REST example
.INDENT 0.0
.TP
.B salt.modules.rest_package.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs)
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_package.installed(name, version=None, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, sources=None, **kwargs)
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_package.list_pkgs(versions_as_list=False, **kwargs)
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_package.remove(name=None, pkgs=None, **kwargs)
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_package.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rest_sample
.sp
Module for interfacing to the REST example
.sp
pre\-pre\-ALPHA QUALITY code.
.INDENT 0.0
.TP
.B salt.modules.rest_sample.grains_refresh()
Refresh the cache.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_sample.ping()
.UNINDENT
.SS salt.modules.rest_service
.sp
Service support for the REST example
.INDENT 0.0
.TP
.B salt.modules.rest_service.list_()
List services.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rest_service.list <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_service.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rest_service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_service.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rest_service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_service.status(name)
Return the status for a service, returns a bool whether the service is
running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rest_service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rest_service.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rest_service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.ret
.sp
Module to integrate with the returner system and retrieve data sent to a salt returner
.INDENT 0.0
.TP
.B salt.modules.ret.get_fun(returner, fun)
Return info about last time fun was called on each minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ret.get_fun mysql network.interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ret.get_jid(returner, jid)
Return the information for a specified job id
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ret.get_jid redis 20421104181954700505
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ret.get_jids(returner)
Return a list of all job ids
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ret.get_jids mysql
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ret.get_minions(returner)
Return a list of all minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ret.get_minions mysql
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rh_ip
.sp
The networking module for RHEL/Fedora based distros
.INDENT 0.0
.TP
.B salt.modules.rh_ip.apply_network_settings(**settings)
Apply global network configuration.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.apply_network_settings
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.build_bond(iface, **settings)
Create a bond script in /etc/modprobe.d with the passed settings
and load the bonding kernel module.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_bond bond0 mode=balance\-alb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.build_interface(iface, iface_type, enabled, **settings)
Build an interface script for a network interface.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_interface eth0 eth <settings>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.build_network_settings(**settings)
Build the global network script.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_network_settings <settings>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.build_routes(iface, **settings)
Build a route script for a network interface.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.build_routes eth0 <settings>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.down(iface, iface_type)
Shutdown a network interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.down eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.get_bond(iface)
Return the content of a bond script
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_bond bond0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.get_interface(iface)
Return the contents of an interface script
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_interface eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.get_network_settings()
Return the contents of the global network script.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_network_settings
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.get_routes(iface)
Return the contents of the interface routes script.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.get_routes eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_ip.up(iface, iface_type)
Start up a network interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ip.up eth0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rh_service
.sp
Service support for RHEL\-based systems, including support for both upstart and sysvinit
.INDENT 0.0
.TP
.B salt.modules.rh_service.available(name, limit=\(aq\(aq)
Return True if the named service is available. Use the \fBlimit\fP param to
restrict results to services of that type.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
salt \(aq*\(aq service.available sshd limit=upstart
salt \(aq*\(aq service.available sshd limit=sysvinit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.disable(name, **kwargs)
Disable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.disabled(name)
Check to see if the named service is disabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.enable(name, **kwargs)
Enable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.enabled(name)
Check to see if the named service is enabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.get_all(limit=\(aq\(aq)
Return all installed services. Use the \fBlimit\fP param to restrict results
to services of that type.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
salt \(aq*\(aq service.get_all limit=upstart
salt \(aq*\(aq service.get_all limit=sysvinit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.get_disabled(limit=\(aq\(aq)
Return the disabled services. Use the \fBlimit\fP param to restrict results
to services of that type.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
salt \(aq*\(aq service.get_disabled limit=upstart
salt \(aq*\(aq service.get_disabled limit=sysvinit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.get_enabled(limit=\(aq\(aq)
Return the enabled services. Use the \fBlimit\fP param to restrict results
to services of that type.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
salt \(aq*\(aq service.get_enabled limit=upstart
salt \(aq*\(aq service.get_enabled limit=sysvinit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.missing(name, limit=\(aq\(aq)
The inverse of service.available.
Return True if the named service is not available. Use the \fBlimit\fP param to
restrict results to services of that type.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
salt \(aq*\(aq service.missing sshd limit=upstart
salt \(aq*\(aq service.missing sshd limit=sysvinit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.reload_(name)
Reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.status(name, sig=None)
Return the status for a service, returns a bool whether the service is
running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rh_service.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.riak
.SS Riak Salt Module
.sp
Author: David Boucha <\fI\%boucha@gmail.com\fP>
.INDENT 0.0
.TP
.B salt.modules.riak.cluster_commit()
Commit Cluster Changes
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq riak.cluster_commit
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.riak.cluster_join(riak_user=None, riak_host=None)
Join a Riak cluster
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq riak.cluster_join <user> <host>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.riak.cluster_plan()
Review Cluster Plan
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq riak.cluster_plan
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.riak.member_status()
Get cluster member status
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq riak.member_status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.riak.start()
Start Riak
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq riak.start
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.riak.stop()
Stop Riak
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq riak.stop
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rpm
.sp
Support for rpm
.INDENT 0.0
.TP
.B salt.modules.rpm.file_dict(*packages)
List the files that belong to a package, sorted by group. Not specifying
any packages will return a list of _every_ file on the system\(aqs rpm
database (not generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.file_dict httpd
salt \(aq*\(aq lowpkg.file_dict httpd postfix
salt \(aq*\(aq lowpkg.file_dict
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rpm.file_list(*packages)
List the files that belong to a package. Not specifying any packages will
return a list of _every_ file on the system\(aqs rpm database (not generally
recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.file_list httpd
salt \(aq*\(aq lowpkg.file_list httpd postfix
salt \(aq*\(aq lowpkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rpm.list_pkgs(*packages)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rpm.verify(*package, **kwargs)
Runs an rpm \-Va on a system, and returns the results in a dict
.sp
Files with an attribute of config, doc, ghost, license or readme in the
package header can be ignored using the \fBignore_types\fP keyword argument
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq lowpkg.verify
salt \(aq*\(aq lowpkg.verify httpd
salt \(aq*\(aq lowpkg.verify \(aqhttpd postfix\(aq
salt \(aq*\(aq lowpkg.verify \(aqhttpd postfix\(aq ignore_types=[\(aqconfig\(aq,\(aqdoc\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rsync
.sp
Wrapper for rsync
.sp
New in version 2014.1.0.
.sp
This data can also be passed into \fBpillar\fP\&.
Options passed into opts will overwrite options passed into pillar.
.INDENT 0.0
.TP
.B salt.modules.rsync.config(confile=\(aq/etc/rsyncd.conf\(aq)
Return rsync config
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rsync.config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rsync.rsync(src, dst, delete=False, force=False, update=False, passwordfile=None, exclude=None, excludefrom=None)
Rsync files from src to dst
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rsync.rsync {src} {dst} {delete=True} {update=True} {passwordfile=/etc/pass.crt} {exclude=xx}
salt \(aq*\(aq rsync.rsync {src} {dst} {delete=True} {excludefrom=/xx.ini}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rsync.version()
Return rsync version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rsync.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.rvm
.sp
Manage ruby installations and gemsets with RVM, the Ruby Version Manager.
.INDENT 0.0
.TP
.B salt.modules.rvm.do(ruby, command, runas=None, cwd=None)
Execute a command in an RVM controlled environment.
.INDENT 7.0
.TP
.B ruby:
The ruby to use.
.TP
.B command:
The command to execute.
.TP
.B runas
None
The user to run rvm as.
.TP
.B cwd
None
The current working directory.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.do 2.0.0 <command>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.gemset_copy(source, destination, runas=None)
Copy all gems from one gemset to another.
.INDENT 7.0
.TP
.B source
The name of the gemset to copy, complete with ruby version.
.TP
.B destination
The destination gemset.
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.gemset_copy foobar bazquo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.gemset_create(ruby, gemset, runas=None)
Creates a gemset.
.INDENT 7.0
.TP
.B ruby
The ruby version to create the gemset for.
.TP
.B gemset
The name of the gemset to create.
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.gemset_create 2.0.0 foobar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.gemset_delete(ruby, gemset, runas=None)
Deletes a gemset.
.INDENT 7.0
.TP
.B ruby
The ruby version the gemset belongs to.
.TP
.B gemset
The gemset to delete.
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.gemset_delete 2.0.0 foobar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.gemset_empty(ruby, gemset, runas=None)
Remove all gems from a gemset.
.INDENT 7.0
.TP
.B ruby
The ruby version the gemset belongs to.
.TP
.B gemset
The gemset to empty.
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.gemset_empty 2.0.0 foobar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.gemset_list(ruby=\(aqdefault\(aq, runas=None)
List all gemsets for the given ruby.
.INDENT 7.0
.TP
.B ruby
default
The ruby version to list the gemsets for
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.gemset_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.gemset_list_all(runas=None)
List all gemsets for all installed rubies.
.sp
Note that you must have set a default ruby before this can work.
.INDENT 7.0
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.gemset_list_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.get(version=\(aqstable\(aq, runas=None)
Update RVM.
.INDENT 7.0
.TP
.B version
stable
Which version of RVM to install, e.g. stable or head.
.TP
.B ruby
The version of ruby to reinstall.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.get
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.install(runas=None)
Install RVM system wide.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.install
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.install_ruby(ruby, runas=None)
Install a ruby implementation.
.INDENT 7.0
.TP
.B ruby
The version of ruby to install.
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.install_ruby 1.9.3\-p385
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.is_installed(runas=None)
Check if RVM is installed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.is_installed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.list_(runas=None)
List all rvm installed rubies.
.INDENT 7.0
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.reinstall_ruby(ruby, runas=None)
Reinstall a ruby implementation.
.INDENT 7.0
.TP
.B ruby
The version of ruby to reinstall.
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.reinstall_ruby 1.9.3\-p385
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.rubygems(ruby, version, runas=None)
Installs a specific rubygems version in the given ruby.
.INDENT 7.0
.TP
.B ruby
The ruby to install rubygems for.
.TP
.B version
The version of rubygems to install or \(aqremove\(aq to use the version that
ships with 1.9
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.rubygems 2.0.0 1.8.24
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.set_default(ruby, runas=None)
Set the default ruby.
.INDENT 7.0
.TP
.B ruby
The version of ruby to make the default.
.TP
.B runas
None
The user to run rvm as.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.set_default 2.0.0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rvm.wrapper(ruby_string, wrapper_prefix, runas=None, *binaries)
Install RVM wrapper scripts.
.INDENT 7.0
.TP
.B ruby_string
Ruby/gemset to install wrappers for.
.TP
.B wrapper_prefix
What to prepend to the name of the generated wrapper binaries.
.TP
.B runas
None
The user to run rvm as.
.TP
.B binaries
None
The names of the binaries to create wrappers for. When nothing is
given, wrappers for ruby, gem, rake, irb, rdoc, ri and testrb are
generated.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq rvm.wrapper <ruby_string> <wrapper_prefix>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.s3
.sp
Connection module for Amazon S3
.INDENT 0.0
.TP
.B configuration
This module accepts explicit s3 credentials but can also utilize
IAM roles assigned to the instance trough Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More Information available at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
s3.keyid: GKTADJGHEIQSXMKKRBJ08H
s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A service_url may also be specified in the configuration:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
s3.service_url: s3.amazonaws.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a service_url is not specified, the default is s3.amazonaws.com. This
may appear in various documentation as an "endpoint". A comprehensive list
for Amazon S3 may be found at:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The service_url will form the basis for the final endpoint that is used to
query the service.
.sp
SSL verification may also be turned off in the configuration:
.sp
s3.verify_ssl: False
.sp
This is required if using S3 bucket names that contain a period, as
these will not match Amazon\(aqs S3 wildcard certificates. Certificate
verification is enabled by default.
.sp
This module should be usable to query other S3\-like services, such as
Eucalyptus.
.TP
.B depends
requests
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.s3.delete(bucket, path=None, action=None, key=None, keyid=None, service_url=None, verify_ssl=None)
Delete a bucket, or delete an object from a bucket.
.sp
CLI Example to delete a bucket:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.delete mybucket
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to delete an object from a bucket:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.delete mybucket remoteobject
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.s3.get(bucket=None, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None)
List the contents of a bucket, or return an object from a bucket. Set
return_bin to True in order to retrieve an object wholesale. Otherwise,
Salt will attempt to parse an XML response.
.sp
CLI Example to list buckets:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.get
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to list the contents of a bucket:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.get mybucket
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to return the binary contents of an object:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.get mybucket myfile.png return_bin=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to save the binary contents of an object to a local file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.get mybucket myfile.png local_file=/tmp/myfile.png
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is also possible to perform an action on a bucket. Currently, S3
supports the following actions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
acl
cors
lifecycle
policy
location
logging
notification
tagging
versions
requestPayment
versioning
website
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To perform an action on a bucket:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.get mybucket myfile.png action=acl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.s3.head(bucket, path=None, key=None, keyid=None, service_url=None, verify_ssl=None)
Return the metadata for a bucket, or an object in a bucket.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.head mybucket
salt myminion s3.head mybucket myfile.png
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.s3.put(bucket, path=None, return_bin=False, action=None, local_file=None, key=None, keyid=None, service_url=None, verify_ssl=None)
Create a new bucket, or upload an object to a bucket.
.sp
CLI Example to create a bucket:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.put mybucket
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to upload an object to a bucket:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion s3.put mybucket remotepath local_file=/path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.saltcloudmod
.sp
Control a salt cloud system
.INDENT 0.0
.TP
.B salt.modules.saltcloudmod.create(name, profile)
Create the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt <minion\-id> saltcloud.create webserver rackspace_centos_512
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.saltutil
.sp
The Saltutil module is used to manage the state of the salt minion itself. It
is used to manage minion modules as well as automate updates to the salt
minion.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
esky Python module for update functionality
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.clear_cache()
Forcibly removes all caches on a minion.
.sp
New in version 2014.7.0.
.sp
WARNING: The safest way to clear a minion cache is by first stopping
the minion and then deleting the cache files before restarting it.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.clear_cache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.cmd(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, ssh=False, **kwargs)
Assuming this minion is a master, execute a salt command
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.cmd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.cmd_iter(tgt, fun, arg=(), timeout=None, expr_form=\(aqglob\(aq, ret=\(aq\(aq, kwarg=None, ssh=False, **kwargs)
Assuming this minion is a master, execute a salt command
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.cmd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.find_cached_job(jid)
Return the data for a specific cached job id
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.find_cached_job <job id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.find_job(jid)
Return the data for a specific job id
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.find_job <job id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.is_running(fun)
If the named function is running return the data associated with it/them.
The argument can be a glob
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.is_running state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.kill_job(jid)
Sends a kill signal (SIGKILL 9) to the named salt job\(aqs process
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.kill_job <job id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.mmodule(saltenv, fun, *args, **kwargs)
Loads minion modules from an environment so that they can be used in pillars
for that environment
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.mmodule base test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.refresh_modules()
Signal the minion to refresh the module and grain data
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.refresh_modules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.refresh_pillar()
Signal the minion to refresh the pillar data.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.refresh_pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.regen_keys()
Used to regenerate the minion keys.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.regen_keys
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.revoke_auth()
The minion sends a request to the master to revoke its own key.
Note that the minion session will be revoked and the minion may
not be able to return the result of this command back to the master.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.revoke_auth
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.runner(fun, **kwargs)
Execute a runner module (this function must be run on the master)
.sp
New in version 2014.7.
.INDENT 7.0
.TP
.B name
The name of the function to run
.TP
.B kwargs
Any keyword arguments to pass to the runner function
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.runner jobs.list_jobs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.running()
Return the data on all running salt processes on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.running
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.signal_job(jid, sig)
Sends a signal to the named salt job\(aqs process
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.signal_job <job id> 15
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_all(saltenv=None, refresh=True)
Sync down all of the dynamic modules from the file server for a specific
environment
.INDENT 7.0
.TP
.B refresh
True
Also refresh the execution modules available to the minion.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_grains(saltenv=None, refresh=True)
Sync the grains from the _grains directory on the salt master file
server. This function is environment aware, pass the desired environment
to grab the contents of the _grains directory, base is the default
environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_grains
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_modules(saltenv=None, refresh=True)
Sync the modules from the _modules directory on the salt master file
server. This function is environment aware, pass the desired environment
to grab the contents of the _modules directory, base is the default
environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_modules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_outputters(saltenv=None, refresh=True)
Sync the outputters from the _outputters directory on the salt master file
server. This function is environment aware, pass the desired environment
to grab the contents of the _outputters directory, base is the default
environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_outputters
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_renderers(saltenv=None, refresh=True)
Sync the renderers from the _renderers directory on the salt master file
server. This function is environment aware, pass the desired environment
to grab the contents of the _renderers directory, base is the default
environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_renderers
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_returners(saltenv=None, refresh=True)
Sync the returners from the _returners directory on the salt master file
server. This function is environment aware, pass the desired environment
to grab the contents of the _returners directory, base is the default
environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_returners
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_states(saltenv=None, refresh=True)
Sync the states from the _states directory on the salt master file
server. This function is environment aware, pass the desired environment
to grab the contents of the _states directory, base is the default
environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_states
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.sync_utils(saltenv=None, refresh=True)
Sync utility source files from the _utils directory on the salt master file
server. This function is environment aware, pass the desired environment
to grab the contents of the _utils directory, base is the default
environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_utils
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.term_job(jid)
Sends a termination signal (SIGTERM 15) to the named salt job\(aqs process
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.term_job <job id>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.update(version=None)
Update the salt minion from the URL defined in opts[\(aqupdate_url\(aq]
SaltStack, Inc provides the latest builds here:
update_url: \fI\%http://docs.saltstack.com/downloads/\fP
.sp
Be aware that as of 2014\-8\-11 there\(aqs a bug in esky such that only the
latest version available in the update_url can be downloaded and installed.
.sp
This feature requires the minion to be running a bdist_esky build.
.sp
The version number is optional and will default to the most recent version
available at opts[\(aqupdate_url\(aq].
.sp
Returns details about the transaction upon completion.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.update
salt \(aq*\(aq saltutil.update 0.10.3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.saltutil.wheel(fun, **kwargs)
Execute a wheel module (this function must be run on the master)
.sp
New in version 2014.7.
.INDENT 7.0
.TP
.B name
The name of the function to run
.TP
.B kwargs
Any keyword arguments to pass to the wheel function
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.wheel key.accept match=jerry
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.schedule
.sp
Module for manging the Salt schedule on a minion
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B salt.modules.schedule.add(name, **kwargs)
Add a job to the schedule
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.add job1 function=\(aqtest.ping\(aq seconds=3600
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.build_schedule_item(name, **kwargs)
Build a schedule job
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.build_schedule_item job1 function=\(aqtest.ping\(aq seconds=3600
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.delete(name, **kwargs)
Delete a job from the minion\(aqs schedule
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.delete job1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.disable(**kwargs)
Disable all scheduled jobs on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.disable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.disable_job(name, **kwargs)
Disable a job in the minion\(aqs schedule
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.disable_job job1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.enable(**kwargs)
Enable all scheduled jobs on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.enable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.enable_job(name, **kwargs)
Enable a job in the minion\(aqs schedule
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.enable_job job1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.list_(show_all=False, return_yaml=True)
List the jobs currently scheduled on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.list
salt \(aq*\(aq schedule.list show_all=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.modify(name, **kwargs)
Modify an existing job in the schedule
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.modify job1 function=\(aqtest.ping\(aq seconds=3600
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.purge(**kwargs)
Purge all the jobs currently scheduled on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.purge
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.reload_()
Reload saved scheduled jobs on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.reload
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.run_job(name, force=False)
Run a scheduled job on the minion immediately
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.run_job job1
salt \(aq*\(aq schedule.run_job job1 force=True
Force the job to run even if it is disabled.
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.schedule.save()
Save all scheduled jobs on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq schedule.save
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.seed
.sp
Virtual machine image management tools
.INDENT 0.0
.TP
.B salt.modules.seed.apply_(path, id_=None, config=None, approve_key=True, install=True, prep_install=False)
Seed a location (disk image, directory, or block device) with the
minion config, approve the minion\(aqs key, and/or install salt\-minion.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq seed.apply path id [config=config_data] \e
[gen_key=(true|false)] [approve_key=(true|false)] \e
[install=(true|false)]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B path
Full path to the directory, device, or disk image on the target
minion\(aqs file system.
.TP
.B id
Minion id with which to seed the path.
.TP
.B config
Minion configuration options. By default, the \(aqmaster\(aq option is set to
the target host\(aqs \(aqmaster\(aq.
.TP
.B approve_key
Request a pre\-approval of the generated minion key. Requires
that the salt\-master be configured to either auto\-accept all keys or
expect a signing request from the target host. Default: true.
.TP
.B install
Install salt\-minion, if absent. Default: true.
.TP
.B prep_install
Prepare the bootstrap script, but don\(aqt run it. Default: false
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.seed.mkconfig(config=None, tmp=None, id_=None, approve_key=True, pub_key=None, priv_key=None)
Generate keys and config and put them in a tmp directory.
.INDENT 7.0
.TP
.B pub_key
absolute path or file content of an optional preseeded salt key
.TP
.B priv_key
absolute path or file content of an optional preseeded salt key
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\(aq seed.mkconfig [config=config_data] [tmp=tmp_dir] \e
[id_=minion_id] [approve_key=(true|false)]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.selinux
.sp
Execute calls on selinux
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module requires the \fBsemanage\fP and \fBsetsebool\fP commands to be
available on the minion. On RHEL\-based distros, this means that the
\fBpolicycoreutils\fP and \fBpolicycoreutils\-python\fP packages must be
installed. If not on a RHEL\-based distribution, consult the selinux
documentation for your distro to ensure that the proper packages are
installed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.getenforce()
Return the mode selinux is running in
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq selinux.getenforce
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.getsebool(boolean)
Return the information on a specific selinux boolean
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq selinux.getsebool virt_use_usb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.list_sebool()
Return a structure listing all of the selinux booleans on the system and
what state they are in
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq selinux.list_sebool
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.selinux_fs_path(*args)
Return the location of the SELinux VFS directory
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq selinux.selinux_fs_path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.setenforce(mode)
Set the SELinux enforcing mode
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq selinux.setenforce enforcing
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.setsebool(boolean, value, persist=False)
Set the value for a boolean
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq selinux.setsebool virt_use_usb off
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.selinux.setsebools(pairs, persist=False)
Set the value of multiple booleans
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq selinux.setsebools \(aq{virt_use_usb: on, squid_use_tproxy: off}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.sensors
.sp
Read lm\-sensors
.sp
New in version 2014.1.3.
.INDENT 0.0
.TP
.B salt.modules.sensors.sense(chip, fahrenheit=False)
Gather lm\-sensors data from a given chip
.sp
To determine the chip to query, use the \(aqsensors\(aq command
and see the leading line in the block.
.sp
Example:
.sp
/usr/bin/sensors
.sp
coretemp\-isa\-0000
Adapter: ISA adapter
Physical id 0: +56.0°C (high = +87.0°C, crit = +105.0°C)
Core 0: +52.0°C (high = +87.0°C, crit = +105.0°C)
Core 1: +50.0°C (high = +87.0°C, crit = +105.0°C)
Core 2: +56.0°C (high = +87.0°C, crit = +105.0°C)
Core 3: +53.0°C (high = +87.0°C, crit = +105.0°C)
.sp
Given the above, the chip is \(aqcoretemp\-isa\-0000\(aq.
.UNINDENT
.SS salt.modules.serverdensity_device
.SS Wrapper around Server Density API
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B salt.modules.serverdensity_device.create(name, **params)
Function to create device in Server Density. For more info, see the \fI\%API
docs\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq serverdensity_device.create lama
salt \(aq*\(aq serverdensity_device.create rich_lama group=lama_band installedRAM=32768
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.serverdensity_device.delete(device_id)
Delete a device from Server Density. For more information, see the \fI\%API
docs\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq serverdensity_device.delete 51f7eafcdba4bb235e000ae4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.serverdensity_device.get_sd_auth(val, sd_auth_pillar_name=\(aqserverdensity\(aq)
Returns requested Server Density authentication value from pillar.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq serverdensity_device.get_sd_auth <val>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.serverdensity_device.install_agent(agent_key)
Function downloads Server Density installation agent, and installs sd\-agent
with agent_key.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq serverdensity_device.install_agent c2bbdd6689ff46282bdaa07555641498
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.serverdensity_device.ls(**params)
List devices in Server Density
.sp
Results will be filtered by any params passed to this function. For more
information, see the API docs on \fI\%listing\fP and \fI\%searching\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq serverdensity_device.ls
salt \(aq*\(aq serverdensity_device.ls name=lama
salt \(aq*\(aq serverdensity_device.ls name=lama group=lama_band installedRAM=32768
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.serverdensity_device.update(device_id, **params)
Updates device information in Server Density. For more information see the
\fI\%API docs\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=lama group=lama_band
salt \(aq*\(aq serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=better_lama group=rock_lamas swapSpace=512
.ft P
.fi
.UNINDENT
.UNINDENT
.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.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.get_all()
Return a list of all available services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.reload_(name)
Refreshes config files by calling service reload. Does not perform a full
restart.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.restart(name)
Restart the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name> [service signature]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.service.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.shadow
.sp
Manage the shadow file
.INDENT 0.0
.TP
.B salt.modules.shadow.default_hash()
Returns the default hash used for unset passwords
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.default_hash
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.del_password(name)
Delete the password from name user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.del_password username
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.gen_password(password, crypt_salt=None, algorithm=\(aqsha512\(aq)
Generate hashed password
.INDENT 7.0
.TP
.B password
Plaintext password to be hashed.
.TP
.B crypt_salt
Crpytographic salt. If not given, a random 8\-character salt will be
generated.
.TP
.B algorithm
The following hash algorithms are supported:
.INDENT 7.0
.IP \(bu 2
md5
.IP \(bu 2
blowfish (not in mainline glibc, only available in distros that add it)
.IP \(bu 2
sha256
.IP \(bu 2
sha512 (default)
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq
salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq crypt_salt\(aqI_am_salt\(aq algorithm=sha256
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.info(name)
Return information for the specified user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.set_date(name, date)
Sets the value for the date the password was last changed to days since the
epoch (January 1, 1970). See man chage.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_date username 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.set_expire(name, expire)
Changed in version 2014.7.0.
.sp
Sets the value for the date the account expires as days since the epoch
(January 1, 1970). Using a value of \-1 will clear expiration. See man
chage.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_expire username \-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.set_inactdays(name, inactdays)
Set the number of days of inactivity after a password has expired before
the account is locked. See man chage.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_inactdays username 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.set_maxdays(name, maxdays)
Set the maximum number of days during which a password is valid.
See man chage.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_maxdays username 90
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.set_mindays(name, mindays)
Set the minimum number of days between password changes. See man chage.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_mindays username 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.set_password(name, password, use_usermod=False)
Set the password for a named user. The password must be a properly defined
hash. The password hash can be generated with this command:
.sp
\fBpython \-c "import crypt; print crypt.crypt(\(aqpassword\(aq,
\(aq\e$6\e$SALTsalt\(aq)"\fP
.sp
\fBSALTsalt\fP is the 8\-character crpytographic salt. Valid characters in the
salt are \fB\&.\fP, \fB/\fP, and any alphanumeric character.
.sp
Keep in mind that the $6 represents a sha512 hash, if your OS is using a
different hashing algorithm this needs to be changed accordingly
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_password root \(aq$1$UYCIxa628.9qXjpQCjM4a..\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.shadow.set_warndays(name, warndays)
Set the number of days of warning before a password change is required.
See man chage.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_warndays username 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.smartos_imgadm
.sp
Module for running imgadm command on SmartOS
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.avail(search=None)
Return a list of available images
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.avail [percona]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.delete(uuid=None)
Remove an installed image
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.delete e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.get(uuid=None)
Return info on an installed image
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.get e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.import_image(uuid=None)
Import an image from the repository
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.import_image e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.list_installed()
Return a list of installed images
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.list_installed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.show(uuid=None)
Show manifest of a given image
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.show e42f8c84\-bbea\-11e2\-b920\-078fab2aab1f
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.update_installed()
Gather info on unknown images (locally installed)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.update_installed()
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_imgadm.version()
Return imgadm version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq imgadm.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.smartos_vmadm
.sp
Module for managing VMs on SmartOS
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.destroy(uuid=None)
Hard power down the virtual machine, this is equivalent to pulling the power
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.destroy <uuid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.get_macs(uuid=None)
Return a list off MAC addresses from the named VM
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_macs <uuid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.init(**kwargs)
Initialize a new VM
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.init image_uuid=\(aq...\(aq alias=\(aq...\(aq [...]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.list_active_vms()
Return a list of uuids for active virtual machine on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_active_vms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.list_inactive_vms()
Return a list of uuids for inactive virtual machine on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_inactive_vms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.list_vms()
Return a list of virtual machine names on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_vms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.reboot(uuid=None)
Reboot a domain via ACPI request
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.reboot <uuid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.setmem(uuid, memory)
Change the amount of memory allocated to VM.
<memory> is to be specified in MB.
.sp
Note for KVM : this would require a restart of the VM.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.setmem <uuid> 512
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.shutdown(uuid=None)
Send a soft shutdown signal to the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.shutdown <uuid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.start(uuid=None)
Start a defined domain
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.start <uuid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.vm_info(uuid=None)
Return a dict with information about the specified VM on this CN
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_info <uuid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smartos_vmadm.vm_virt_type(uuid=None)
Return VM virtualization type : OS or KVM
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_virt_type <uuid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.smf
.sp
Service support for Solaris 10 and 11, should work with other systems
that use SMF also. (e.g. SmartOS)
.INDENT 0.0
.TP
.B salt.modules.smf.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
The Solaris and SmartOS "if" statement uses svcs to return the service name from the
package name.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available net\-snmp
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.disable(name, **kwargs)
Disable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.disabled(name)
Check to see if the named service is disabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.enable(name, **kwargs)
Enable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.enabled(name)
Check to see if the named service is enabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.get_all()
Return all installed services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.get_disabled()
Return the disabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.get_enabled()
Return the enabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.get_running()
Return the running services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_running
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.get_stopped()
Return the stopped services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_stopped
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing net\-snmp
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.reload_(name)
Reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.status(name, sig=None)
Return the status for a service, returns a bool whether the service is
running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smf.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.smtp
.sp
Module for Sending Messages via SMTP
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
smtplib python module
.UNINDENT
.TP
.B configuration
This module can be used by either passing a jid and password
directly to send_message, or by specifying the name of a configuration
profile in the minion config, minion pillar, or master config.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
my\-smtp\-login:
smtp.server: smtp.domain.com
smtp.sender: admin@domain.com
smtp.username: myuser
smtp.password: verybadpass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The resourcename refers to the resource that is using this account. It is
user\-definable, and optional. The following configurations are both valid:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
my\-smtp\-login:
smtp.server: smtp.domain.com
smtp.sender: admin@domain.com
smtp.username: myuser
smtp.password: verybadpass
another\-smtp\-login:
smtp.server: smtp.domain.com
smtp.sender: admin@domain.com
smtp.username: myuser
smtp.password: verybadpass
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.smtp.send_msg(recipient, message, subject=\(aqMessage from Salt\(aq, sender=None, server=None, use_ssl=\(aqTrue\(aq, username=None, password=None, profile=None)
Send a message to an SMTP recipient. Designed for use in states.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
smtp.send_msg \(aqadmin@example.com\(aq \(aqThis is a salt module test\(aq profile=\(aqmy\-smtp\-account\(aq
smtp.send_msg \(aqadmin@example.com\(aq \(aqThis is a salt module test\(aq username=\(aqmyuser\(aq password=\(aqverybadpass\(aq sender="admin@example.com\(aq server=\(aqsmtp.domain.com\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.softwareupdate
.sp
Support for the softwareupdate command on MacOS.
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.download(*updates)
Download a named update so that it can be installed later with
the install or upgrade function. It returns a list of all updates
that are now downloaded.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.download <update name>
salt \(aq*\(aq softwareupdate.download "<update with whitespace>"
salt \(aq*\(aq softwareupdate.download <update1> <update2> <update3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.download_all(rec=False, restart=True)
Download all available updates so that they can be installed later
with the install or upgrade function. It returns a list of updates
that are now downloaded.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.download_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.ignore(*updates)
Ignore a specific program update. When an update is ignored the \(aq\-\(aq and
version number at the end will be omitted, so "SecUpd2014\-001\-1.0" becomes
"SecUpd2014\-001". It will be removed automatically if present. An update
is successfully ignored when it no longer shows up after list_upgrades.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.ignore <update\-name>
salt \(aq*\(aq softwareupdate.ignore "<update with whitespace>"
salt \(aq*\(aq softwareupdate.ignore <update1> <update2> <update3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.install(*updates)
Install a named upgrade. Returns a dictionary containing the name
of the update and the status of its installation.
.sp
Return values:
\- \fBTrue\fP: The update was installed.
\- \fBFalse\fP: The update was not installed.
\- \fBNone\fP: There is no update available with that name.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.install <update\-name>
salt \(aq*\(aq softwareupdate.install "<update with whitespace>"
salt \(aq*\(aq softwareupdate.install <update1> <update2> <update3>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.list_downloads()
Return a list of all updates that have been downloaded locally.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.list_downloads
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.list_ignored()
List all upgrades that has been ignored. Ignored updates are shown
without the \(aq\-\(aq and version number at the end, this is how the
softwareupdate command works.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.list_ignored
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.list_upgrades(rec=False, restart=False)
List all available updates.
.INDENT 7.0
.TP
.B rec
Return only the recommended updates.
.TP
.B restart
Return only the updates that require a restart.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.reset_ignored()
Make sure the ignored updates are not ignored anymore,
returns a list of the updates that are no longer ignored.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.reset_ignored
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.schedule(*status)
Decide if automatic checking for upgrades should be on or off.
If no arguments are given it will return the current status.
Append on or off to change the status.
.sp
Return values:
\- \fBTrue\fP: Automatic checking is now on,
\- \fBFalse\fP: Automatic checking is now off,
\- \fBNone\fP: Invalid argument.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.schedule
salt \(aq*\(aq softwareupdate.schedule on|off
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.upgrade(rec=False, restart=True)
Install all available upgrades. Returns a dictionary containing the name
of the update and the status of its installation.
.sp
Return values:
\- \fBTrue\fP: The update was installed.
\- \fBFalse\fP: The update was not installed.
.INDENT 7.0
.TP
.B rec
If set to True, only install all the recommended updates.
.TP
.B restart
Set this to False if you do not want to install updates
that require a restart.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.softwareupdate.upgrade_available(update)
Check whether or not an upgrade is available with a given name.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq softwareupdate.upgrade_available <update\-name>
salt \(aq*\(aq softwareupdate.upgrade_available "<update with whitespace>"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.solaris_group
.sp
Manage groups on Solaris
.INDENT 0.0
.TP
.B salt.modules.solaris_group.add(name, gid=None, **kwargs)
Add the specified group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.add foo 3456
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_group.chgid(name, gid)
Change the gid for a named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_group.delete(name)
Remove the named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.delete foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_group.getent(refresh=False)
Return info on all groups
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_group.info(name)
Return information about a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.info foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.solaris_shadow
.sp
Manage the password database on Solaris systems
.INDENT 0.0
.TP
.B salt.modules.solaris_shadow.default_hash()
Returns the default hash used for unset passwords
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.default_hash
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_shadow.info(name)
Return information for the specified user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_shadow.set_maxdays(name, maxdays)
Set the maximum number of days during which a password is valid. See man
passwd.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_maxdays username 90
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_shadow.set_mindays(name, mindays)
Set the minimum number of days between password changes. See man passwd.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_mindays username 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_shadow.set_password(name, password)
Set the password for a named user. The password must be a properly defined
hash, the password hash can be generated with this command:
\fBopenssl passwd \-1 <plaintext password>\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_password root $1$UYCIxa628.9qXjpQCjM4a..
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_shadow.set_warndays(name, warndays)
Set the number of days of warning before a password change is required.
See man passwd.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_warndays username 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.solaris_user
.sp
Manage users with the useradd command
.INDENT 0.0
.TP
.B salt.modules.solaris_user.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True, **kwargs)
Add a user to the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chfullname(name, fullname)
Change the user\(aqs Full Name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chfullname foo "Foo Bar"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chgid(name, gid)
Change the default group of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chgroups(name, groups, append=False)
Change the groups this user belongs to, add append to append the specified
groups
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgroups foo wheel,root True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chhome(name, home, persist=False)
Change the home directory of the user, pass true for persist to copy files
to the new home dir
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhome foo /home/users/foo True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chhomephone(name, homephone)
Change the user\(aqs Home Phone
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhomephone foo "7735551234"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chroomnumber(name, roomnumber)
Change the user\(aqs Room Number
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chroomnumber foo 123
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chshell(name, shell)
Change the default shell of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chshell foo /bin/zsh
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chuid(name, uid)
Change the uid for a named user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chuid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.chworkphone(name, workphone)
Change the user\(aqs Work Phone
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chworkphone foo "7735550123"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.delete(name, remove=False, force=False)
Remove a user from the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.delete name remove=True force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.getent(refresh=False)
Return the list of all info for all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.info(name)
Return user information
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_user.list_groups(name)
Return a list of groups the named user belongs to
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_groups foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.solarispkg
.sp
Package support for Solaris
.INDENT 0.0
.TP
.B salt.modules.solarispkg.install(name=None, sources=None, saltenv=\(aqbase\(aq, **kwargs)
Install the passed package. Can install packages from the following
sources:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
* Locally (package already exists on the minion
* HTTP/HTTPS server
* FTP server
* Salt master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example, installing a data stream pkg that already exists on the
minion:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"<pkg name>": "/dir/on/minion/<pkg filename>"}]\(aq
salt \(aq*\(aq pkg.install sources=\(aq[{"SMClgcc346": "/var/spool/pkg/gcc\-3.4.6\-sol10\-sparc\-local.pkg"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example, installing a data stream pkg that exists on the salt master:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"<pkg name>": "salt://pkgs/<pkg filename>"}]\(aq
salt \(aq*\(aq pkg.install sources=\(aq[{"SMClgcc346": "salt://pkgs/gcc\-3.4.6\-sol10\-sparc\-local.pkg"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example, installing a data stream pkg that exists on a HTTP server:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"<pkg name>": "http://packages.server.com/<pkg filename>"}]\(aq
salt \(aq*\(aq pkg.install sources=\(aq[{"SMClgcc346": "http://packages.server.com/gcc\-3.4.6\-sol10\-sparc\-local.pkg"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If working with solaris zones and you want to install a package only in the
global zone you can pass \(aqcurrent_zone_only=True\(aq to salt to have the
package only installed in the global zone. (Behind the scenes this is
passing \(aq\-G\(aq to the pkgadd command.) Solaris default when installing a
package in the global zone is to install it in all zones. This overrides
that and installs the package only in the global.
.sp
CLI Example, installing a data stream package only in the global zone:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqglobal_zone\(aq pkg.install sources=\(aq[{"SMClgcc346": "/var/spool/pkg/gcc\-3.4.6\-sol10\-sparc\-local.pkg"}]\(aq current_zone_only=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default salt automatically provides an adminfile, to automate package
installation, with these options set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
email=
instance=quit
partial=nocheck
runlevel=nocheck
idepend=nocheck
rdepend=nocheck
space=nocheck
setuid=nocheck
conflict=nocheck
action=nocheck
basedir=default
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can override any of these options in two ways. First you can optionally
pass any of the options as a kwarg to the module/state to override the
default value or you can optionally pass the \(aqadmin_source\(aq option
providing your own adminfile to the minions.
.sp
Note: You can find all of the possible options to provide to the adminfile
by reading the admin man page:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
man \-s 4 admin
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example \- Overriding the \(aqinstance\(aq adminfile option when calling the
module directly:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"<pkg name>": "salt://pkgs/<pkg filename>"}]\(aq instance="overwrite"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example \- Overriding the \(aqinstance\(aq adminfile option when used in a
state:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
SMClgcc346:
pkg.installed:
\- sources:
\- SMClgcc346: salt://srv/salt/pkgs/gcc\-3.4.6\-sol10\-sparc\-local.pkg
\- instance: overwrite
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note: the ID declaration is ignored, as the package name is read from the
"sources" parameter.
.sp
CLI Example \- Providing your own adminfile when calling the module
directly:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"<pkg name>": "salt://pkgs/<pkg filename>"}]\(aq admin_source=\(aqsalt://pkgs/<adminfile filename>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example \- Providing your own adminfile when using states:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
<pkg name>:
pkg.installed:
\- sources:
\- <pkg name>: salt://pkgs/<pkg filename>
\- admin_source: salt://pkgs/<adminfile filename>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note: the ID declaration is ignored, as the package name is read from the
"sources" parameter.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solarispkg.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
NOTE: As package repositories are not presently supported for Solaris
pkgadd, this function will always return an empty string for a given
package.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solarispkg.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solarispkg.purge(name=None, pkgs=None, **kwargs)
Package purges are not supported, this function is identical to
\fBremove()\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solarispkg.remove(name=None, pkgs=None, saltenv=\(aqbase\(aq, **kwargs)
Remove packages with pkgrm
.INDENT 7.0
.TP
.B name
The name of the package to be deleted
.UNINDENT
.sp
By default salt automatically provides an adminfile, to automate package
removal, with these options set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
email=
instance=quit
partial=nocheck
runlevel=nocheck
idepend=nocheck
rdepend=nocheck
space=nocheck
setuid=nocheck
conflict=nocheck
action=nocheck
basedir=default
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can override any of these options in two ways. First you can optionally
pass any of the options as a kwarg to the module/state to override the
default value or you can optionally pass the \(aqadmin_source\(aq option
providing your own adminfile to the minions.
.sp
Note: You can find all of the possible options to provide to the adminfile
by reading the admin man page:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
man \-s 4 admin
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove SUNWgit
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solarispkg.upgrade_available(name)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solarispkg.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.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 e.g. [\(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 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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.abort_import dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.backup music
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.core_status None music
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solr.delta_import(handler, host=None, core_name=None, options=None, extra=None)
Submits an import command to the specified handler using specified options.
This command can only be run if the minion is 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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.delta_import dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solr.full_import(handler, host=None, core_name=None, options=None, extra=None)
MASTER ONLY
Submits an import command to the specified handler using specified options.
This command can only be run if the minion is 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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.full_import dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.UNINDENT
.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 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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.import_status dataimport None music False
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.is_replication_enabled music
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.lucene_version
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.match_index_versions music
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.optimize music
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.ping music
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.reload_core None music
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Return data is in the following format:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:bool, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.reload_import_config dataimport None music {\(aqclean\(aq:True}
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.replication_details music
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.set_is_polling False
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.set_replication_enabled false, None, music
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.signal restart
.ft P
.fi
.UNINDENT
.UNINDENT
.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>:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq solr.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.sqlite3
.sp
Support for SQLite3
.INDENT 0.0
.TP
.B salt.modules.sqlite3.fetch(db=None, sql=None)
Retrieve data from an sqlite3 db (returns all rows, be careful!)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sqlite3.fetch /root/test.db \(aqSELECT * FROM test;\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sqlite3.indexes(db=None)
Show all indices in the database, for people with poor spelling skills
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sqlite3.indexes /root/test.db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sqlite3.indices(db=None)
Show all indices in the database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sqlite3.indices /root/test.db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sqlite3.modify(db=None, sql=None)
Issue an SQL query to sqlite3 (with no return data), usually used
to modify the database in some way (insert, delete, create, etc)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sqlite3.modify /root/test.db \(aqCREATE TABLE test(id INT, testdata TEXT);\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sqlite3.sqlite_version()
Return version of sqlite
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sqlite3.sqlite_version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sqlite3.tables(db=None)
Show all tables in the database
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sqlite3.tables /root/test.db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sqlite3.version()
Return version of pysqlite
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sqlite3.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.ssh
.sp
Manage client ssh components
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module requires the use of MD5 hashing. Certain
security audits may not permit the use of MD5. For those cases,
this module should be disabled or removed.
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.auth_keys root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.check_key(user, key, enc, comment, options, config=\(aq.ssh/authorized_keys\(aq, cache_keys=None)
Check to see if a key needs updating, returns "update", "add" or "exists"
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.check_key <user> <key> <enc> <comment> <options>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.check_key_file(user, source, config=\(aq.ssh/authorized_keys\(aq, saltenv=\(aqbase\(aq, env=None)
Check a keyfile from a source destination against the local keys and
return the keys to change
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq root salt://ssh/keyfile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.check_known_host(user=None, hostname=None, key=None, fingerprint=None, config=None)
Check the record in known_hosts file, either by its value or by fingerprint
(it\(aqs enough to set up either key or fingerprint, you don\(aqt need to set up
both).
.sp
If provided key or fingerprint doesn\(aqt match with stored value, return
"update", if no value is found for a given host, return "add", otherwise
return "exists".
.sp
If neither key, nor fingerprint is defined, then additional validation is
not performed.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.check_known_host <user> <hostname> key=\(aqAAAA...FAaQ==\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.get_known_host(user, hostname, config=None)
Return information about known host from the configfile, if any.
If there is no such key, return None.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.get_known_host <user> <hostname>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.hash_known_hosts(user=None, config=None)
Hash all the hostnames in the known hosts file.
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.hash_known_hosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.host_keys(keydir=None)
Return the minion\(aqs host keys
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.host_keys
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.recv_known_host(hostname, enc=None, port=None, hash_hostname=False)
Retrieve information about host public key from remote server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.recv_known_host <hostname> enc=<enc> port=<port>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.rm_auth_key <user> <key>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.rm_known_host(user=None, hostname=None, config=None)
Remove all keys belonging to hostname from a known_hosts file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.rm_known_host <user> <hostname>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.set_auth_key(user, key, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, options=None, config=\(aq.ssh/authorized_keys\(aq, cache_keys=None)
Add a key to the authorized_keys file. The "key" parameter must only be the
string of text that is the encoded key. If the key begins with "ssh\-rsa"
or ends with \fI\%user@host\fP, remove those from the key before passing it to this
function.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.set_auth_key <user> \(aq<key>\(aq enc=\(aqdsa\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.set_auth_key_from_file(user, source, config=\(aq.ssh/authorized_keys\(aq, saltenv=\(aqbase\(aq, env=None)
Add a key to the authorized_keys file, using a file as the source.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.set_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.set_known_host(user=None, hostname=None, fingerprint=None, key=None, port=None, enc=None, hash_hostname=True, config=None)
Download SSH public key from remote host "hostname", optionally validate
its fingerprint against "fingerprint" variable and save the record in the
known_hosts file.
.sp
If such a record does already exists in there, do nothing.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.set_known_host <user> fingerprint=\(aqxx:xx:..:xx\(aq enc=\(aqssh\-rsa\(aq config=\(aq.ssh/known_hosts\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ssh.user_keys(user=None, pubfile=None, prvfile=None)
Return the user\(aqs ssh keys on the minion
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ssh.user_keys
salt \(aq*\(aq ssh.user_keys user=user1
salt \(aq*\(aq ssh.user_keys user=user1 pubfile=/home/user1/.ssh/id_rsa.pub prvfile=/home/user1/.ssh/id_rsa
salt \(aq*\(aq ssh.user_keys user="[\(aquser1\(aq,\(aquser2\(aq] pubfile=id_rsa.pub prvfile=id_rsa
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.state
.sp
Control the state system on the minion
.INDENT 0.0
.TP
.B salt.modules.state.clear_cache()
Clear out cached state files, forcing even cache runs to refresh the cache
on the next state execution.
.sp
Remember that the state cache is completely disabled by default, this
execution only applies if cache=True is used in states
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.clear_cache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.high(data, queue=False, **kwargs)
Execute the compound calls stored in a single set of high data
This function is mostly intended for testing the state system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.high \(aq{"vim": {"pkg": ["installed"]}}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.highstate(test=None, queue=False, **kwargs)
Retrieve the state data from the salt master for this minion and execute it
.INDENT 7.0
.TP
.B test
Notify states to execute in test\-only (dry\-run) mode.
.sp
Sets the \fBtest\fP variable in the minion \fBopts\fP for the duration of
the state run.
.TP
.B pillar
Custom Pillar data can be passed with the \fBpillar\fP kwarg. Values
passed here will override hard\-coded Pillar values.
.TP
.B queue
\fBFalse\fP
Instead of failing immediately when another state run is in progress,
queue the new state run to begin running once the other has finished.
.sp
This option starts a new thread for each queued state run so use this
option sparingly.
.TP
.B localconfig:
Instead of using running minion opts, load \fBlocalconfig\fP and merge that
with the running minion opts. This functionality is intended for using
"roots" of salt directories (with their own minion config, pillars,
file_roots) to run highstate out of.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate
salt \(aq*\(aq state.highstate whitelist=sls1_to_run,sls2_to_run
salt \(aq*\(aq state.highstate exclude=sls_to_exclude
salt \(aq*\(aq state.highstate exclude="[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]"
salt \(aq*\(aq state.highstate pillar="{foo: \(aqFoo!\(aq, bar: \(aqBar!\(aq}"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.low(data, queue=False, **kwargs)
Execute a single low data call
This function is mostly intended for testing the state system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.low \(aq{"state": "pkg", "fun": "installed", "name": "vi"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.pkg(pkg_path, pkg_sum, hash_type, test=False, **kwargs)
Execute a packaged state run, the packaged state run will exist in a
tarball available locally. This packaged state
can be generated using salt\-ssh.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.pkg /tmp/state_pkg.tgz
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.running(concurrent=False)
Return a dict of state return data if a state function is already running.
This function is used to prevent multiple state calls from being run at
the same time.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.running
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.show_highstate(queue=False, **kwargs)
Retrieve the highstate data from the salt master and display it
.sp
Custom Pillar data can be passed with the \fBpillar\fP kwarg.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.show_low_sls(mods, saltenv=\(aqbase\(aq, test=None, queue=False, env=None, **kwargs)
Display the low data from a specific sls. The default environment is
\fBbase\fP, use \fBsaltenv\fP (\fBenv\fP in Salt 0.17.x and older) to specify a
different environment.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_low_sls foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.show_lowstate(queue=False, **kwargs)
List out the low data that will be applied to this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_lowstate
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.show_sls(mods, saltenv=\(aqbase\(aq, test=None, queue=False, env=None, **kwargs)
Display the state data from a specific sls or list of sls files on the
master. The default environment is \fBbase\fP, use \fBsaltenv\fP (\fBenv\fP in
Salt 0.17.x and older) to specify a different environment.
.sp
This function does not support topfiles. For \fBtop.sls\fP please use
\fBshow_top\fP instead.
.sp
Custom Pillar data can be passed with the \fBpillar\fP kwarg.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_sls core,edit.vim dev
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.show_top(queue=False, **kwargs)
Return the top data that the minion will use for a highstate
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_top
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.single(fun, name, test=None, queue=False, **kwargs)
Execute a single state function with the named kwargs, returns False if
insufficient data is sent to the command
.sp
By default, the values of the kwargs will be parsed as YAML. So, you can
specify lists values, or lists of single entry key\-value maps, as you
would in a YAML salt file. Alternatively, JSON format of keyword values
is also supported.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.single pkg.installed name=vim
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.sls(mods, saltenv=\(aqbase\(aq, test=None, exclude=None, queue=False, env=None, **kwargs)
Execute a set list of state files from an environment.
.INDENT 7.0
.TP
.B test
Notify states to execute in test\-only (dry\-run) mode.
.sp
Sets the \fBtest\fP variable in the minion \fBopts\fP for the duration of
the state run.
.TP
.B pillar
Custom Pillar data can be passed with the \fBpillar\fP kwarg. Values
passed here will override hard\-coded Pillar values.
.TP
.B queue
\fBFalse\fP
Instead of failing immediately when another state run is in progress,
queue the new state run to begin running once the other has finished.
.sp
This option starts a new thread for each queued state run so use this
option sparingly.
.TP
.B saltenv
base
Specify a \fBfile_roots\fP environment.
.sp
Changed in version 0.17.0: Argument name changed from \fBenv\fP to \fBsaltenv\fP\&.
.TP
.B concurrent:
WARNING: This flag is potentially dangerous. It is designed
for use when multiple state runs can safely be run at the same
Do not use this flag for performance optimization.
.TP
.B localconfig:
Instead of using running minion opts, load \fBlocalconfig\fP and merge that
with the running minion opts. This functionality is intended for using
"roots" of salt directories (with their own minion config, pillars,
file_roots) to run highstate out of.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.sls core,edit.vim dev
salt \(aq*\(aq state.sls core exclude="[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]"
salt \(aq*\(aq state.sls myslsfile pillar="{foo: \(aqFoo!\(aq, bar: \(aqBar!\(aq}"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.sls_id(id_, mods, saltenv=\(aqbase\(aq, test=None, queue=False, **kwargs)
Call a single ID from the named module(s) and handle all requisites
.sp
New in version 2014.7.0.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.sls_id apache http
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.template(tem, queue=False, **kwargs)
Execute the information stored in a template file on the minion.
.sp
This function does not ask a master for a SLS file to render but
instead directly processes the file at the provided path on the minion.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.template \(aq<Path to template on the minion>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.template_str(tem, queue=False, **kwargs)
Execute the information stored in a string from an sls template
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.template_str \(aq<Template String>\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.state.top(topfn, test=None, queue=False, **kwargs)
Execute a specific top file instead of the default
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.top reverse_top.sls
salt \(aq*\(aq state.top reverse_top.sls exclude=sls_to_exclude
salt \(aq*\(aq state.top reverse_top.sls exclude="[{\(aqid\(aq: \(aqid_to_exclude\(aq}, {\(aqsls\(aq: \(aqsls_to_exclude\(aq}]"
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.all_status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.cpuinfo()
Return the CPU info for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.cpuinfo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.cpustats()
Return the CPU stats for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.cpustats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.custom()
Return a custom composite of status data and info for this minion,
based on the minion config file. An example config like might be:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
status.cpustats.custom: [ \(aqcpu\(aq, \(aqctxt\(aq, \(aqbtime\(aq, \(aqprocesses\(aq ]
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.custom
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.diskstats()
Return the disk stats for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.diskstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.diskusage(*args)
Return the disk usage for this minion
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.diskusage [paths and/or filesystem types]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.loadavg()
Return the load averages for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.loadavg
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.master(master=None, connected=True)
New in version 2014.7.0.
.sp
Fire an event if the minion gets disconnected from its master. This
function is meant to be run via a scheduled job from the minion. If
master_ip is an FQDN/Hostname, is must be resolvable to a valid IPv4
address.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.meminfo()
Return the memory info for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.meminfo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.netdev()
Return the network device stats for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.netdev
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.netstats()
Return the network stats for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.netstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.nproc()
Return the number of processing units available on this system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.nproc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.pid(sig)
Return the PID or an empty string if the process is running or not.
Pass a signature to use to find the process via ps. Note you can pass
a Python\-compatible regular expression to return all pids of
processes matching the regexp.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.pid <sig>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.procs()
Return the process data
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.procs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.uptime()
Return the uptime for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.uptime
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.version()
Return the system version for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.status.vmstats()
Return the virtual memory stats for this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.vmstats
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.w
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.supervisord
.sp
Provide the service module for system supervisord or supervisord in a
virtualenv
.INDENT 0.0
.TP
.B salt.modules.supervisord.add(name, user=None, conf_file=None, bin_env=None)
Activates any updates in config for process/group.
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.add <name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.custom(command, user=None, conf_file=None, bin_env=None)
Run any custom supervisord command
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.custom "mstop \(aq*gunicorn*\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.options(name, conf_file=None)
New in version 2014.1.0.
.sp
Read the config file and return the config options for a given process
.INDENT 7.0
.TP
.B name
Name of the configured process
.TP
.B conf_file
path to supervisord config file
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.options foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.remove(name, user=None, conf_file=None, bin_env=None)
Removes process/group from active config
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.remove <name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.reread(user=None, conf_file=None, bin_env=None)
Reload the daemon\(aqs configuration files
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.reread
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.restart(name=\(aqall\(aq, user=None, conf_file=None, bin_env=None)
Restart the named service.
Process group names should not include a trailing asterisk.
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.restart <service>
salt \(aq*\(aq supervisord.restart <group>:
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.start(name=\(aqall\(aq, user=None, conf_file=None, bin_env=None)
Start the named service.
Process group names should not include a trailing asterisk.
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.start <service>
salt \(aq*\(aq supervisord.start <group>:
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.status(name=None, user=None, conf_file=None, bin_env=None)
List programs and its state
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.status_raw(name=None, user=None, conf_file=None, bin_env=None)
Display the raw output of status
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.status_raw
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.stop(name=\(aqall\(aq, user=None, conf_file=None, bin_env=None)
Stop the named service.
Process group names should not include a trailing asterisk.
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.stop <service>
salt \(aq*\(aq supervisord.stop <group>:
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.supervisord.update(user=None, conf_file=None, bin_env=None)
Reload config and add/remove as necessary
.INDENT 7.0
.TP
.B user
user to run supervisorctl as
.TP
.B conf_file
path to supervisord config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq supervisord.update
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.svn
.sp
Subversion SCM
.INDENT 0.0
.TP
.B salt.modules.svn.add(cwd, targets, user=None, username=None, password=None, *opts)
Add files to be tracked by the Subversion working\-copy checkout
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B targets
None
files and directories to pass to the command as arguments
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.add /path/to/repo /path/to/new/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.checkout(cwd, remote, target=None, user=None, username=None, password=None, *opts)
Download a working copy of the remote Subversion repository
directory or file
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B remote
None
URL to checkout
.TP
.B target
None
The name to give the file or directory working copy
Default: svn uses the remote basename
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.checkout /path/to/repo svn://remote/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.commit(cwd, targets=None, msg=None, user=None, username=None, password=None, *opts)
Commit the current directory, files, or directories to
the remote Subversion repository
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B targets
None
files and directories to pass to the command as arguments
Default: svn uses \(aq.\(aq
.TP
.B msg
None
Message to attach to the commit log
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.commit /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.diff(cwd, targets=None, user=None, username=None, password=None, *opts)
Return the diff of the current directory, files, or directories from
the remote Subversion repository
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B targets
None
files and directories to pass to the command as arguments
Default: svn uses \(aq.\(aq
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.diff /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.export(cwd, remote, target=None, user=None, username=None, password=None, revision=\(aqHEAD\(aq, *opts)
Create an unversioned copy of a tree.
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B remote
None
URL and path to file or directory checkout
.TP
.B target
None
The name to give the file or directory working copy
Default: svn uses the remote basename
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.export /path/to/repo svn://remote/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.info(cwd, targets=None, user=None, username=None, password=None, fmt=\(aqstr\(aq)
Display the Subversion information from the checkout.
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B targets
None
files, directories, and URLs to pass to the command as arguments
svn uses \(aq.\(aq by default
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.TP
.B fmt
str
How to fmt the output from info.
(str, xml, list, dict)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.info /path/to/svn/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.remove(cwd, targets, msg=None, user=None, username=None, password=None, *opts)
Remove files and directories from the Subversion repository
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B targets
None
files, directories, and URLs to pass to the command as arguments
.TP
.B msg
None
Message to attach to the commit log
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.remove /path/to/repo /path/to/repo/remove
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.status(cwd, targets=None, user=None, username=None, password=None, *opts)
Display the status of the current directory, files, or
directories in the Subversion repository
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B targets
None
files, directories, and URLs to pass to the command as arguments
Default: svn uses \(aq.\(aq
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.status /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.switch(cwd, remote, target=None, user=None, username=None, password=None, *opts)
New in version 2014.1.0.
.sp
Switch a working copy of a remote Subversion repository
directory
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B remote
None
URL to switch
.TP
.B target
None
The name to give the file or directory working copy
Default: svn uses the remote basename
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B username
None
Connect to the Subversion server as another user
.TP
.B password
None
Connect to the Subversion server with this password
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.switch /path/to/repo svn://remote/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.svn.update(cwd, targets=None, user=None, username=None, password=None, *opts)
Update the current directory, files, or directories from
the remote Subversion repository
.INDENT 7.0
.TP
.B cwd
The path to the Subversion repository
.TP
.B targets
None
files and directories to pass to the command as arguments
Default: svn uses \(aq.\(aq
.TP
.B user
None
Run svn as a user other than what the minion runs as
.TP
.B password
None
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.TP
.B username
None
Connect to the Subversion server as another user
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq svn.update /path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.swift
.sp
Module for handling OpenStack Swift calls
Author: Anthony Stanton <\fI\%anthony.stanton@gmail.com\fP>
.sp
Inspired by the S3 and Nova modules
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
swiftclient Python module
.UNINDENT
.TP
.B configuration
This module is not usable until the user, password, tenant, and
auth URL are specified either in a pillar or in the minion\(aqs config file.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If configuration for multiple OpenStack accounts is required, they can be
set up as different configuration profiles:
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
openstack1:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq
openstack2:
keystone.user: admin
keystone.password: verybadpass
keystone.tenant: admin
keystone.auth_url: \(aqhttp://127.0.0.2:5000/v2.0/\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With this configuration in place, any of the swift functions can make use of
a configuration profile by declaring it explicitly.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq swift.get mycontainer myfile /tmp/file profile=openstack1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.swift.delete(cont, path=None, profile=None)
Delete a container, or delete an object from a container.
.sp
CLI Example to delete a container:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.delete mycontainer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to delete an object from a container:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.delete mycontainer remoteobject
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.swift.get(cont=None, path=None, local_file=None, return_bin=False, profile=None)
List the contents of a container, or return an object from a container. Set
return_bin to True in order to retrieve an object wholesale. Otherwise,
Salt will attempt to parse an XML response.
.sp
CLI Example to list containers:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.get
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to list the contents of a container:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.get mycontainer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to return the binary contents of an object:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.get mycontainer myfile.png return_bin=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to save the binary contents of an object to a local file:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.get mycontainer myfile.png local_file=/tmp/myfile.png
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.swift.head()
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.swift.put(cont, path=None, local_file=None, profile=None)
Create a new container, or upload an object to a container.
.sp
CLI Example to create a container:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.put mycontainer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example to upload an object to a container:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt myminion swift.put mycontainer remotepath local_file=/path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.sysbench
.sp
The \(aqsysbench\(aq module is used to analyze the
performance of the minions, right from the master!
It measures various system parameters such as
CPU, Memory, File I/O, Threads and Mutex.
.INDENT 0.0
.TP
.B salt.modules.sysbench.cpu()
Tests for the CPU performance of minions.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysbench.cpu
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysbench.fileio()
This tests for the file read and write operations
Various modes of operations are
.INDENT 7.0
.IP \(bu 2
sequential write
.IP \(bu 2
sequential rewrite
.IP \(bu 2
sequential read
.IP \(bu 2
random read
.IP \(bu 2
random write
.IP \(bu 2
random read and write
.UNINDENT
.sp
The test works with 32 files with each file being 1Gb in size
The test consumes a lot of time. Be patient!
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysbench.fileio
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysbench.memory()
This tests the memory for read and write operations.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysbench.memory
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysbench.mutex()
Tests the implementation of mutex
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysbench.mutex
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysbench.ping()
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysbench.threads()
This tests the performance of the processor\(aqs scheduler
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sysbench.threads
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.sysmod
.sp
The sys module provides information about the available functions on the minion
.INDENT 0.0
.TP
.B salt.modules.sysmod.argspec(module=\(aq\(aq)
Return the argument specification of functions in Salt execution
modules.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.argspec pkg.install
salt \(aq*\(aq sys.argspec sys
salt \(aq*\(aq sys.argspec
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.doc(*args)
Return the docstrings for all modules. Optionally, specify a module or a
function to narrow the selection.
.sp
The strings are aggregated into a single document on the master for easy
reading.
.sp
Multiple modules/functions can be specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
salt \(aq*\(aq sys.doc sys
salt \(aq*\(aq sys.doc sys.doc
salt \(aq*\(aq sys.doc network.traceroute user.info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_functions(*args, **kwargs)
List the functions for all modules. Optionally, specify a module or modules
from which to list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_functions
salt \(aq*\(aq sys.list_functions sys
salt \(aq*\(aq sys.list_functions sys user
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_modules()
List the modules loaded on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_modules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_returner_functions(*args, **kwargs)
New in version 2014.7.0.
.sp
List the functions for all returner modules. Optionally, specify a returner
module or modules from which to list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_returner_functions
salt \(aq*\(aq sys.list_returner_functions mysql
salt \(aq*\(aq sys.list_returner_functions mysql etcd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_returners()
New in version 2014.7.0.
.sp
List the runners loaded on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_returners
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_runner_functions(*args, **kwargs)
New in version 2014.7.0.
.sp
List the functions for all runner modules. Optionally, specify a runner
module or modules from which to list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_runner_functions
salt \(aq*\(aq sys.list_runner_functions state
salt \(aq*\(aq sys.list_runner_functions state virt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_runners()
New in version 2014.7.0.
.sp
List the runners loaded on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_runners
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_state_functions(*args, **kwargs)
New in version 2014.7.0.
.sp
List the functions for all state modules. Optionally, specify a state
module or modules from which to list.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_state_functions
salt \(aq*\(aq sys.list_state_functions file
salt \(aq*\(aq sys.list_state_functions pkg user
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.list_state_modules()
New in version 2014.7.0.
.sp
List the modules loaded on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.list_state_modules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.reload_modules()
Tell the minion to reload the execution modules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.reload_modules
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.returner_doc(*args)
New in version 2014.7.0.
.sp
Return the docstrings for all returners. Optionally, specify a returner or a
function to narrow the selection.
.sp
The strings are aggregated into a single document on the master for easy
reading.
.sp
Multiple returners/functions can be specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.returner_doc
salt \(aq*\(aq sys.returner_doc sqlite3
salt \(aq*\(aq sys.returner_doc sqlite3.get_fun
salt \(aq*\(aq sys.returner_doc sqlite3.get_fun etcd.get_fun
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.runner_doc(*args)
New in version 2014.7.0.
.sp
Return the docstrings for all runners. Optionally, specify a runner or a
function to narrow the selection.
.sp
The strings are aggregated into a single document on the master for easy
reading.
.sp
Multiple runners/functions can be specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.runner_doc
salt \(aq*\(aq sys.runner_doc cache
salt \(aq*\(aq sys.runner_doc cache.grains
salt \(aq*\(aq sys.runner_doc cache.grains mine.get
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysmod.state_doc(*args)
New in version 2014.7.0.
.sp
Return the docstrings for all states. Optionally, specify a state or a
function to narrow the selection.
.sp
The strings are aggregated into a single document on the master for easy
reading.
.sp
Multiple states/functions can be specified.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.state_doc
salt \(aq*\(aq sys.state_doc service
salt \(aq*\(aq sys.state_doc service.running
salt \(aq*\(aq sys.state_doc service.running ipables.append
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.system
.sp
Support for reboot, shutdown, etc
.INDENT 0.0
.TP
.B salt.modules.system.halt()
Halt a running system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.halt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.system.init(runlevel)
Change the system runlevel on sysV compatible systems
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.init 3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.system.poweroff()
Poweroff a running system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.poweroff
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.system.reboot()
Reboot the system using the \(aqreboot\(aq command
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.reboot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.system.shutdown(at_time=None)
Shutdown a running system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.shutdown
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.systemd
.sp
Provide the service module for systemd
.INDENT 0.0
.TP
.B salt.modules.systemd.available(name)
Check that the given service is available taking into account
template units.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.disable(name, **kwargs)
Disable the named service to not start when the system boots
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.disabled(name)
Return if the named service is disabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.enable(name, **kwargs)
Enable the named service to start when the system boots
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.enabled(name)
Return if the named service is enabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.execs()
Return a list of all files specified as \fBExecStart\fP for all services.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq service.execs
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.force_reload(name)
Force\-reload the specified service with systemd
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.force_reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.get_all()
Return a list of all available services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.get_disabled()
Return a list of all disabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.get_enabled()
Return a list of all enabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.reload_(name)
Reload the specified service with systemd
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.restart(name)
Restart the specified service with systemd
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.show(name)
Show properties of one or more units/jobs or the manager
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq service.show <service name>
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.start(name)
Start the specified service with systemd
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.status(name, sig=None)
Return the status for a service via systemd, returns a bool
whether the service is running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.stop(name)
Stop the specified service with systemd
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.systemd.systemctl_reload()
Reloads systemctl, an action needed whenever unit files are updated.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.systemctl_reload
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.test
.sp
Module for running arbitrary tests
.INDENT 0.0
.TP
.B salt.modules.test.arg(*args, **kwargs)
Print out the data passed into the function \fB*args\fP and \fB\(gakwargs\fP, this
is used to both test the publication data and cli argument passing, but
also to display the information available within the publication data.
Returns {"args": args, "kwargs": kwargs}.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.arg 1 "two" 3.1 txt="hello" wow=\(aq{a: 1, b: "hello"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.arg_repr(*args, **kwargs)
Print out the data passed into the function \fB*args\fP and \fB\(gakwargs\fP, this
is used to both test the publication data and cli argument passing, but
also to display the information available within the publication data.
Returns {"args": repr(args), "kwargs": repr(kwargs)}.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.arg_repr 1 "two" 3.1 txt="hello" wow=\(aq{a: 1, b: "hello"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.arg_type(*args, **kwargs)
Print out the types of the args and kwargs. This is used to test the types
of the args and kwargs passed down to the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.arg_type 1 \(aqint\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.collatz 3
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.conf_test
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.cross_test(func, args=None)
Execute a minion function via the __salt__ object in the test
module, used to verify that the minion functions can be called
via the __salt__ module.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.cross_test file.gid_to_group 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.echo(text)
Return a string \- used for testing the connection
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.echo \(aqfoo bar baz quo qux\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.exception(message=\(aqTest Exception\(aq)
Raise an exception
.sp
Optionally provide an error message or output the full stack.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.exception \(aqOh noes!\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.fib(num)
Return a Fibonacci sequence up to the passed number, and the
timeit took to compute in seconds. Used for performance tests
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.fib 3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.get_opts()
Return the configuration options passed to this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.get_opts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.kwarg(**kwargs)
Print out the data passed into the function \fB**kwargs\fP, this is used to
both test the publication data and cli kwarg passing, but also to display
the information available within the publication data.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.kwarg num=1 txt="two" env=\(aq{a: 1, b: "hello"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.not_loaded()
List the modules that were not loaded by the salt loader system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.not_loaded
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.opts_pkg()
Return an opts package with the grains and opts for this minion.
This is primarily used to create the options used for master side
state compiling routines
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.opts_pkg
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.outputter(data)
Test the outputter, pass in data to return
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.outputter foobar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.ping()
Used to make sure the minion is up and responding. Not an ICMP ping.
.sp
Returns \fBTrue\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.provider(module)
Pass in a function name to discover what provider is being used
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.provider service
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.providers()
Return a dict of the provider names and the files that provided them
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.providers
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.rand_sleep(max=60)
Sleep for a random number of seconds, used to test long\-running commands
and minions returning at differing intervals
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.rand_sleep 60
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.rand_str(size=9999999999)
Return a random string
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.rand_str
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.retcode(code=42)
Test that the returncode system is functioning correctly
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.retcode 42
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.sleep(length)
Instruct the minion to initiate a process that will sleep for a given
period of time.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.sleep 20
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.stack()
Return the current stack trace
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.stack
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.tty(*args, **kwargs)
Deprecated! Moved to cmdmod.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.tty tty0 \(aqThis is a test\(aq
salt \(aq*\(aq test.tty pts3 \(aqThis is a test\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.version()
Return the version of salt on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.versions_information()
Returns versions of components used by salt as a dict
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.versions_information
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.test.versions_report()
Returns versions of components used by salt
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.versions_report
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.timezone
.sp
Module for managing timezone on POSIX\-like systems.
.INDENT 0.0
.TP
.B salt.modules.timezone.get_hwclock()
Get current hardware clock setting (UTC or localtime)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_hwclock
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.timezone.get_offset()
Get current numeric timezone offset from UCT (i.e. \-0700)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_offset
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.timezone.get_zone()
Get current timezone (i.e. America/Denver)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_zone
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.timezone.get_zonecode()
Get current timezone (i.e. PST, MDT, etc)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_zonecode
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.timezone.set_hwclock(clock)
Sets the hardware clock to be either UTC or localtime
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.set_hwclock UTC
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.timezone.set_zone(timezone)
Unlinks, then symlinks /etc/localtime to the set timezone.
.sp
The timezone is crucial to several system processes, each of which SHOULD
be restarted (for instance, whatever you system uses as its cron and
syslog daemons). This will not be magically done for you!
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.set_zone \(aqAmerica/Denver\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.timezone.zone_compare(timezone)
Checks the hash sum between the given timezone, and the one set in
/etc/localtime. Returns True if they match, and False if not. Mostly useful
for running state checks.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.zone_compare \(aqAmerica/Denver\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.tls
.sp
A salt module for SSL/TLS.
Can create a Certificate Authority (CA)
or use Self\-Signed certificates.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
PyOpenSSL Python module
.UNINDENT
.TP
.B configuration
Add the following values in \fB/etc/salt/minion\fP for the CA module
to function properly:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ca.cert_base_path: \(aq/etc/pki\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.ca_exists(ca_name, cacert_path=None)
Verify whether a Certificate Authority (CA) already exists
.INDENT 7.0
.TP
.B ca_name
name of the CA
.TP
.B cacert_path
absolute path to ca certificates root directory
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.ca_exists test_ca /etc/certs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.cert_base_path(cacert_path=None)
Return the base path for certs from CLI or from options
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.cert_base_path
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.create_ca(ca_name, bits=2048, days=365, CN=\(aqlocalhost\(aq, C=\(aqUS\(aq, ST=\(aqUtah\(aq, L=\(aqSalt Lake City\(aq, O=\(aqSaltStack\(aq, OU=None, emailAddress=\(aqxyz@pdq.net\(aq, fixmode=False, cacert_path=None, digest=\(aqsha256\(aq)
Create a Certificate Authority (CA)
.INDENT 7.0
.TP
.B ca_name
name of the CA
.TP
.B bits
number of RSA key bits, Default is \fB2048\fP
.TP
.B days
number of days the CA will be valid, Default is \fB365\fP
.TP
.B CN
common name in the request, Default is \fBlocalhost\fP
.TP
.B C
country, Default is \fBUS\fP
.TP
.B ST
state, Default is \fBUtah\fP
.TP
.B L
locality, Default is \fBSalt Lake City\fP
.TP
.B O
organization, Default is \fBSaltStack\fP
.TP
.B OU
organizational unit, Default is \fBNone\fP
.TP
.B emailAddress
email address for the CA owner, Default is \fBxyz@pdq.net\fP
.TP
.B cacert_path
absolute path to ca certificates root directory
.TP
.B digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: \(aqsha256\(aq
.UNINDENT
.sp
Writes out a CA certificate based upon defined config values. If the file
already exists, the function just returns assuming the CA certificate
already exists.
.sp
If the following values were set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ca.cert_base_path=\(aq/etc/pki\(aq
ca_name=\(aqkoji\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the resulting CA, and corresponding key, would be written in the following location:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/pki/koji/koji_ca_cert.crt
/etc/pki/koji/koji_ca_cert.key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.create_ca test_ca
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.create_ca_signed_cert(ca_name, CN, days=365, cacert_path=None, digest=\(aqsha256\(aq, **extensions)
Create a Certificate (CERT) signed by a named Certificate Authority (CA)
.sp
If the certificate file already exists, the function just returns assuming
the CERT already exists.
.sp
The CN \fImust\fP match an existing CSR generated by create_csr. If it
does not, this method does nothing.
.INDENT 7.0
.TP
.B ca_name
name of the CA
.TP
.B CN
common name matching the certificate signing request
.TP
.B days
number of days certificate is valid, Default is \fB365\fP (1 year)
.TP
.B cacert_path
absolute path to ca certificates root directory
.TP
.B digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: \(aqsha256\(aq
.TP
.B
.nf
**
.fi
extensions
X509 V3 certificate extension
.UNINDENT
.sp
Writes out a Certificate (CERT). If the file already
exists, the function just returns assuming the CERT already exists.
.sp
The CN \fImust\fP match an existing CSR generated by create_csr. If it
does not, this method does nothing.
.sp
If the following values were set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ca.cert_base_path=\(aq/etc/pki\(aq
ca_name=\(aqkoji\(aq
CN=\(aqtest.egavas.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the resulting signed certificate would be written in the
following location:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/pki/koji/certs/test.egavas.org.crt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.create_ca_signed_cert test localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.create_csr(ca_name, bits=2048, CN=\(aqlocalhost\(aq, C=\(aqUS\(aq, ST=\(aqUtah\(aq, L=\(aqSalt Lake City\(aq, O=\(aqSaltStack\(aq, OU=None, emailAddress=\(aqxyz@pdq.net\(aq, subjectAltName=None, cacert_path=None, digest=\(aqsha256\(aq)
Create a Certificate Signing Request (CSR) for a
particular Certificate Authority (CA)
.INDENT 7.0
.TP
.B ca_name
name of the CA
.TP
.B bits
number of RSA key bits, Default is \fB2048\fP
.TP
.B CN
common name in the request, Default is \fBlocalhost\fP
.TP
.B C
country, Default is \fBUS\fP
.TP
.B ST
state, Default is \fBUtah\fP
.TP
.B L
locality, Default is \fBSalt Lake City\fP
.TP
.B O
organization. Must the same as CA certificate or an error will be raised, Default is \fBSaltStack\fP
.TP
.B OU
organizational unit, Default is \fBNone\fP
.TP
.B emailAddress
email address for the request, Default is \fBxyz@pdq.net\fP
.TP
.B subjectAltName
valid subjectAltNames in full form, e.g. to add DNS entry you would call
this function with this value: \fB[\(aqDNS:myapp.foo.comm\(aq]\fP
.TP
.B cacert_path
absolute path to ca certificates root directory
.TP
.B digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: \(aqsha256\(aq
.UNINDENT
.sp
Writes out a Certificate Signing Request (CSR) If the file already
exists, the function just returns assuming the CSR already exists.
.sp
If the following values were set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ca.cert_base_path=\(aq/etc/pki\(aq
ca_name=\(aqkoji\(aq
CN=\(aqtest.egavas.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the resulting CSR, and corresponding key, would be written in the
following location:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/pki/koji/certs/test.egavas.org.csr
/etc/pki/koji/certs/test.egavas.org.key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.create_csr test
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.create_pkcs12(ca_name, CN, passphrase=\(aq\(aq, cacert_path=None)
Create a PKCS#12 browser certificate for a particular Certificate (CN)
.INDENT 7.0
.TP
.B ca_name
name of the CA
.TP
.B CN
common name matching the certificate signing request
.TP
.B passphrase
used to unlock the PKCS#12 certificate when loaded into the browser
.TP
.B cacert_path
absolute path to ca certificates root directory
.UNINDENT
.sp
If the following values were set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ca.cert_base_path=\(aq/etc/pki\(aq
ca_name=\(aqkoji\(aq
CN=\(aqtest.egavas.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the resulting signed certificate would be written in the
following location:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/pki/koji/certs/test.egavas.org.p12
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.create_pkcs12 test localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.create_self_signed_cert(tls_dir=\(aqtls\(aq, bits=2048, days=365, CN=\(aqlocalhost\(aq, C=\(aqUS\(aq, ST=\(aqUtah\(aq, L=\(aqSalt Lake City\(aq, O=\(aqSaltStack\(aq, OU=None, emailAddress=\(aqxyz@pdq.net\(aq, cacert_path=None, digest=\(aqsha256\(aq)
Create a Self\-Signed Certificate (CERT)
.INDENT 7.0
.TP
.B tls_dir
location appended to the ca.cert_base_path, Default is \fBtls\fP
.TP
.B bits
number of RSA key bits, Default is \fB2048\fP
.TP
.B days
validity of certificate, Default is \fB365\fP
.TP
.B CN
common name in the request, Default is \fBlocalhost\fP
.TP
.B C
country, Default is \fBUS\fP
.TP
.B ST
state, Default is \fBUtah\fP
.TP
.B L
locality, Default is \fBSalt Lake City\fP
.TP
.B O
organization. Must the same as CA certificate or an error will be raised, Default is \fBSaltStack\fP
.TP
.B OU
organizational unit, Default is \fBNone\fP
.TP
.B emailAddress
email address for the request, Default is \fBxyz@pdq.net\fP
.TP
.B cacert_path
absolute path to ca certificates root directory
.TP
.B digest
The message digest algorithm. Must be a string describing a digest
algorithm supported by OpenSSL (by EVP_get_digestbyname, specifically).
For example, "md5" or "sha1". Default: \(aqsha256\(aq
.UNINDENT
.sp
Writes out a Self\-Signed Certificate (CERT). If the file already
exists, the function just returns.
.sp
If the following values were set:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ca.cert_base_path=\(aq/etc/pki\(aq
tls_dir=\(aqkoji\(aq
CN=\(aqtest.egavas.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the resulting CERT, and corresponding key, would be written in the
following location:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/pki/koji/certs/test.egavas.org.crt
/etc/pki/koji/certs/test.egavas.org.key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.create_self_signed_cert
salt \(aqminion\(aq tls.create_self_signed_cert CN=\(aqtest.mysite.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.get_ca(ca_name, as_text=False, cacert_path=None)
Get the certificate path or content
.INDENT 7.0
.TP
.B ca_name
name of the CA
.TP
.B as_text
if true, return the certificate content instead of the path
.TP
.B cacert_path
absolute path to ca certificates root directory
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.get_ca test_ca as_text=False cacert_path=/etc/certs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.maybe_fix_ssl_version(ca_name, cacert_path=None)
Check that the X509 version is correct
(was incorrectly set in previous salt versions).
This will fix the version if needed.
.INDENT 7.0
.TP
.B ca_name
ca authority name
.TP
.B cacert_path
absolute path to ca certificates root directory
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.maybe_fix_ssl_version test_ca /etc/certs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tls.set_ca_path(cacert_path)
If wanted, store the aforementioned cacert_path in context
to be used as the basepath for further operations
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tls.set_ca_path /etc/certs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.tomcat
.sp
Support for Tomcat
.sp
This module uses the manager webapp to manage Apache tomcat webapps.
If the manager webapp is not configured some of the functions won\(aqt work.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The config format was changed in 2014.7.0, but backwards compatibility for
the old\-style config will be in the 2014.7.1 release.
.UNINDENT
.UNINDENT
.sp
The following grains/pillar should be set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tomcat\-manager:
user: <username>
passwd: <password>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or the old format:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tomcat\-manager.user: <username>
tomcat\-manager.passwd: <password>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Also configure a user in the conf/tomcat\-users.xml file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<?xml version=\(aq1.0\(aq encoding=\(aqutf\-8\(aq?>
<tomcat\-users>
<role rolename="manager\-script"/>
<user username="tomcat" password="tomcat" roles="manager\-script"/>
</tomcat\-users>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
More information about tomcat manager:
\fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html\fP
.IP \(bu 2
if you use only this module for deployments you\(aqve might want to strict
access to the manager only from localhost for more info:
\fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html#Configuring_Manager_Application_Access\fP
.IP \(bu 2
Tested on:
.INDENT 2.0
.TP
.B JVM Vendor:
Sun Microsystems Inc.
.TP
.B JVM Version:
1.6.0_43\-b01
.TP
.B OS Architecture:
amd64
.TP
.B OS Name:
Linux
.TP
.B OS Version:
2.6.32\-358.el6.x86_64
.TP
.B Tomcat Version:
Apache Tomcat/7.0.37
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.deploy_war(war, context, force=\(aqno\(aq, url=\(aqhttp://localhost:8080/manager\(aq, saltenv=\(aqbase\(aq, timeout=180, env=None, temp_war_location=None)
Deploy a WAR file
.INDENT 7.0
.TP
.B war
absolute path to WAR file (should be accessible by the user running
tomcat) or a path supported by the salt.modules.cp.get_file function
.TP
.B context
the context path to deploy
.TP
.B force
False
set True to deploy the webapp even one is deployed in the context
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B saltenv
base
the environment for WAR file in used by salt.modules.cp.get_url
function
.TP
.B timeout
180
timeout for HTTP request
.TP
.B temp_war_location
None
use another location to temporarily copy to war file
by default the system\(aqs temp directory is used
.UNINDENT
.sp
CLI Examples:
.sp
cp module
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.deploy_war salt://application.war /api
salt \(aq*\(aq tomcat.deploy_war salt://application.war /api no
salt \(aq*\(aq tomcat.deploy_war salt://application.war /api yes http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
minion local file system
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.deploy_war /tmp/application.war /api
salt \(aq*\(aq tomcat.deploy_war /tmp/application.war /api no
salt \(aq*\(aq tomcat.deploy_war /tmp/application.war /api yes http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.fullversion()
Return all server information from catalina.sh version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.fullversion
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.leaks(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Find memory leaks in tomcat
.INDENT 7.0
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.leaks
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.ls(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
list all the deployed webapps
.INDENT 7.0
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.ls
salt \(aq*\(aq tomcat.ls http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.passwd(passwd, user=\(aq\(aq, alg=\(aqmd5\(aq, realm=None)
This function replaces the $CATALINA_HOME/bin/digest.sh script
convert a clear\-text password to the $CATALINA_BASE/conf/tomcat\-users.xml
format
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.passwd secret
salt \(aq*\(aq tomcat.passwd secret tomcat sha1
salt \(aq*\(aq tomcat.passwd secret tomcat sha1 \(aqProtected Realm\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.reload_(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Reload the webapp
.INDENT 7.0
.TP
.B app
the webapp context path
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.reload /jenkins
salt \(aq*\(aq tomcat.reload /jenkins http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.serverinfo(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
return details about the server
.INDENT 7.0
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.serverinfo
salt \(aq*\(aq tomcat.serverinfo http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.sessions(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
return the status of the webapp sessions
.INDENT 7.0
.TP
.B app
the webapp context path
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.sessions /jenkins
salt \(aq*\(aq tomcat.sessions /jenkins http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.signal(signal=None)
Signals catalina to start, stop, securestart, forcestop.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.signal start
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.start(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Start the webapp
.INDENT 7.0
.TP
.B app
the webapp context path
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.start /jenkins
salt \(aq*\(aq tomcat.start /jenkins http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.status(url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Used to test if the tomcat manager is up
.INDENT 7.0
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.status
salt \(aq*\(aq tomcat.status http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.status_webapp(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
return the status of the webapp (stopped | running | missing)
.INDENT 7.0
.TP
.B app
the webapp context path
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.status_webapp /jenkins
salt \(aq*\(aq tomcat.status_webapp /jenkins http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.stop(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Stop the webapp
.INDENT 7.0
.TP
.B app
the webapp context path
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.stop /jenkins
salt \(aq*\(aq tomcat.stop /jenkins http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.undeploy(app, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Undeploy a webapp
.INDENT 7.0
.TP
.B app
the webapp context path
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.undeploy /jenkins
salt \(aq*\(aq tomcat.undeploy /jenkins http://localhost:8080/manager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.tomcat.version()
Return server version from catalina.sh version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq tomcat.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.twilio_notify
.sp
Module for notifications via Twilio
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
twilio python module
.UNINDENT
.TP
.B configuration
Configure this module by specifying the name of a configuration
profile in the minion config, minion pillar, or master config.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
my\-twilio\-account:
twilio.account_sid: AC32a3c83990934481addd5ce1659f04d2
twilio.auth_token: mytoken
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.twilio_notify.send_sms(profile, body, to, from_)
Send an sms
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
twilio.send_sms twilio\-account \(aqTest sms\(aq \(aq+18019999999\(aq \(aq+18011111111\(aq
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.upstart
.sp
Module for the management of upstart systems. The Upstart system only supports
service starting, stopping and restarting.
.sp
Currently (as of Ubuntu 12.04) there is no tool available to disable
Upstart services (like update\-rc.d). This[1] is the recommended way to
disable an Upstart service. So we assume that all Upstart services
that have not been disabled in this manner are enabled.
.sp
But this is broken because we do not check to see that the dependent
services are enabled. Otherwise we would have to do something like
parse the output of "initctl show\-config" to determine if all service
dependencies are enabled to start on boot. For example, see the "start
on" condition for the lightdm service below[2]. And this would be too
hard. So we wait until the upstart developers have solved this
problem. :) This is to say that an Upstart service that is enabled may
not really be enabled.
.sp
Also, when an Upstart service is enabled, should the dependent
services be enabled too? Probably not. But there should be a notice
about this, at least.
.sp
[1] \fI\%http://upstart.ubuntu.com/cookbook/#disabling\-a\-job\-from\-automatically\-starting\fP
.sp
[2] example upstart configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
lightdm
emits login\-session\-start
emits desktop\-session\-start
emits desktop\-shutdown
start on ((((filesystem and runlevel [!06]) and started dbus) and (drm\-device\-added card0 PRIMARY_DEVICE_FOR_DISPLAY=1 or stopped udev\-fallback\-graphics)) or runlevel PREVLEVEL=S)
stop on runlevel [016]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This module should not be used on Red Hat systems. For these,
the \fBrh_service\fP module should be
used, as it supports the hybrid upstart/sysvinit system used in
RHEL/CentOS 6.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.disable(name, **kwargs)
Disable the named service from starting on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.disabled(name)
Check to see if the named service is disabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.enable(name, **kwargs)
Enable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.enabled(name)
Check to see if the named service is enabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.force_reload(name)
Force\-reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.force_reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.full_restart(name)
Do a full restart (stop/start) of the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.full_restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.get_all()
Return all installed services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.get_disabled()
Return the disabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.get_enabled()
Return the enabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing sshd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.reload_(name)
Reload the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.reload <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.status(name, sig=None)
Return the status for a service, returns a bool whether the service is
running.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.upstart.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.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=None, shell=None, unique=True, system=False, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True)
Add a user to the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chfullname(name, fullname)
Change the user\(aqs Full Name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chfullname foo "Foo Bar"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chgid(name, gid)
Change the default group of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgroups foo wheel,root True
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhome foo /home/users/foo True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chhomephone(name, homephone)
Change the user\(aqs Home Phone
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhomephone foo "7735551234"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chroomnumber(name, roomnumber)
Change the user\(aqs Room Number
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chroomnumber foo 123
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chshell(name, shell)
Change the default shell of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chshell foo /bin/zsh
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chuid(name, uid)
Change the uid for a named user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chuid foo 4376
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.chworkphone(name, workphone)
Change the user\(aqs Work Phone
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chworkphone foo "7735550123"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.delete(name, remove=False, force=False)
Remove a user from the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.delete name remove=True force=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.getent(refresh=False)
Return the list of all info for all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.info(name)
Return user information
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_groups foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.useradd.list_users()
Return a list of all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_users
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.uwsgi
.sp
uWSGI stats server \fI\%http://uwsgi\-docs.readthedocs.org/en/latest/StatsServer.html\fP
.INDENT 0.0
.TP
.B maintainer
Peter Baumgartner <\fI\%pete@lincolnloop.com\fP>
.TP
.B maturity
new
.TP
.B platform
all
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.uwsgi.stats(socket)
Return the data from \fIuwsgi \-\-connect\-and\-read\fP as a dictionary.
.INDENT 7.0
.TP
.B socket
The socket the uWSGI stats server is listening on
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq uwsgi.stats /var/run/mystatsserver.sock
salt \(aq*\(aq uwsgi.stats 127.0.0.1:5050
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.varnish
.sp
Support for Varnish
.sp
New in version 2014.7.0.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
These functions are designed to work with all implementations of Varnish
from 3.x onwards
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.varnish.ban(ban_expression)
Add ban to the varnish cache
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq varnish.ban ban_expression
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.varnish.ban_list()
List varnish cache current bans
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq varnish.ban_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.varnish.param_set(param, value)
Set a param in varnish cache
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq varnish.param_set param value
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.varnish.param_show(param=None)
Show params of varnish cache
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq varnish.param_show param
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.varnish.purge()
Purge the varnish cache
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq varnish.purge
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.varnish.version()
Return server version from varnishd \-V
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq varnish.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.virt
.sp
Work with virtual machines managed by libvirt
.INDENT 0.0
.TP
.B depends
libvirt Python module
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.create(vm_)
Start a defined domain
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.create <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.create_xml_path(path)
Start a domain based on the XML\-file path passed to the function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.create_xml_path <path to XML file on the node>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.create_xml_str <XML in string format>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.ctrl_alt_del(vm_)
Sends CTRL+ALT+DEL to a VM
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.ctrl_alt_del <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.define_vol_xml_path(path)
Define a volume based on the XML\-file path passed to the function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.define_vol_xml_path <path to XML file on the node>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.define_vol_xml_str(xml)
Define a volume based on the XML passed to the function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.define_vol_xml_str <XML in string format>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.define_xml_path(path)
Define a domain based on the XML\-file path passed to the function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.define_xml_path <path to XML file on the node>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.define_xml_str(xml)
Define a domain based on the XML passed to the function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.define_xml_str <XML in string format>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.destroy <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.freecpu
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.freemem
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.full_info()
Return the node_info, vm_info and freemem
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.full_info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_disks(vm_)
Return the disks of a named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_disks <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_graphics(vm_)
Returns the information on vnc for a given vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_graphics <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_macs(vm_)
Return a list off MAC addresses from the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_macs <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_nics(vm_)
Return info about the network interfaces of a named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_nics <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_profiles(hypervisor=None)
Return the virt profiles for hypervisor.
.sp
Currently there are profiles for:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
nic
.IP \(bu 2
disk
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_profiles
salt \(aq*\(aq virt.get_profiles hypervisor=esxi
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.get_xml(vm_)
Returns the XML for a given vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_xml <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.init(name, cpu, mem, image=None, nic=\(aqdefault\(aq, hypervisor=\(aqkvm\(aq, start=True, disk=\(aqdefault\(aq, saltenv=\(aqbase\(aq, **kwargs)
Initialize a new vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqhypervisor\(aq virt.init vm_name 4 512 salt://path/to/image.raw
salt \(aqhypervisor\(aq virt.init vm_name 4 512 nic=profile disk=profile
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.is_hyper()
Returns a bool whether or not this node is a hypervisor of any kind
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.is_hyper
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.is_kvm_hyper()
Returns a bool whether or not this node is a KVM hypervisor
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.is_kvm_hyper
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.is_xen_hyper()
Returns a bool whether or not this node is a XEN hypervisor
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.is_xen_hyper
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.list_active_vms()
Return a list of names for active virtual machine on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_active_vms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.list_inactive_vms()
Return a list of names for inactive virtual machine on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_inactive_vms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.list_vms()
Return a list of virtual machine names on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_vms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.migrate(vm_, target, ssh=False)
Shared storage migration
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.migrate <vm name> <target hypervisor>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.migrate_non_shared(vm_, target, ssh=False)
Attempt to execute non\-shared storage "all" migration
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.migrate_non_shared <vm name> <target hypervisor>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.migrate_non_shared_inc(vm_, target, ssh=False)
Attempt to execute non\-shared storage "all" migration
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.migrate_non_shared_inc <vm name> <target hypervisor>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.node_info()
Return a dict with information about this node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.node_info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.pause(vm_)
Pause the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.pause <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.purge <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.reboot(vm_)
Reboot a domain via ACPI request
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.reboot <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.reset(vm_)
Reset a VM by emulating the reset button on a physical machine
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.reset <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.resume(vm_)
Resume the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.resume <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.seed_non_shared_migrate <disks>
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt "*" virt.set_autostart <vm name> <on | off>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.setmem(vm_, memory, config=False)
Changes the amount of memory allocated to VM. The VM must be shutdown
for this to work.
.sp
memory is to be specified in MB
If config is True then we ask libvirt to modify the config as well
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.setmem myvm 768
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.setvcpus(vm_, vcpus, config=False)
Changes the amount of vcpus allocated to VM. The VM must be shutdown
for this to work.
.sp
vcpus is an int representing the number to be assigned
If config is True then we ask libvirt to modify the config as well
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.setvcpus myvm 2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.shutdown(vm_)
Send a soft shutdown signal to the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.shutdown <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.start(vm_)
Alias for the obscurely named \(aqcreate\(aq function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.start <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.stop(vm_)
Alias for the obscurely named \(aqdestroy\(aq function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.stop <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.undefine <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.virt_type()
Returns the virtual machine type as a string
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.virt_type
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.vm_cputime(vm_=None)
Return cputime used by the vms on this hyper in a
list of dicts:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
\(aqyour\-vm\(aq: {
\(aqcputime\(aq <int>
\(aqcputime_percent\(aq <int>
},
...
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_cputime
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.vm_diskstats(vm_=None)
Return disk usage counters used by the vms on this hyper in a
list of dicts:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
\(aqyour\-vm\(aq: {
\(aqrd_req\(aq : 0,
\(aqrd_bytes\(aq : 0,
\(aqwr_req\(aq : 0,
\(aqwr_bytes\(aq : 0,
\(aqerrs\(aq : 0
},
...
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_blockstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.vm_info(vm_=None)
Return detailed information about the vms on this hyper in a
list of dicts:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
\(aqyour\-vm\(aq: {
\(aqcpu\(aq: <int>,
\(aqmaxMem\(aq: <int>,
\(aqmem\(aq: <int>,
\(aqstate\(aq: \(aq<state>\(aq,
\(aqcputime\(aq <int>
},
...
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.vm_netstats(vm_=None)
Return combined network counters used by the vms on this hyper in a
list of dicts:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
\(aqyour\-vm\(aq: {
\(aqrx_bytes\(aq : 0,
\(aqrx_packets\(aq : 0,
\(aqrx_errs\(aq : 0,
\(aqrx_drop\(aq : 0,
\(aqtx_bytes\(aq : 0,
\(aqtx_packets\(aq : 0,
\(aqtx_errs\(aq : 0,
\(aqtx_drop\(aq : 0
},
...
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_netstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virt.vm_state(vm_=None)
Return list of all the vms and their state.
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_state <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.virtualenv
.sp
Create virtualenv environments
.INDENT 0.0
.TP
.B salt.modules.virtualenv_mod.create(path, venv_bin=None, system_site_packages=False, distribute=False, clear=False, python=None, extra_search_dir=None, never_download=None, prompt=None, pip=False, symlinks=None, upgrade=None, user=None, runas=None, saltenv=\(aqbase\(aq)
Create a virtualenv
.INDENT 7.0
.TP
.B path
The path to create the virtualenv
.TP
.B venv_bin
None (default \(aqvirtualenv\(aq)
The name (and optionally path) of the virtualenv command. This can also
be set globally in the minion config file as \fBvirtualenv.venv_bin\fP\&.
.TP
.B system_site_packages
False
Passthrough argument given to virtualenv or pyvenv
.TP
.B distribute
False
Passthrough argument given to virtualenv
.TP
.B pip
False
Install pip after creating a virtual environment,
implies distribute=True
.TP
.B clear
False
Passthrough argument given to virtualenv or pyvenv
.TP
.B python
None (default)
Passthrough argument given to virtualenv
.TP
.B extra_search_dir
None (default)
Passthrough argument given to virtualenv
.TP
.B never_download
None (default)
Passthrough argument given to virtualenv if True
.TP
.B prompt
None (default)
Passthrough argument given to virtualenv if not None
.TP
.B symlinks
None
Passthrough argument given to pyvenv if True
.TP
.B upgrade
None
Passthrough argument given to pyvenv if True
.TP
.B user
None
Set ownership for the virtualenv
.TP
.B runas
None
Set ownership for the virtualenv
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fBrunas\fP argument is deprecated as of 2014.1.0. \fBuser\fP should be
used instead.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virtualenv.create /path/to/new/virtualenv
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.virtualenv_mod.get_site_packages(venv)
Returns the path to the site\-packages directory inside a virtualenv
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virtualenv.get_site_packages /path/to/my/venv
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_autoruns
.sp
Module for listing programs that automatically run on startup
(very alpha...not tested on anything but my Win 7x64)
.INDENT 0.0
.TP
.B salt.modules.win_autoruns.list_()
Get a list of automatically running programs
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq autoruns.list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_disk
.sp
Module for gathering disk information on Windows
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
win32api Python module
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_disk.usage()
Return usage information for volumes mounted on this minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq disk.usage
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_dns_client
.sp
Module for configuring DNS Client on Windows systems
.INDENT 0.0
.TP
.B salt.modules.win_dns_client.add_dns(ip, interface=\(aqLocal Area Connection\(aq, index=1)
Add the DNS server to the network interface
(index starts from 1)
.sp
Note: if the interface DNS is configured by DHCP, all the DNS servers will
be removed from the interface and the requested DNS will be the only one
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_dns_client.add_dns <ip> <interface> <index>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_dns_client.dns_dhcp(interface=\(aqLocal Area Connection\(aq)
Configure the interface to get its DNS servers from the DHCP server
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_dns_client.dns_dhcp <interface>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_dns_client.get_dns_config(interface=\(aqLocal Area Connection\(aq)
Get the type of DNS configuration (dhcp / static)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_dns_client.get_dns_config \(aqLocal Area Connection\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_dns_client.get_dns_servers(interface=\(aqLocal Area Connection\(aq)
Return a list of the configured DNS servers of the specified interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_dns_client.get_dns_servers \(aqLocal Area Connection\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_dns_client.rm_dns(ip, interface=\(aqLocal Area Connection\(aq)
Remove the DNS server from the network interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_dns_client.rm_dns <ip> <interface>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_file
.sp
Manage information about files on the minion, set/read user, group
data
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
win32api
.IP \(bu 2
win32file
.IP \(bu 2
win32security
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.chgrp(path, group)
Change the group of a file
.sp
Under Windows, this will do nothing.
.sp
While a file in Windows does have a \(aqprimary group\(aq, this rarely used
attribute generally has no bearing on permissions unless intentionally
configured and is only used to support Unix compatibility features (e.g.
Services For Unix, NFS services).
.sp
Salt, therefore, remaps this function to do nothing while still being
compatible with Unix behavior. When managing Windows systems,
this function is superfluous and will generate an info level log entry if
used directly.
.sp
If you do actually want to set the \(aqprimary group\(aq of a file, use \fIfile
.chpgrp\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.chpgrp c:\etemp\etest.txt administrators
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.chown(path, user, group=None, pgroup=None, follow_symlinks=True)
Chown a file, pass the file the desired user and group
.sp
Under Windows, the group parameter will be ignored.
.sp
This is because while files in Windows do have a \(aqprimary group\(aq
property, this is rarely used. It generally has no bearing on
permissions unless intentionally configured and is most commonly used to
provide Unix compatibility (e.g. Services For Unix, NFS services).
.sp
If you do want to change the \(aqprimary group\(aq property and understand the
implications, pass the Windows only parameter, pgroup, instead.
.sp
To set the primary group to \(aqNone\(aq, it must be specified in quotes.
Otherwise Salt will interpret it as the Python value of None and no primary
group changes will occur. See the example below.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.chown c:\etemp\etest.txt myusername
salt \(aq*\(aq file.chown c:\etemp\etest.txt myusername pgroup=Administrators
salt \(aq*\(aq file.chown c:\etemp\etest.txt myusername "pgroup=\(aqNone\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.chpgrp(path, group)
Change the group of a file
.sp
Under Windows, this will set the rarely used primary group of a file.
This generally has no bearing on permissions unless intentionally
configured and is most commonly used to provide Unix compatibility (e.g.
Services For Unix, NFS services).
.sp
Ensure you know what you are doing before using this function.
.sp
To set the primary group to \(aqNone\(aq, it must be specified in quotes.
Otherwise Salt will interpret it as the Python value of None and no primary
group changes will occur. See the example below.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.chpgrp c:\etemp\etest.txt Administrators
salt \(aq*\(aq file.chpgrp c:\etemp\etest.txt "\(aqNone\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_attributes(path)
Return a dictionary object with the Windows
file attributes for a file.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_attributes c:\etemp\ea.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_gid(path, follow_symlinks=True)
Return the id of the group that owns a given file
.sp
Under Windows, this will return the uid of the file.
.sp
While a file in Windows does have a \(aqprimary group\(aq, this rarely used
attribute generally has no bearing on permissions unless intentionally
configured and is only used to support Unix compatibility features (e.g.
Services For Unix, NFS services).
.sp
Salt, therefore, remaps this function to provide functionality that
somewhat resembles Unix behavior for API compatibility reasons. When
managing Windows systems, this function is superfluous and will generate
an info level log entry if used directly.
.sp
If you do actually want to access the \(aqprimary group\(aq of a file, use
\fIfile.get_pgid\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_gid c:\etemp\etest.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_group(path, follow_symlinks=True)
Return the group that owns a given file
.sp
Under Windows, this will return the user (owner) of the file.
.sp
While a file in Windows does have a \(aqprimary group\(aq, this rarely used
attribute generally has no bearing on permissions unless intentionally
configured and is only used to support Unix compatibility features (e.g.
Services For Unix, NFS services).
.sp
Salt, therefore, remaps this function to provide functionality that
somewhat resembles Unix behavior for API compatibility reasons. When
managing Windows systems, this function is superfluous and will generate
an info level log entry if used directly.
.sp
If you do actually want to access the \(aqprimary group\(aq of a file, use
\fIfile.get_pgroup\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_group c:\etemp\etest.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_mode(path)
Return the mode of a file
.sp
Right now we\(aqre just returning None because Windows\(aq doesn\(aqt have a mode
like Linux
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_mode /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_pgid(path, follow_symlinks=True)
Return the id of the primary group that owns a given file (Windows only)
.sp
This function will return the rarely used primary group of a file. This
generally has no bearing on permissions unless intentionally configured
and is most commonly used to provide Unix compatibility (e.g. Services
For Unix, NFS services).
.sp
Ensure you know what you are doing before using this function.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_pgid c:\etemp\etest.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_pgroup(path, follow_symlinks=True)
Return the name of the primary group that owns a given file (Windows only)
.sp
This function will return the rarely used primary group of a file. This
generally has no bearing on permissions unless intentionally configured
and is most commonly used to provide Unix compatibility (e.g. Services
For Unix, NFS services).
.sp
Ensure you know what you are doing before using this function.
.sp
The return value may be \(aqNone\(aq, e.g. if the user is not on a domain. This is
a valid group \- do not confuse this with the Salt/Python value of None which
means no value was returned. To be certain, use the \fIget_pgid\fP function
which will return the SID, including for the system \(aqNone\(aq group.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_pgroup c:\etemp\etest.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_uid(path, follow_symlinks=True)
Return the id of the user that owns a given file
.sp
Symlinks are followed by default to mimic Unix behavior. Specify
\fIfollow_symlinks=False\fP to turn off this behavior.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_uid c:\etemp\etest.txt
salt \(aq*\(aq file.get_uid c:\etemp\etest.txt follow_symlinks=False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.get_user(path, follow_symlinks=True)
Return the user that owns a given file
.sp
Symlinks are followed by default to mimic Unix behavior. Specify
\fIfollow_symlinks=False\fP to turn off this behavior.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.get_user c:\etemp\etest.txt
salt \(aq*\(aq file.get_user c:\etemp\etest.txt follow_symlinks=False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.gid_to_group(gid)
Convert the group id to the group name on this system
.sp
Under Windows, because groups are just another ACL entity, this function
behaves the same as uid_to_user.
.sp
For maintaining Windows systems, this function is superfluous and only
exists for API compatibility with Unix. Use the uid_to_user function
instead; an info level log entry will be generated if this function is used
directly.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.gid_to_group S\-1\-5\-21\-626487655\-2533044672\-482107328\-1010
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.group_to_gid(group)
Convert the group to the gid on this system
.sp
Under Windows, because groups are just another ACL entity, this function
behaves the same as user_to_uid, except if None is given, \(aq\(aq is returned.
.sp
For maintaining Windows systems, this function is superfluous and only
exists for API compatibility with Unix. Use the user_to_uid function
instead; an info level log entry will be generated if this function is used
directly.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.group_to_gid administrators
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.is_link(path)
Return the path that a symlink points to
.sp
This is only supported on Windows Vista or later.
.sp
Inline with Unix behavior, this function will raise an error if the path
is not a symlink, however, the error raised will be a SaltInvocationError,
not an OSError.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.is_link /path/to/link
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.lchown(path, user, group=None, pgroup=None)
Chown a file, pass the file the desired user and group without following any
symlinks.
.sp
Under Windows, the group parameter will be ignored.
.sp
This is because while files in Windows do have a \(aqprimary group\(aq
property, this is rarely used. It generally has no bearing on
permissions unless intentionally configured and is most commonly used to
provide Unix compatibility (e.g. Services For Unix, NFS services).
.sp
If you do want to change the \(aqprimary group\(aq property and understand the
implications, pass the Windows only parameter, pgroup, instead.
.sp
To set the primary group to \(aqNone\(aq, it must be specified in quotes.
Otherwise Salt will interpret it as the Python value of None and no primary
group changes will occur. See the example below.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.lchown c:\etemp\etest.txt myusername
salt \(aq*\(aq file.lchown c:\etemp\etest.txt myusername pgroup=Administrators
salt \(aq*\(aq file.lchown c:\etemp\etest.txt myusername "pgroup=\(aqNone\(aq"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.readlink(path)
Return the path that a symlink points to
.sp
This is only supported on Windows Vista or later.
.sp
Inline with Unix behavior, this function will raise an error if the path is
not a symlink, however, the error raised will be a SaltInvocationError, not
an OSError.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.readlink /path/to/link
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.set_attributes(path, archive=None, hidden=None, normal=None, notIndexed=None, readonly=None, system=None, temporary=None)
Set file attributes for a file. Note that the normal attribute
means that all others are false. So setting it will clear all others.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.set_attributes c:\etemp\ea.txt normal=True
salt \(aq*\(aq file.set_attributes c:\etemp\ea.txt readonly=True hidden=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.set_mode(path, mode)
Set the mode of a file
.sp
This just calls get_mode, which returns None because we don\(aqt use mode on
Windows
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.set_mode /etc/passwd 0644
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.stats(path, hash_type=\(aqmd5\(aq, follow_symlinks=True)
Return a dict containing the stats for a given file
.sp
Under Windows, \fIgid\fP will equal \fIuid\fP and \fIgroup\fP will equal \fIuser\fP\&.
.sp
While a file in Windows does have a \(aqprimary group\(aq, this rarely used
attribute generally has no bearing on permissions unless intentionally
configured and is only used to support Unix compatibility features (e.g.
Services For Unix, NFS services).
.sp
Salt, therefore, remaps these properties to keep some kind of
compatibility with Unix behavior. If the \(aqprimary group\(aq is required, it
can be accessed in the \fIpgroup\fP and \fIpgid\fP properties.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.stats /etc/passwd
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.symlink(src, link)
Create a symbolic link to a file
.sp
This is only supported with Windows Vista or later and must be executed by
a user with the SeCreateSymbolicLink privilege.
.sp
The behavior of this function matches the Unix equivalent, with one
exception \- invalid symlinks cannot be created. The source path must exist.
If it doesn\(aqt, an error will be raised.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.symlink /path/to/file /path/to/link
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.uid_to_user(uid)
Convert a uid to a user name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.uid_to_user S\-1\-5\-21\-626487655\-2533044672\-482107328\-1010
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_file.user_to_uid(user)
Convert user name to a uid
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq file.user_to_uid myusername
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_firewall
.sp
Module for configuring Windows Firewall
.INDENT 0.0
.TP
.B salt.modules.win_firewall.add_rule(name, localport, protocol=\(aqtcp\(aq, action=\(aqallow\(aq, dir=\(aqin\(aq)
Add a new firewall rule
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq firewall.add_rule "test" "tcp" "8080"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_firewall.disable()
Disable all the firewall profiles
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq firewall.disable
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_firewall.get_config()
Get the status of all the firewall profiles
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq firewall.get_config
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_firewall.get_rule(name=\(aqall\(aq)
Get firewall rule(s) info
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq firewall.get_rule "MyAppPort"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_groupadd
.sp
Manage groups on Windows
.INDENT 0.0
.TP
.B salt.modules.win_groupadd.add(name, gid=None, system=False)
Add the specified group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.add foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_groupadd.delete(name)
Remove the named group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.delete foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_groupadd.getent(refresh=False)
Return info on all groups
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_groupadd.info(name)
Return information about a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq group.info foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_ip
.sp
The networking module for Windows based systems
.INDENT 0.0
.TP
.B salt.modules.win_ip.disable(iface)
Disable an interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.disable \(aqLocal Area Connection #2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.enable(iface)
Enable an interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.enable \(aqLocal Area Connection #2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.get_all_interfaces()
Return configs for all interfaces
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.get_all_interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.get_default_gateway()
Set DNS source to DHCP on Windows
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.get_default_gateway
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.get_interface(iface)
Return the configuration of a network interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.get_interface \(aqLocal Area Connection\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.get_subnet_length(mask)
Convenience function to convert the netmask to the CIDR subnet length
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.get_subnet_length 255.255.255.0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.is_disabled(iface)
Returns \fBTrue\fP if interface is disabled, otherwise \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.is_disabled \(aqLocal Area Connection #2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.is_enabled(iface)
Returns \fBTrue\fP if interface is enabled, otherwise \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.is_enabled \(aqLocal Area Connection #2\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.raw_interface_configs()
Return raw configs for all interfaces
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.raw_interface_configs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.set_dhcp_all(iface)
Set both IP Address and DNS to DHCP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.set_dhcp_all \(aqLocal Area Connection\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.set_dhcp_dns(iface)
Set DNS source to DHCP on Windows
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.set_dhcp_dns \(aqLocal Area Connection\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.set_dhcp_ip(iface)
Set Windows NIC to get IP from DHCP
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.set_dhcp_ip \(aqLocal Area Connection\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.set_static_dns(iface, *addrs)
Set static DNS configuration on a Windows NIC
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.set_static_dns \(aqLocal Area Connection\(aq \(aq192.168.1.1\(aq
salt \-G \(aqos_family:Windows\(aq ip.set_static_dns \(aqLocal Area Connection\(aq \(aq192.168.1.252\(aq \(aq192.168.1.253\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ip.set_static_ip(iface, addr, gateway=None, append=False)
Set static IP configuration on a Windows NIC
.INDENT 7.0
.TP
.B iface
The name of the interface to manage
.TP
.B addr
IP address with subnet length (ex. \fB10.1.2.3/24\fP). The
\fI\%ip.get_subnet_length\fP
function can be used to calculate the subnet length from a netmask.
.TP
.B gateway
None
If specified, the default gateway will be set to this value.
.TP
.B append
False
If \fBTrue\fP, this IP address will be added to the interface. Default is
\fBFalse\fP, which overrides any existing configuration for the interface
and sets \fBaddr\fP as the only address on the interface.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G \(aqos_family:Windows\(aq ip.set_static_ip \(aqLocal Area Connection\(aq 10.1.2.3/24 gateway=10.1.2.1
salt \-G \(aqos_family:Windows\(aq ip.set_static_ip \(aqLocal Area Connection\(aq 10.1.2.4/24 append=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_network
.sp
Module for gathering and managing network information
.INDENT 0.0
.TP
.B salt.modules.win_network.dig(host)
Performs a DNS lookup with dig
.sp
Note: dig must be installed on the Windows minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.dig archlinux.org
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.hw_addr(iface)
Return the hardware address (a.k.a. MAC address) for a given interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.hw_addr \(aqWireless Connection #1\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.hwaddr(iface)
Return the hardware address (a.k.a. MAC address) for a given interface
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.hw_addr \(aqWireless Connection #1\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.in_subnet(cidr)
Returns True if host is within specified subnet, otherwise False
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.in_subnet 10.0.0.0/16
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.interfaces()
Return a dictionary of information about all the interfaces on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.interfaces_names()
Return a list of all the interfaces names
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.interfaces_names
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.ip_addrs(interface=None, include_loopback=False)
Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is
ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is
provided, then only IP addresses from that interface will be returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.ip_addrs6(interface=None, include_loopback=False)
Returns a list of IPv6 addresses assigned to the host. ::1 is ignored,
unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided,
then only IP addresses from that interface will be returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.ipaddrs(interface=None, include_loopback=False)
Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is
ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is
provided, then only IP addresses from that interface will be returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.ipaddrs6(interface=None, include_loopback=False)
Returns a list of IPv6 addresses assigned to the host. ::1 is ignored,
unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided,
then only IP addresses from that interface will be returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ip_addrs6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.netstat()
Return information on open ports and states
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.netstat
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.nslookup(host)
Query DNS for information about a domain or ip address
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.nslookup archlinux.org
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.ping(host)
Performs a ping to a host
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.ping archlinux.org
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.subnets()
Returns a list of subnets to which the host belongs
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.subnets
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_network.traceroute(host)
Performs a traceroute to a 3rd party host
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq network.traceroute archlinux.org
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_ntp
.sp
Management of NTP servers on Windows
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B salt.modules.win_ntp.get_servers()
Get list of configured NTP servers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ntp.get_servers
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ntp.set_servers(*servers)
Set Windows to use a list of NTP servers
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq ntp.set_servers \(aqpool.ntp.org\(aq \(aqus.pool.ntp.org\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_path
.sp
Manage the Windows System PATH
.sp
Note that not all Windows applications will rehash the PATH environment variable,
Only the ones that listen to the WM_SETTINGCHANGE message
\fI\%http://support.microsoft.com/kb/104011\fP
.INDENT 0.0
.TP
.B salt.modules.win_path.add(path, index=0)
Add the directory to the SYSTEM path in the index location
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Will add to the beginning of the path
salt \(aq*\(aq win_path.add \(aqc:\epython27\(aq 0
# Will add to the end of the path
salt \(aq*\(aq win_path.add \(aqc:\epython27\(aq index=\(aq\-1\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_path.exists(path)
Check if the directory is configured in the SYSTEM path
Case\-insensitive and ignores trailing backslash
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_path.exists \(aqc:\epython27\(aq
salt \(aq*\(aq win_path.exists \(aqc:\epython27\e\(aq
salt \(aq*\(aq win_path.exists \(aqC:\epyThon27\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_path.get_path()
Returns the system path
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_path.rehash()
Send a WM_SETTINGCHANGE Broadcast to Windows to rehash the Environment variables
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_path.remove(path)
Remove the directory from the SYSTEM path
.UNINDENT
.SS salt.modules.win_pkg
.sp
A module to manage software on Windows
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
win32com
.IP \(bu 2
win32con
.IP \(bu 2
win32api
.IP \(bu 2
pywintypes
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.get_repo_data(saltenv=\(aqbase\(aq)
Returns the cached winrepo data
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.get_repo_data
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.install(name=None, refresh=False, pkgs=None, saltenv=\(aqbase\(aq, **kwargs)
Install the passed package
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.list_available(*names)
Return a list of available versions of the specified package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_available <package name>
salt \(aq*\(aq pkg.list_available <package name01> <package name02>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
salt \(aq*\(aq pkg.list_pkgs versions_as_list=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.list_upgrades(refresh=True)
List all available package upgrades on this system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.purge(name=None, pkgs=None, version=None, **kwargs)
Package purges are not supported, this function is identical to
\fBremove()\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.TP
.B version
The version of the package to be deleted. If this option is used in
combination with the \fBpkgs\fP option below, then this version will be
applied to all targeted packages.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.refresh_db(saltenv=\(aqbase\(aq)
Just recheck the repository and return a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<database name>\(aq: Bool}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.remove(name=None, pkgs=None, version=None, extra_uninstall_flags=None, **kwargs)
Remove packages.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.TP
.B version
The version of the package to be deleted. If this option is used in
combination with the \fBpkgs\fP option below, then this version will be
applied to all targeted packages.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.upgrade(refresh=True)
Run a full system upgrade
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.upgrade_available(name)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pkg.version(*names, **kwargs)
Returns a version if the package is installed, else returns an empty string
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_repo
.sp
Module to manage Windows software repo on a Standalone Minion
.INDENT 0.0
.TP
.B The following options must be set in the Minion config:
file_client: local
win_repo_cachefile: c:saltfile_rootswinrepowinrepo.p
win_repo: c:saltfile_rootswinrepo
.UNINDENT
.sp
Place all Windows package files in the \(aqwin_repo\(aq directory.
.INDENT 0.0
.TP
.B salt.modules.win_repo.genrepo()
Generate win_repo_cachefile based on sls files in the win_repo
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call winrepo.genrepo \-c c:\esalt\econf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_repo.update_git_repos()
Checkout git repos containing Windows Software Package Definitions
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function will not work unless git is installed and the git module
is further updated to work on Windows. In the meantime just place all
Windows package files in the \fBwin_repo\fP directory.
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_servermanager
.sp
Manage Windows features via the ServerManager powershell module
.INDENT 0.0
.TP
.B salt.modules.win_servermanager.install(feature, recurse=False)
Install a feature
.sp
Note:
Some features requires reboot after un/installation, if so until the server is restarted
Other features can not be installed !
.sp
Note:
Some features takes a long time to complete un/installation, set \-t with a long timeout
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_servermanager.install Telnet\-Client
salt \(aq*\(aq win_servermanager.install SNMP\-Services True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_servermanager.list_available()
List available features to install
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_servermanager.list_available
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_servermanager.list_installed()
List installed features
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_servermanager.list_installed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_servermanager.remove(feature)
Remove an installed feature
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Some features require a reboot after installation/uninstallation. If
one of these features are modified, then other features cannot be
installed until the server is restarted. Additionally, some features
take a while to complete installation/uninstallation, so it is a good
idea to use the \fB\-t\fP option to set a longer timeout.
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-t 600 \(aq*\(aq win_servermanager.remove Telnet\-Client
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_service
.sp
Windows Service module.
.INDENT 0.0
.TP
.B salt.modules.win_service.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.available <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.disable(name, **kwargs)
Disable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.disabled(name)
Check to see if the named service is disabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.disabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.enable(name, **kwargs)
Enable the named service to start at boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enable <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.enabled(name)
Check to see if the named service is enabled to start on boot
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.enabled <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.get_all()
Return all installed services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.get_disabled()
Return the disabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_disabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.get_enabled()
Return the enabled services
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_enabled
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.get_service_name(*args)
The Display Name is what is displayed in Windows when services.msc is
executed. Each Display Name has an associated Service Name which is the
actual name of the service. This function allows you to discover the
Service Name by returning a dictionary of Display Names and Service Names,
or filter by adding arguments of Display Names.
.sp
If no args are passed, return a dict of all services where the keys are the
service Display Names and the values are the Service Names.
.sp
If arguments are passed, create a dict of Display Names and Service Names
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.get_service_name
salt \(aq*\(aq service.get_service_name \(aqGoogle Update Service (gupdate)\(aq \(aqDHCP Client\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.getsid(name)
Return the sid for this windows service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.getsid <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.has_powershell()
Confirm if Powershell is available
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.has_powershell
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.missing(name)
The inverse of service.available.
Returns \fBTrue\fP if the specified service is not available, otherwise returns
\fBFalse\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.missing <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.restart(name)
Restart the named service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.restart <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.start(name)
Start the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.start <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.status(name, sig=None)
Return the status for a service, returns the PID or an empty string if the
service is running or not, pass a signature to use to find the service via
ps
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.status <service name> [service signature]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.stop(name)
Stop the specified service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq service.stop <service name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_shadow
.sp
Manage the shadow file
.INDENT 0.0
.TP
.B salt.modules.win_shadow.info(name)
Return information for the specified user
This is just returns dummy data so that salt states can work.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_shadow.set_password(name, password)
Set the password for a named user.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq shadow.set_password root mysecretpassword
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_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 depends
.INDENT 7.0
.IP \(bu 2
pythoncom
.IP \(bu 2
wmi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_status.master(master=None, connected=True)
Fire an event if the minion gets disconnected from its master. This
function is meant to be run via a scheduled job from the minion. If
master_ip is an FQDN/Hostname, is must be resolvable to a valid IPv4
address.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_status.procs()
Return the process data
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq status.procs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_system
.sp
Support for reboot, shutdown, etc
.INDENT 0.0
.TP
.B salt.modules.win_system.get_computer_desc()
Get the Windows computer description
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\-id\(aq system.get_computer_desc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.get_computer_name()
Get the Windows computer name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\-id\(aq system.get_computer_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.get_pending_computer_name()
Get a pending computer name. If the computer name has been changed, and the
change is pending a system reboot, this function will return the pending
computer name. Otherwise, \fBNone\fP will be returned. If there was an error
retrieving the pending computer name, \fBFalse\fP will be returned, and an
error message will be logged to the minion log.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\-id\(aq system.get_pending_computer_name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.get_system_date()
Get the Windows system date
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.get_system_date
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.get_system_time()
Get the Windows system time
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.get_system_time
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.halt(timeout=5)
Halt a running system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.halt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.init(runlevel)
Change the system runlevel on sysV compatible systems
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.init 3
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.join_domain(domain=None, username=None, password=None, account_ou=None, account_exists=False)
Join a computer to an Active Directory domain
.INDENT 7.0
.TP
.B domain
The domain to which the computer should be joined, e.g.
\fBmy\-company.com\fP
.TP
.B username
Username of an account which is authorized to join computers to the
specified domain. Need to be either fully qualified like
\fBuser@domain.tld\fP or simply \fBuser\fP
.TP
.B password
Password of the specified user
.TP
.B account_ou
None
The DN of the OU below which the account for this computer should be
created when joining the domain, e.g.
\fBou=computers,ou=departm_432,dc=my\-company,dc=com\fP
.TP
.B account_exists
False
Needs to be set to \fBTrue\fP to allow re\-using an existing account
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\-id\(aq system.join_domain domain=\(aqdomain.tld\(aq \e
username=\(aqjoinuser\(aq password=\(aqjoinpassword\(aq \e
account_ou=\(aqou=clients,ou=org,dc=domain,dc=tld\(aq \e
account_exists=False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.poweroff(timeout=5)
Poweroff a running system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.poweroff
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.reboot(timeout=5)
Reboot the system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.reboot
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.set_computer_desc(desc)
Set the Windows computer description
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\-id\(aq system.set_computer_desc \(aqThis computer belongs to Dave!\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.set_computer_name(name)
Set the Windows computer name
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqminion\-id\(aq system.set_computer_name \(aqDavesComputer\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.set_system_date(newdate)
Set the Windows system date. Use <mm\-dd\-yy> format for the date.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.set_system_date \(aq03\-28\-13\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.set_system_time(newtime)
Set the Windows system time
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.set_system_time \(aq11:31:15 AM\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.shutdown(timeout=5)
Shutdown a running system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.shutdown
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.shutdown_hard()
Shutdown a running system with no timeout or warning
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.shutdown_hard
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.start_time_service()
Start the Windows time service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.start_time_service
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_system.stop_time_service()
Stop the Windows time service
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq system.stop_time_service
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_timezone
.sp
Module for managing timezone on Windows systems.
.INDENT 0.0
.TP
.B salt.modules.win_timezone.get_hwclock()
Get current hardware clock setting (UTC or localtime)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_hwclock
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_timezone.get_offset()
Get current numeric timezone offset from UCT (i.e. \-0700)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_offset
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_timezone.get_zone()
Get current timezone (i.e. America/Denver)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_zone
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_timezone.get_zonecode()
Get current timezone (i.e. PST, MDT, etc)
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.get_zonecode
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_timezone.set_hwclock(clock)
Sets the hardware clock to be either UTC or localtime
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.set_hwclock UTC
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_timezone.set_zone(timezone)
Unlinks, then symlinks /etc/localtime to the set timezone.
.sp
The timezone is crucial to several system processes, each of which SHOULD
be restarted (for instance, whatever you system uses as its cron and
syslog daemons). This will not be magically done for you!
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.set_zone \(aqAmerica/Denver\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_timezone.zone_compare(timezone)
Checks the md5sum between the given timezone, and the one set in
/etc/localtime. Returns True if they match, and False if not. Mostly useful
for running state checks.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq timezone.zone_compare \(aqAmerica/Denver\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_update
.sp
Module for running windows updates.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
win32com
.IP \(bu 2
win32con
.IP \(bu 2
win32api
.IP \(bu 2
pywintypes
.UNINDENT
.UNINDENT
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B class salt.modules.win_update.PyWinUpdater(categories=None, skipUI=True, skipDownloaded=False, skipInstalled=True, skipReboot=False, skipPresent=False, softwareUpdates=True, driverUpdates=False, skipHidden=True)
.INDENT 7.0
.TP
.B AutoSearch()
this function generates a search string. simplifying the search function while
still providing as many features as possible.
.UNINDENT
.INDENT 7.0
.TP
.B Download()
.UNINDENT
.INDENT 7.0
.TP
.B GetAvailableCategories()
.UNINDENT
.INDENT 7.0
.TP
.B GetCategories()
.UNINDENT
.INDENT 7.0
.TP
.B GetDownloadResults()
.UNINDENT
.INDENT 7.0
.TP
.B GetInstallationResults()
this gets results of installation process.
.UNINDENT
.INDENT 7.0
.TP
.B GetInstallationResultsPretty()
converts the installation results into a pretty print.
.UNINDENT
.INDENT 7.0
.TP
.B GetSearchResults()
.UNINDENT
.INDENT 7.0
.TP
.B GetSearchResultsPretty()
.UNINDENT
.INDENT 7.0
.TP
.B Install()
.UNINDENT
.INDENT 7.0
.TP
.B Search(searchString)
.UNINDENT
.INDENT 7.0
.TP
.B SetCategories(categories)
.UNINDENT
.INDENT 7.0
.TP
.B SetInclude(include, state)
.UNINDENT
.INDENT 7.0
.TP
.B SetIncludes(includes)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_update.download_updates(includes=None, retries=5, categories=None)
Downloads all available updates, skipping those that require user
interaction.
.sp
Various aspects of the updates can be included or excluded. this feature is
still in development.
.INDENT 7.0
.TP
.B retries
Number of retries to make before giving up. This is total, not per
step.
.TP
.B categories
Specify the categories to update. Must be passed as a list.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_update.download_updates categories="[\(aqUpdates\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Categories include the following:
.INDENT 7.0
.IP \(bu 2
Updates
.IP \(bu 2
Windows 7
.IP \(bu 2
Critical Updates
.IP \(bu 2
Security Updates
.IP \(bu 2
Update Rollups
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Normal Usage
salt \(aq*\(aq win_update.download_updates
# Download critical updates only
salt \(aq*\(aq win_update.download_updates categories="[\(aqCritical Updates\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_update.install_updates(includes=None, retries=5, categories=None)
Downloads and installs all available updates, skipping those that require
user interaction.
.sp
various aspects of the updates can be included or excluded. this feature is
still in development.
.INDENT 7.0
.TP
.B retries
Number of retries to make before giving up. This is total, not per
step.
.TP
.B categories
Specify the categories to install. Must be passed as a list.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_update.install_updates categories="[\(aqUpdates\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Categories include the following:
.INDENT 7.0
.IP \(bu 2
Updates
.IP \(bu 2
Windows 7
.IP \(bu 2
Critical Updates
.IP \(bu 2
Security Updates
.IP \(bu 2
Update Rollups
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Normal Usage
salt \(aq*\(aq win_update.install_updates
# Install all critical updates
salt \(aq*\(aq win_update.install_updates categories="[\(aqCritical Updates\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_update.list_updates(verbose=False, includes=None, retries=5, categories=None)
Returns a summary of available updates, grouped into their non\-mutually
exclusive categories.
.INDENT 7.0
.TP
.B verbose
Print results in greater detail
.TP
.B retries
Number of retries to make before giving up. This is total, not per
step.
.TP
.B categories
Specify the categories to list. Must be passed as a list.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq win_update.list_updates categories="[\(aqUpdates\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Categories include the following:
.INDENT 7.0
.IP \(bu 2
Updates
.IP \(bu 2
Windows 7
.IP \(bu 2
Critical Updates
.IP \(bu 2
Security Updates
.IP \(bu 2
Update Rollups
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Normal Usage
salt \(aq*\(aq win_update.list_updates
# List all critical updates list in verbose detail
salt \(aq*\(aq win_update.list_updates categories=[\(aqCritical Updates\(aq] verbose=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.win_useradd
.sp
Manage Windows users with the net user command
.sp
NOTE: This currently only works with local user accounts, not domain accounts
.INDENT 0.0
.TP
.B salt.modules.win_useradd.add(name, password=None, uid=None, gid=None, groups=None, home=False, shell=None, unique=False, system=False, fullname=False, roomnumber=False, workphone=False, homephone=False, createhome=False)
Add a user to the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.add name password
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.addgroup(name, group)
Add user to a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.addgroup username groupname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.chfullname(name, fullname)
Change the full name of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chfullname user \(aqFirst Last\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.chgroups(name, groups, append=False)
Change the groups this user belongs to, add append to append the specified
groups
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chgroups foo wheel,root True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.chhome(name, home)
Change the home directory of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chhome foo \e\efileserver\ehome\efoo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.chprofile(name, profile)
Change the profile directory of the user
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.chprofile foo \e\efileserver\eprofiles\efoo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.delete(name, purge=False, force=False)
Remove a user from the minion
NOTE: purge and force have not been implemented on Windows yet
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.delete name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.getent(refresh=False)
Return the list of all info for all users
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.getent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.info(name)
Return user information
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.info root
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.list_groups(name)
Return a list of groups the named user belongs to
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.list_groups foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.list_users()
Return a list of users on Windows
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.removegroup(name, group)
Remove user from a group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.removegroup username groupname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_useradd.setpassword(name, password)
Set a user\(aqs password
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq user.setpassword name password
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.xapi
.sp
This module (mostly) uses the XenAPI to manage Xen virtual machines.
.sp
Big fat warning: the XenAPI used in this file is the one bundled with
Xen Source, NOT XenServer nor Xen Cloud Platform. As a matter of fact it
\fIwill\fP fail under those platforms. From what I\(aqve read, little work is needed
to adapt this code to XS/XCP, mostly playing with XenAPI version, but as
XCP is not taking precedence on Xen Source on many platforms, please keep
compatibility in mind.
.sp
Useful documentation:
.sp
\&. \fI\%http://downloads.xen.org/Wiki/XenAPI/xenapi\-1.0.6.pdf\fP
. \fI\%http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/\fP
. \fI\%https://github.com/xapi\-project/xen\-api/tree/master/scripts/examples/python\fP
. \fI\%http://xenbits.xen.org/gitweb/?p=xen.git;a=tree;f=tools/python/xen/xm;hb=HEAD\fP
.INDENT 0.0
.TP
.B salt.modules.xapi.create(config_)
Start a defined domain
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.create <path to Xen cfg file>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.destroy(vm_)
Hard power down the virtual machine, this is equivalent to pulling the
power
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.destroy <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.freecpu()
Return an int representing the number of unallocated cpus on this
hypervisor
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.freecpu
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.freemem()
Return an int representing the amount of memory that has not been given
to virtual machines on this node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.freemem
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.full_info()
Return the node_info, vm_info and freemem
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.full_info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.get_disks(vm_)
Return the disks of a named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_disks <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.get_macs(vm_)
Return a list off MAC addresses from the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_macs <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.get_nics(vm_)
Return info about the network interfaces of a named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.get_nics <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.is_hyper()
Returns a bool whether or not this node is a hypervisor of any kind
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.is_hyper
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.list_vms()
Return a list of virtual machine names on the minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.list_vms
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.migrate(vm_, target, live=1, port=0, node=\-1, ssl=None, change_home_server=0)
Migrates the virtual machine to another hypervisor
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.migrate <vm name> <target hypervisor> [live] [port] [node] [ssl] [change_home_server]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Optional values:
.INDENT 7.0
.TP
.B live
Use live migration
.TP
.B port
Use a specified port
.TP
.B node
Use specified NUMA node on target
.TP
.B ssl
use ssl connection for migration
.TP
.B change_home_server
change home server for managed domains
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.node_info()
Return a dict with information about this node
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.node_info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.pause(vm_)
Pause the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.pause <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.reboot(vm_)
Reboot a domain via ACPI request
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.reboot <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.reset(vm_)
Reset a VM by emulating the reset button on a physical machine
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.reset <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.resume(vm_)
Resume the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.resume <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.setmem(vm_, memory)
Changes the amount of memory allocated to VM.
.sp
Memory is to be specified in MB
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.setmem myvm 768
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.setvcpus(vm_, vcpus)
Changes the amount of vcpus allocated to VM.
.sp
vcpus is an int representing the number to be assigned
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.setvcpus myvm 2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.shutdown(vm_)
Send a soft shutdown signal to the named vm
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.shutdown <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.start(config_)
Alias for the obscurely named \(aqcreate\(aq function
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.start <path to Xen cfg file>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.vcpu_pin(vm_, vcpu, cpus)
Set which CPUs a VCPU can use.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqfoo\(aq virt.vcpu_pin domU\-id 2 1
salt \(aqfoo\(aq virt.vcpu_pin domU\-id 2 2\-6
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.vm_cputime(vm_=None)
Return cputime used by the vms on this hyper in a
list of dicts:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
\(aqyour\-vm\(aq: {
\(aqcputime\(aq <int>
\(aqcputime_percent\(aq <int>
},
...
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_cputime
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.vm_diskstats(vm_=None)
Return disk usage counters used by the vms on this hyper in a
list of dicts:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
\(aqyour\-vm\(aq: {
\(aqio_read_kbs\(aq : 0,
\(aqio_write_kbs\(aq : 0
},
...
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_diskstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.vm_info(vm_=None)
Return detailed information about the vms.
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_info
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.vm_netstats(vm_=None)
Return combined network counters used by the vms on this hyper in a
list of dicts:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[
\(aqyour\-vm\(aq: {
\(aqio_read_kbs\(aq : 0,
\(aqio_total_read_kbs\(aq : 0,
\(aqio_total_write_kbs\(aq : 0,
\(aqio_write_kbs\(aq : 0
},
...
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_netstats
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xapi.vm_state(vm_=None)
Return list of all the vms and their state.
.sp
If you pass a VM name in as an argument then it will return info
for just the named VM, otherwise it will return all VMs.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq virt.vm_state <vm name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.xmpp
.sp
Module for Sending Messages via XMPP (a.k.a. Jabber)
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
sleekxmpp python module
.UNINDENT
.TP
.B configuration
This module can be used by either passing a jid and password
directly to send_message, or by specifying the name of a configuration
profile in the minion config, minion pillar, or master config.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
my\-xmpp\-login:
xmpp.jid: myuser@jabber.example.org/resourcename
xmpp.password: verybadpass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The resourcename refers to the resource that is using this account. It is
user\-definable, and optional. The following configurations are both valid:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
my\-xmpp\-login:
xmpp.jid: myuser@jabber.example.org/salt
xmpp.password: verybadpass
my\-xmpp\-login:
xmpp.jid: myuser@jabber.example.org
xmpp.password: verybadpass
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.modules.xmpp.SendMsgBot(jid, password, recipient, msg)
.INDENT 7.0
.TP
.B start(event)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xmpp.send_msg(recipient, message, jid=None, password=None, profile=None)
Send a message to an XMPP recipient. Designed for use in states.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
xmpp.send_msg \(aqadmins@xmpp.example.com\(aq \(aqThis is a salt module test\(aq profile=\(aqmy\-xmpp\-account\(aq
xmpp.send_msg \(aqadmins@xmpp.example.com\(aq \(aqThis is a salt module test\(aq jid=\(aqmyuser@xmpp.example.com/salt\(aq password=\(aqverybadpass\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.yumpkg
.sp
Support for YUM
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module makes heavy use of the \fBrepoquery\fP utility, from the
\fI\%yum\-utils\fP package. This package will be installed as a dependency if salt
is installed via EPEL. However, if salt has been installed using pip, or a
host is being managed using salt\-ssh, then as of version 2014.7.0
\fI\%yum\-utils\fP will be installed automatically to satisfy this dependency.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.check_db(*names, **kwargs)
New in version 0.17.0.
.sp
Returns a dict containing the following information for each specified
package:
.INDENT 7.0
.IP 1. 3
A key \fBfound\fP, which will be a boolean value denoting if a match was
found in the package database.
.IP 2. 3
If \fBfound\fP is \fBFalse\fP, then a second key called \fBsuggestions\fP will
be present, which will contain a list of possible matches.
.UNINDENT
.sp
The \fBfromrepo\fP, \fBenablerepo\fP and \fBdisablerepo\fP arguments are
supported, as used in pkg states, and the \fBdisableexcludes\fP option is
also supported.
.sp
New in version 2014.7.0: Support for the \fBdisableexcludes\fP option
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.check_db <package1> <package2> <package3>
salt \(aq*\(aq pkg.check_db <package1> <package2> <package3> fromrepo=epel\-testing
salt \(aq*\(aq pkg.check_db <package1> <package2> <package3> disableexcludes=main
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.clean_metadata(**kwargs)
New in version 2014.1.0.
.sp
Cleans local yum metadata. Functionally identical to \fI\%refresh_db()\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.clean_metadata
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.del_repo(repo, basedir=\(aq/etc/yum.repos.d\(aq, **kwargs)
Delete a repo from <basedir> (default basedir: /etc/yum.repos.d).
.sp
If the .repo file that the repo exists in does not contain any other repo
configuration, the file itself will be deleted.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.del_repo myrepo
salt \(aq*\(aq pkg.del_repo myrepo basedir=/path/to/dir
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.expand_repo_def(repokwargs)
Take a repository definition and expand it to the full pkg repository dict
that can be used for comparison. This is a helper function to make
certain repo managers sane for comparison in the pkgrepo states.
.sp
There is no use to calling this function via the CLI.
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.file_dict(*packages)
New in version 2014.1.0.
.sp
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of \fIevery\fP file on the system\(aqs
rpm database (not generally recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.file_list(*packages)
New in version 2014.1.0.
.sp
List the files that belong to a package. Not specifying any packages will
return a list of \fIevery\fP file on the system\(aqs rpm database (not generally
recommended).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.file_list httpd
salt \(aq*\(aq pkg.file_list httpd postfix
salt \(aq*\(aq pkg.file_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.get_locked_packages(pattern=None, full=True)
Get packages that are currently locked
\fByum \-q versionlock list\fP\&.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.get_locked_packages
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.get_repo(repo, basedir=\(aq/etc/yum.repos.d\(aq, **kwargs)
Display a repo from <basedir> (default basedir: \fB/etc/yum.repos.d\fP).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.get_repo myrepo
salt \(aq*\(aq pkg.get_repo myrepo basedir=/path/to/dir
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.group_diff(name)
New in version 2014.1.0.
.sp
Lists packages belonging to a certain group, and which are installed
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.group_diff \(aqPerl Support\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.group_info(name)
New in version 2014.1.0.
.sp
Lists packages belonging to a certain group
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.group_info \(aqPerl Support\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.group_install(name, skip=(), include=(), **kwargs)
New in version 2014.1.0.
.sp
Install the passed package group(s). This is basically a wrapper around
pkg.install, which performs package group resolution for the user. This
function is currently considered experimental, and should be expected to
undergo changes.
.INDENT 7.0
.TP
.B name
Package group to install. To install more than one group, either use a
comma\-separated list or pass the value as a python list.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.group_install \(aqGroup 1\(aq
salt \(aq*\(aq pkg.group_install \(aqGroup 1,Group 2\(aq
salt \(aq*\(aq pkg.group_install \(aq["Group 1", "Group 2"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B skip
The name(s), in a list, of any packages that would normally be
installed by the package group ("default" packages), which should not
be installed. Can be passed either as a comma\-separated list or a
python list.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq skip=\(aqfoo,bar\(aq
salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq skip=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B include
The name(s), in a list, of any packages which are included in a group,
which would not normally be installed ("optional" packages). Note that
this will not enforce group membership; if you include packages which
are not members of the specified groups, they will still be installed.
Can be passed either as a comma\-separated list or a python list.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq include=\(aqfoo,bar\(aq
salt \(aq*\(aq pkg.group_install \(aqMy Group\(aq include=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Because this is essentially a wrapper around pkg.install, any argument
which can be passed to pkg.install may also be included here, and it
will be passed along wholesale.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.group_list()
New in version 2014.1.0.
.sp
Lists all groups known by yum on this system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.group_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.hold(name=None, pkgs=None, sources=None, **kwargs)
New in version 2014.7.0.
.sp
Hold packages with \fByum \-q versionlock\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to hold. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.hold <package name>
salt \(aq*\(aq pkg.hold pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.install(name=None, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, sources=None, reinstall=False, normalize=True, **kwargs)
Install the passed package(s), add refresh=True to clean the yum database
before package is installed.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Note that this parameter is
ignored if either "pkgs" or "sources" is passed. Additionally, please
note that this option can only be used to install packages from a
software repository. To install a package file manually, use the
"sources" option.
.sp
32\-bit packages can be installed on 64\-bit systems by appending the
architecture designation (\fB\&.i686\fP, \fB\&.i586\fP, etc.) to the end of the
package name.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B refresh
Whether or not to update the yum database before executing.
.TP
.B reinstall
Specifying reinstall=True will use \fByum reinstall\fP rather than
\fByum install\fP for requested packages that are already installed.
.sp
If a version is specified with the requested package, then
\fByum reinstall\fP will only be used if the installed version
matches the requested version.
.sp
Works with sources when the package header of the source can be
matched to the name and version of an installed package.
.sp
New in version 2014.7.0.
.TP
.B skip_verify
Skip the GPG verification check (e.g., \fB\-\-nogpgcheck\fP)
.TP
.B version
Install a specific version of the package, e.g. 1.2.3\-4.el5. Ignored
if "pkgs" or "sources" is passed.
.UNINDENT
.sp
Repository Options:
.INDENT 7.0
.TP
.B fromrepo
Specify a package repository (or repositories) from which to install.
(e.g., \fByum \-\-disablerepo=\(aq*\(aq \-\-enablerepo=\(aqsomerepo\(aq\fP)
.TP
.B enablerepo (ignored if \fBfromrepo\fP is specified)
Specify a disabled package repository (or repositories) to enable.
(e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP)
.TP
.B disablerepo (ignored if \fBfromrepo\fP is specified)
Specify an enabled package repository (or repositories) to disable.
(e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP)
.TP
.B disableexcludes
Disable exclude from main, for a repo or for everything.
(e.g., \fByum \-\-disableexcludes=\(aqmain\(aq\fP)
.sp
New in version 2014.7.0.
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from a software repository. Must be
passed as a python list. A specific version number can be specified
by using a single\-element dict representing the package and its
version.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-4.el5"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B sources
A list of RPM packages to install. Must be passed as a list of dicts,
with the keys being package names, and the values being the source URI
or local path to the package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B normalize
Normalize the package name by removing the architecture. Default is True.
This is useful for poorly created packages which might include the
architecture as an actual part of the name such as kernel modules
which match a specific kernel version.
.sp
New in version 2014.7.0.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-G role:nsd pkg.install gpfs.gplbin\-2.6.32\-279.31.1.el6.x86_64 normalize=False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
A specific repo can be requested using the \fBfromrepo\fP keyword argument,
and the \fBdisableexcludes\fP option is also supported.
.sp
New in version 2014.7.0: Support for the \fBdisableexcludes\fP option
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package name> fromrepo=epel\-testing
salt \(aq*\(aq pkg.latest_version <package name> disableexcludes=main
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed in a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.list_repo_pkgs(*args, **kwargs)
New in version 2014.1.0.
.sp
Changed in version 2014.7.0: All available versions of each package are now returned. This required
a slight modification to the structure of the return dict. The return
data shown below reflects the updated return dict structure.
.sp
Returns all available packages. Optionally, package names (and name globs)
can be passed and the results will be filtered to packages matching those
names. This is recommended as it speeds up the function considerably.
.sp
This function can be helpful in discovering the version or repo to specify
in a \fBpkg.installed\fP state.
.sp
The return data is a dictionary of repo names, with each repo containing a
dictionary in which the keys are package names, and the values are a list
of version numbers. Here is an example of the return data:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{
\(aqbase\(aq: {
\(aqbash\(aq: [\(aq4.1.2\-15.el6_4\(aq],
\(aqkernel\(aq: [\(aq2.6.32\-431.el6\(aq]
},
\(aqupdates\(aq: {
\(aqbash\(aq: [\(aq4.1.2\-15.el6_5.2\(aq, \(aq4.1.2\-15.el6_5.1\(aq],
\(aqkernel\(aq: [\(aq2.6.32\-431.29.2.el6\(aq,
\(aq2.6.32\-431.23.3.el6\(aq,
\(aq2.6.32\-431.20.5.el6\(aq,
\(aq2.6.32\-431.20.3.el6\(aq,
\(aq2.6.32\-431.17.1.el6\(aq,
\(aq2.6.32\-431.11.2.el6\(aq,
\(aq2.6.32\-431.5.1.el6\(aq,
\(aq2.6.32\-431.3.1.el6\(aq,
\(aq2.6.32\-431.1.2.0.1.el6\(aq]
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B fromrepo
None
Only include results from the specified repo(s). Multiple repos can be
specified, comma\-separated.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_repo_pkgs
salt \(aq*\(aq pkg.list_repo_pkgs foo bar baz
salt \(aq*\(aq pkg.list_repo_pkgs \(aqsamba4*\(aq fromrepo=base,updates
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.list_repos(basedir=\(aq/etc/yum.repos.d\(aq)
Lists all repos in <basedir> (default: /etc/yum.repos.d/).
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_repos
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.list_upgrades(refresh=True, **kwargs)
Check whether or not an upgrade is available for all packages
.sp
The \fBfromrepo\fP, \fBenablerepo\fP, and \fBdisablerepo\fP arguments are
supported, as used in pkg states, and the \fBdisableexcludes\fP option is
also supported.
.sp
New in version 2014.7.0: Support for the \fBdisableexcludes\fP option
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.mod_repo(repo, basedir=None, **kwargs)
Modify one or more values for a repo. If the repo does not exist, it will
be created, so long as the following values are specified:
.INDENT 7.0
.TP
.B repo
name by which the yum refers to the repo
.TP
.B name
a human\-readable name for the repo
.TP
.B baseurl
the URL for yum to reference
.TP
.B mirrorlist
the URL for yum to reference
.UNINDENT
.sp
Key/Value pairs may also be removed from a repo\(aqs configuration by setting
a key to a blank value. Bear in mind that a name cannot be deleted, and a
baseurl can only be deleted if a mirrorlist is specified (or vice versa).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.mod_repo reponame enabled=1 gpgcheck=1
salt \(aq*\(aq pkg.mod_repo reponame basedir=/path/to/dir enabled=1
salt \(aq*\(aq pkg.mod_repo reponame baseurl= mirrorlist=http://host.com/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.normalize_name(name)
Strips the architecture from the specified package name, if necessary.
Circumstances where this would be done include:
.INDENT 7.0
.IP \(bu 2
If the arch is 32 bit and the package name ends in a 32\-bit arch.
.IP \(bu 2
If the arch matches the OS arch, or is \fBnoarch\fP\&.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.normalize_name zsh.x86_64
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.owner(*paths)
New in version 2014.7.0.
.sp
Return the name of the package that owns the file. Multiple file paths can
be passed. Like \fBpkg.version <salt.modules.yumpkg.version\fP, if a
single path is passed, a string will be returned, and if multiple paths are
passed, a dictionary of file/package name pairs will be returned.
.sp
If the file is not owned by a package, or is not present on the minion,
then an empty string will be returned for that path.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt \(aq*\(aq pkg.owner /usr/bin/apachectl
salt \(aq*\(aq pkg.owner /usr/bin/apachectl /etc/httpd/conf/httpd.conf
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.purge(name=None, pkgs=None, **kwargs)
Package purges are not supported by yum, this function is identical to
\fI\%pkg.remove\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.refresh_db(**kwargs)
Check the yum repos for updated packages
.sp
Returns:
.INDENT 7.0
.IP \(bu 2
\fBTrue\fP: Updates are available
.IP \(bu 2
\fBFalse\fP: An error occurred
.IP \(bu 2
\fBNone\fP: No updates are available
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.remove(name=None, pkgs=None, **kwargs)
Remove packages with \fByum \-q \-y remove\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.unhold(name=None, pkgs=None, sources=None, **kwargs)
New in version 2014.7.0.
.sp
Hold packages with \fByum \-q versionlock\fP\&.
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to unhold. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.unhold <package name>
salt \(aq*\(aq pkg.unhold pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.upgrade(refresh=True, fromrepo=None, skip_verify=False, **kwargs)
Run a full system upgrade, a yum upgrade
.sp
Changed in version 2014.7.0.
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Repository Options:
.INDENT 7.0
.TP
.B fromrepo
Specify a package repository (or repositories) from which to install.
(e.g., \fByum \-\-disablerepo=\(aq*\(aq \-\-enablerepo=\(aqsomerepo\(aq\fP)
.TP
.B enablerepo (ignored if \fBfromrepo\fP is specified)
Specify a disabled package repository (or repositories) to enable.
(e.g., \fByum \-\-enablerepo=\(aqsomerepo\(aq\fP)
.TP
.B disablerepo (ignored if \fBfromrepo\fP is specified)
Specify an enabled package repository (or repositories) to disable.
(e.g., \fByum \-\-disablerepo=\(aqsomerepo\(aq\fP)
.TP
.B disableexcludes
Disable exclude from main, for a repo or for everything.
(e.g., \fByum \-\-disableexcludes=\(aqmain\(aq\fP)
.sp
New in version 2014.7.0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.upgrade_available(name)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.verify(*names, **kwargs)
New in version 2014.1.0.
.sp
Runs an rpm \-Va on a system, and returns the results in a dict
.sp
Files with an attribute of config, doc, ghost, license or readme in the
package header can be ignored using the \fBignore_types\fP keyword argument
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.verify
salt \(aq*\(aq pkg.verify httpd
salt \(aq*\(aq pkg.verify \(aqhttpd postfix\(aq
salt \(aq*\(aq pkg.verify \(aqhttpd postfix\(aq ignore_types=[\(aqconfig\(aq,\(aqdoc\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.yumpkg.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.zcbuildout
.SS Management of zc.buildout
.sp
New in version 2014.1.0.
.sp
This module is inspired by \fI\%minitage\(aqs buildout maker\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The zc.buildout integration is still in beta; the API is subject to change
.UNINDENT
.UNINDENT
.SS General notes
.sp
You have those following methods:
.INDENT 0.0
.IP \(bu 2
upgrade_bootstrap
.IP \(bu 2
bootstrap
.IP \(bu 2
run_buildout
.IP \(bu 2
buildout
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zcbuildout.bootstrap(*a, **kw)
Run the buildout bootstrap dance (python bootstrap.py).
.INDENT 7.0
.TP
.B directory
directory to execute in
.TP
.B config
alternative buildout configuration file to use
.TP
.B runas
User used to run buildout as
.TP
.B env
environment variables to set when running
.TP
.B buildout_ver
force a specific buildout version (1 | 2)
.TP
.B test_release
buildout accept test release
.TP
.B offline
are we executing buildout in offline mode
.TP
.B distribute
Forcing use of distribute
.TP
.B new_st
Forcing use of setuptools >= 0.7
.TP
.B python
path to a python executable to use in place of default (salt one)
.TP
.B onlyif
Only execute cmd if statement on the host return 0
.TP
.B unless
Do not execute cmd if statement on the host return 0
.TP
.B use_vt
Use the new salt VT to stream output [experimental]
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq buildout.bootstrap /srv/mybuildout
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zcbuildout.buildout(*a, **kw)
Run buildout in a directory.
.INDENT 7.0
.TP
.B directory
directory to execute in
.TP
.B config
buildout config to use
.TP
.B parts
specific buildout parts to run
.TP
.B runas
user used to run buildout as
.TP
.B env
environment variables to set when running
.TP
.B buildout_ver
force a specific buildout version (1 | 2)
.TP
.B test_release
buildout accept test release
.TP
.B new_st
Forcing use of setuptools >= 0.7
.TP
.B distribute
use distribute over setuptools if possible
.TP
.B offline
does buildout run offline
.TP
.B python
python to use
.TP
.B debug
run buildout with \-D debug flag
.TP
.B onlyif
Only execute cmd if statement on the host return 0
.TP
.B unless
Do not execute cmd if statement on the host return 0
.TP
.B newest
run buildout in newest mode
.TP
.B verbose
run buildout in verbose mode (\-vvvvv)
.TP
.B use_vt
Use the new salt VT to stream output [experimental]
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq buildout.buildout /srv/mybuildout
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zcbuildout.run_buildout(*a, **kw)
Run a buildout in a directory.
.INDENT 7.0
.TP
.B directory
directory to execute in
.TP
.B config
alternative buildout configuration file to use
.TP
.B offline
are we executing buildout in offline mode
.TP
.B runas
user used to run buildout as
.TP
.B env
environment variables to set when running
.TP
.B onlyif
Only execute cmd if statement on the host return 0
.TP
.B unless
Do not execute cmd if statement on the host return 0
.TP
.B newest
run buildout in newest mode
.TP
.B force
run buildout unconditionally
.TP
.B verbose
run buildout in verbose mode (\-vvvvv)
.TP
.B use_vt
Use the new salt VT to stream output [experimental]
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq buildout.run_buildout /srv/mybuildout
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zcbuildout.upgrade_bootstrap(*a, **kw)
Upgrade current bootstrap.py with the last released one.
.sp
Indeed, when we first run a buildout, a common source of problem
is to have a locally stale bootstrap, we just try to grab a new copy
.INDENT 7.0
.TP
.B directory
directory to execute in
.TP
.B offline
are we executing buildout in offline mode
.TP
.B buildout_ver
forcing to use a specific buildout version (1 | 2)
.TP
.B onlyif
Only execute cmd if statement on the host return 0
.TP
.B unless
Do not execute cmd if statement on the host return 0
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq buildout.upgrade_bootstrap /srv/mybuildout
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.zfs
.sp
Salt interface to ZFS commands
.SS salt.modules.znc
.sp
znc \- An advanced IRC bouncer
.sp
New in version 2014.7.0.
.sp
Provides an interface to basic ZNC functionality
.INDENT 0.0
.TP
.B salt.modules.znc.buildmod(*modules)
Build module using znc\-buildmod
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq znc.buildmod module.cpp [...]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.znc.dumpconf()
Write the active configuration state to config file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq znc.dumpconf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.znc.rehashconf()
Rehash the active configuration state from config file
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq znc.rehashconf
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.znc.version()
Return server version from znc \-\-version
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq znc.version
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.zpool
.sp
Module for running ZFS zpool command
.INDENT 0.0
.TP
.B salt.modules.zpool.add(pool_name, vdev)
Add the specified vdev to the given pool
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.add myzpool /path/to/vdev
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.create(pool_name, *vdevs)
Create a new storage pool
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.create myzpool /path/to/vdev1 [/path/to/vdev2] [...]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.create_file_vdev(size, *vdevs)
Creates file based \fBvirtual devices\fP for a zpool
.sp
\fB*vdevs\fP is a list of full paths for mkfile to create
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.create_file_vdev 7g /path/to/vdev1 [/path/to/vdev2] [...]
Depending on file size this may take a while to return
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.destroy(pool_name)
Destroys a storage pool
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.destroy myzpool
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.exists(pool_name)
Check if a ZFS storage pool is active
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.exists myzpool
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.iostat(name=\(aq\(aq)
Display I/O statistics for the given pools
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.iostat myzpool
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.replace(pool_name, old, new)
Replaces old device with new device.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.replace myzpool /path/to/vdev1 /path/to/vdev2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.scrub(pool_name=None)
Begin a scrub
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.scrub myzpool
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.status(name=\(aq\(aq)
Return the status of the named zpool
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.status myzpool
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zpool.zpool_list()
Return a list of all pools in the system with health status and space usage
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq zpool.zpool_list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.modules.zypper
.sp
Package support for openSUSE via the zypper package manager
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
\fBzypp\fP Python module. Install with \fBzypper install python\-zypp\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.del_repo(repo, **kwargs)
Delete a repo.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.del_repo alias
salt \(aq*\(aq pkg.del_repo alias
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.get_repo(repo, **kwargs)
Display a repo.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.get_repo alias
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs)
Install the passed package(s), add refresh=True to run \(aqzypper refresh\(aq
before package is installed.
.INDENT 7.0
.TP
.B name
The name of the package to be installed. Note that this parameter is
ignored if either "pkgs" or "sources" is passed. Additionally, please
note that this option can only be used to install packages from a
software repository. To install a package file manually, use the
"sources" option.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B refresh
Whether or not to refresh the package database before installing.
.TP
.B fromrepo
Specify a package repository to install from.
.TP
.B version
Can be either a version number, or the combination of a comparison
operator (<, >, <=, >=, =) and a version number (ex. \(aq>1.2.3\-4\(aq).
This parameter is ignored if "pkgs" or "sources" is passed.
.UNINDENT
.sp
Multiple Package Installation Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from a software repository. Must be
passed as a python list. A specific version number can be specified
by using a single\-element dict representing the package and its
version. As with the \fBversion\fP parameter above, comparison operators
can be used to target a specific version of a package.
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-4"}]\(aq
salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "<1.2.3\-4"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B sources
A list of RPM packages to install. Must be passed as a list of dicts,
with the keys being package names, and the values being the source URI
or local path to the package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.rpm"},{"bar": "salt://bar.rpm"}]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Returns a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.latest_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
If the latest version of a given package is already installed, an empty
string will be returned for that package.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.latest_version <package name>
salt \(aq*\(aq pkg.latest_version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed as a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package_name>\(aq: \(aq<version>\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.list_repos()
Lists all repos.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_repos
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.list_upgrades(refresh=True)
List all available package upgrades on this system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.list_upgrades
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.mod_repo(repo, **kwargs)
Modify one or more values for a repo. If the repo does not exist, it will
be created, so long as the following values are specified:
.INDENT 7.0
.TP
.B repo
alias by which the zypper refers to the repo
.TP
.B url or mirrorlist
the URL for zypper to reference
.UNINDENT
.sp
Key/Value pairs may also be removed from a repo\(aqs configuration by setting
a key to a blank value. Bear in mind that a name cannot be deleted, and a
url can only be deleted if a mirrorlist is specified (or vice versa).
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.mod_repo alias alias=new_alias
salt \(aq*\(aq pkg.mod_repo alias enabled=True
salt \(aq*\(aq pkg.mod_repo alias url= mirrorlist=http://host.com/
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.purge(name=None, pkgs=None, **kwargs)
Recursively remove a package and all dependencies which were installed
with it, this will call a \fBzypper \-n remove \-u\fP
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.purge <package name>
salt \(aq*\(aq pkg.purge <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.refresh_db()
Just run a \fBzypper refresh\fP, return a dict:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<database name>\(aq: Bool}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.refresh_db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.remove(name=None, pkgs=None, **kwargs)
Remove packages with \fBzypper \-n remove\fP
.INDENT 7.0
.TP
.B name
The name of the package to be deleted.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to delete. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.sp
Returns a dict containing the changes.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.remove <package name>
salt \(aq*\(aq pkg.remove <package1>,<package2>,<package3>
salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.upgrade(refresh=True)
Run a full system upgrade, a zypper upgrade
.sp
Return a dict containing the new package names and versions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq,
\(aqnew\(aq: \(aq<new\-version>\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.upgrade_available(name)
Check whether or not an upgrade is available for a given package
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.upgrade_available <package name>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.zypper.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
name/version pairs is returned.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq pkg.version <package name>
salt \(aq*\(aq pkg.version <package1> <package2> <package3> ...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Full list of netapi modules
.SS rest_cherrypy
.SS A REST API for Salt
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
CherryPy Python module (strongly recommend 3.2.x versions due to
.UNINDENT
.sp
an as yet unknown SSL error).
.TP
.B optdepends
.INDENT 7.0
.IP \(bu 2
ws4py Python module for websockets support.
.UNINDENT
.TP
.B configuration
All authentication is done through Salt\(aqs \fIexternal auth\fP system which requires additional configuration not described
here.
.sp
Example production\-ready configuration; add to the Salt master config file
and restart the \fBsalt\-master\fP and \fBsalt\-api\fP daemons:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
rest_cherrypy:
port: 8000
ssl_crt: /etc/pki/tls/certs/localhost.crt
ssl_key: /etc/pki/tls/certs/localhost.key
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using only a secure HTTPS connection is strongly recommended since Salt
authentication credentials will be sent over the wire.
.sp
A self\-signed certificate can be generated using the
\fBcreate_self_signed_cert()\fP execution function.
Running this function requires pyOpenSSL and the \fBsalt\-call\fP script is
available in the \fBsalt\-minion\fP package.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call \-\-local tls.create_self_signed_cert
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All available configuration options are detailed below. These settings
configure the CherryPy HTTP server and do not apply when using an external
server such as Apache or Nginx.
.INDENT 7.0
.TP
.B port
\fBRequired\fP
.sp
The port for the webserver to listen on.
.TP
.B host
\fB0.0.0.0\fP
The socket interface for the HTTP server to listen on.
.TP
.B debug
\fBFalse\fP
Starts the web server in development mode. It will reload itself when
the underlying code is changed and will output more debugging info.
.TP
.B ssl_crt
The path to a SSL certificate. (See below)
.TP
.B ssl_key
The path to the private key for your SSL certificate. (See below)
.TP
.B disable_ssl
A flag to disable SSL. Warning: your Salt authentication credentials
will be sent in the clear!
.TP
.B webhook_disable_auth
False
The \fI\%Webhook\fP URL requires authentication by default but
external services cannot always be configured to send authentication.
See the Webhook documentation for suggestions on securing this
interface.
.TP
.B webhook_url
/hook
Configure the URL endpoint for the \fI\%Webhook\fP entry point.
.TP
.B thread_pool
\fB100\fP
The number of worker threads to start up in the pool.
.TP
.B socket_queue_size
\fB30\fP
Specify the maximum number of HTTP connections to queue.
.TP
.B expire_responses
True
Whether to check for and kill HTTP responses that have exceeded the
default timeout.
.TP
.B max_request_body_size
\fB1048576\fP
Maximum size for the HTTP request body.
.TP
.B collect_stats
False
Collect and report statistics about the CherryPy server
.sp
Reports are available via the \fI\%Stats\fP URL.
.TP
.B static
A filesystem path to static HTML/JavaScript/CSS/image assets.
.TP
.B static_path
\fB/static\fP
The URL prefix to use when serving static assets out of the directory
specified in the \fBstatic\fP setting.
.TP
.B app
A filesystem path to an HTML file that will be served as a static file.
This is useful for bootstrapping a single\-page JavaScript app.
.TP
.B app_path
\fB/app\fP
The URL prefix to use for serving the HTML file specified in the \fBapp\fP
setting. This should be a simple name containing no slashes.
.sp
Any path information after the specified path is ignored; this is
useful for apps that utilize the HTML5 history API.
.TP
.B root_prefix
\fB/\fP
A URL path to the main entry point for the application. This is useful
for serving multiple applications from the same URL.
.UNINDENT
.UNINDENT
.SS Authentication
.sp
Authentication is performed by passing a session token with each request.
Tokens are generated via the \fI\%Login\fP URL.
.sp
The token may be sent in one of two ways:
.INDENT 0.0
.IP \(bu 2
Include a custom header named \fIX\-Auth\-Token\fP\&.
.sp
For example, using curl:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-sSk https://localhost:8000/login \-H \(aqAccept: application/x\-yaml\(aq \-d username=saltdev \-d password=saltdev \-d eauth=auto
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Copy the \fBtoken\fP value from the output and include it in subsequent
requests:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
curl \-sSk \fI\%https://localhost:8000\fP \-H \(aqAccept: application/x\-yaml\(aq \-H \(aqX\-Auth\-Token: 697adbdc8fe971d09ae4c2a3add7248859c87079\(aq \-d client=local \-d tgt=\(aq*\(aq \-d fun=test.ping
.IP \(bu 2
Sent via a cookie. This option is a convenience for HTTP clients that
automatically handle cookie support (such as browsers).
.sp
For example, using curl:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
# Write the cookie file:
curl \-sSk https://localhost:8000/login \-c ~/cookies.txt \-H \(aqAccept: application/x\-yaml\(aq \-d username=saltdev \-d password=saltdev \-d eauth=auto
# Read the cookie file:
curl \-sSk https://localhost:8000 \-b ~/cookies.txt \-H \(aqAccept: application/x\-yaml\(aq \-d client=local \-d tgt=\(aq*\(aq \-d fun=test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
You can bypass the session handling via the \fI\%Run\fP URL.
.UNINDENT
.UNINDENT
.SS Usage
.sp
Commands are sent to a running Salt master via this module by sending HTTP
requests to the URLs detailed below.
.INDENT 0.0
.INDENT 3.5
.IP "Content negotiation"
.sp
This REST interface is flexible in what data formats it will accept as well
as what formats it will return (e.g., JSON, YAML, x\-www\-form\-urlencoded).
.INDENT 0.0
.IP \(bu 2
Specify the format of data in the request body by including the
\fIContent\-Type\fP header.
.IP \(bu 2
Specify the desired data format for the response body with the
\fIAccept\fP header.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Data sent in \fI\%POST\fP and \fI\%PUT\fP requests must be in
the format of a list of lowstate dictionaries. This allows multiple commands to
be executed in a single HTTP request. The order of commands in the request
corresponds to the return for each command in the response.
.sp
Lowstate, broadly, is a dictionary of values that are mapped to a function
call. This pattern is used pervasively throughout Salt. The functions called
from netapi modules are described in \fIClient Interfaces\fP\&.
.sp
The following example (in JSON format) causes Salt to execute two commands, a
command sent to minions as well as a runner function on the master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[{
"client": "local",
"tgt": "*",
"fun": "test.fib",
"arg": ["10"]
},
{
"client": "runner",
"fun": "jobs.lookup_jid",
"jid": "20130603122505459265"
}]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "x\-www\-form\-urlencoded"
.sp
Sending JSON or YAML in the request body is simple and most flexible,
however sending data in urlencoded format is also supported with the
caveats below. It is the default format for HTML forms, many JavaScript
libraries, and the \fBcurl\fP command.
.sp
For example, the equivalent to running \fBsalt \(aq*\(aq test.ping\fP is sending
\fBfun=test.ping&arg&client=local&tgt=*\fP in the HTTP request body.
.sp
Caveats:
.INDENT 0.0
.IP \(bu 2
Only a single command may be sent per HTTP request.
.IP \(bu 2
Repeating the \fBarg\fP parameter multiple times will cause those
parameters to be combined into a single list.
.sp
Note, some popular frameworks and languages (notably jQuery, PHP, and
Ruby on Rails) will automatically append empty brackets onto repeated
parameters. E.g., \fBarg=one\fP, \fBarg=two\fP will be sent as \fBarg[]=one\fP,
\fBarg[]=two\fP\&. This is not supported; send JSON or YAML instead.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Deployment
.sp
The \fBrest_cherrypy\fP netapi module is a standard Python WSGI app. It can be
deployed one of two ways.
.SS \fBsalt\-api\fP using the CherryPy server
.sp
The default configuration is to run this module using \fBsalt\-api\fP to
start the Python\-based CherryPy server. This server is lightweight,
multi\-threaded, encrypted with SSL, and should be considered production\-ready.
.SS Using a WSGI\-compliant web server
.sp
This module may be deployed on any WSGI\-compliant server such as Apache with
mod_wsgi or Nginx with FastCGI, to name just two (there are many).
.sp
Note, external WSGI servers handle URLs, paths, and SSL certs directly. The
\fBrest_cherrypy\fP configuration options are ignored and the \fBsalt\-api\fP daemon
does not need to be running at all. Remember Salt authentication credentials
are sent in the clear unless SSL is being enforced!
.sp
An example Apache virtual host configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<VirtualHost *:80>
ServerName example.com
ServerAlias *.example.com
ServerAdmin webmaster@example.com
LogLevel warn
ErrorLog /var/www/example.com/logs/error.log
CustomLog /var/www/example.com/logs/access.log combined
DocumentRoot /var/www/example.com/htdocs
WSGIScriptAlias / /path/to/salt/netapi/rest_cherrypy/wsgi.py
</VirtualHost>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS REST URI Reference
.INDENT 0.0
.IP \(bu 2
\fI\%/\fP
.IP \(bu 2
\fI\%/login\fP
.IP \(bu 2
\fI\%/logout\fP
.IP \(bu 2
\fI\%/minions\fP
.IP \(bu 2
\fI\%/jobs\fP
.IP \(bu 2
\fI\%/run\fP
.IP \(bu 2
\fI\%/events\fP
.IP \(bu 2
\fI\%/hook\fP
.IP \(bu 2
\fI\%/key\fP
.IP \(bu 2
\fI\%/ws\fP
.IP \(bu 2
\fI\%/stats\fP
.UNINDENT
.SS \fB/\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.LowDataAdapter
The primary entry point to Salt\(aqs REST API
.INDENT 7.0
.TP
.B GET()
An explanation of the API with links of where to go next
.INDENT 7.0
.TP
.B GET /
.INDENT 7.0
.TP
.B Request Headers
.INDENT 7.0
.IP \(bu 2
\fBAccept\fP \-\- the desired response format.
.UNINDENT
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-i localhost:8000
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET / HTTP/1.1
Host: localhost:8000
Accept: application/json
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Type: application/json
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B POST
Mock out specified imports
.sp
This allows autodoc to do its thing without having oodles of req\(aqd
installed libs. This doesn\(aqt work with \fBimport *\fP imports.
.sp
\fI\%http://read\-the\-docs.readthedocs.org/en/latest/faq.html#i\-get\-import\-errors\-on\-libraries\-that\-depend\-on\-c\-modules\fP
.UNINDENT
.UNINDENT
.SS \fB/login\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Login(*args, **kwargs)
Log in to receive a session token
.sp
\fI\%Authentication information\fP\&.
.INDENT 7.0
.TP
.B GET()
Present the login interface
.INDENT 7.0
.TP
.B GET /login
An explanation of how to log in.
.INDENT 7.0
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-i localhost:8000/login
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /login HTTP/1.1
Host: localhost:8000
Accept: text/html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Type: text/html
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B POST(**kwargs)
\fI\%Authenticate\fP against Salt\(aqs eauth system
.INDENT 7.0
.TP
.B POST /login
.INDENT 7.0
.TP
.B Request Headers
.INDENT 7.0
.IP \(bu 2
\fBX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&.
.IP \(bu 2
\fBAccept\fP \-\- the desired response format.
.IP \(bu 2
\fBContent\-Type\fP \-\- the format of the request body.
.UNINDENT
.TP
.B Form Parameters
.INDENT 7.0
.IP \(bu 2
\fBeauth\fP \-\- the eauth backend configured for the user
.IP \(bu 2
\fBusername\fP \-\- username
.IP \(bu 2
\fBpassword\fP \-\- password
.UNINDENT
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-si localhost:8000/login \e
\-H "Accept: application/json" \e
\-d username=\(aqsaltuser\(aq \e
\-d password=\(aqsaltpass\(aq \e
\-d eauth=\(aqpam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
POST / HTTP/1.1
Host: localhost:8000
Content\-Length: 42
Content\-Type: application/x\-www\-form\-urlencoded
Accept: application/json
username=saltuser&password=saltpass&eauth=pam
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Type: application/json
Content\-Length: 206
X\-Auth\-Token: 6d1b722e
Set\-Cookie: session_id=6d1b722e; expires=Sat, 17 Nov 2012 03:23:52 GMT; Path=/
{"return": {
"token": "6d1b722e",
"start": 1363805943.776223,
"expire": 1363849143.776224,
"user": "saltuser",
"eauth": "pam",
"perms": [
"grains.*",
"status.*",
"sys.*",
"test.*"
]
}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fB/logout\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Logout
Class to remove or invalidate sessions
.INDENT 7.0
.TP
.B POST()
Destroy the currently active session and expire the session cookie
.UNINDENT
.UNINDENT
.SS \fB/minions\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Minions
Convenience URLs for working with minions
.INDENT 7.0
.TP
.B GET(mid=None)
A convenience URL for getting lists of minions or getting minion
details
.INDENT 7.0
.TP
.B GET /minions/(mid)
.INDENT 7.0
.TP
.B Request Headers
.INDENT 7.0
.IP \(bu 2
\fBX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&.
.IP \(bu 2
\fBAccept\fP \-\- the desired response format.
.UNINDENT
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-i localhost:8000/minions/ms\-3
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /minions/ms\-3 HTTP/1.1
Host: localhost:8000
Accept: application/x\-yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 129005
Content\-Type: application/x\-yaml
return:
\- ms\-3:
grains.items:
...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B POST(**kwargs)
Start an execution command and immediately return the job id
.INDENT 7.0
.TP
.B POST /minions
.INDENT 7.0
.TP
.B Request Headers
.INDENT 7.0
.IP \(bu 2
\fBX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&.
.IP \(bu 2
\fBAccept\fP \-\- the desired response format.
.IP \(bu 2
\fBContent\-Type\fP \-\- the format of the request body.
.UNINDENT
.TP
.B Response Headers
.INDENT 7.0
.IP \(bu 2
\fBContent\-Type\fP \-\- the format of the response body; depends on the
\fIAccept\fP request header.
.UNINDENT
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.sp
\fIlowstate\fP data describing Salt commands must be sent in the
request body. The \fBclient\fP option will be set to
\fBlocal_async()\fP\&.
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-sSi localhost:8000/minions \e
\-H "Accept: application/x\-yaml" \e
\-d tgt=\(aq*\(aq \e
\-d fun=\(aqstatus.diskusage\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
POST /minions HTTP/1.1
Host: localhost:8000
Accept: application/x\-yaml
Content\-Length: 26
Content\-Type: application/x\-www\-form\-urlencoded
tgt=*&fun=status.diskusage
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 202 Accepted
Content\-Length: 86
Content\-Type: application/x\-yaml
return:
\- jid: \(aq20130603122505459265\(aq
minions: [ms\-4, ms\-3, ms\-2, ms\-1, ms\-0]
_links:
jobs:
\- href: /jobs/20130603122505459265
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fB/jobs\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Jobs
.INDENT 7.0
.TP
.B GET(jid=None)
A convenience URL for getting lists of previously run jobs or getting
the return from a single job
.INDENT 7.0
.TP
.B GET /jobs/(jid)
List jobs or show a single job from the job cache.
.INDENT 7.0
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-i localhost:8000/jobs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /jobs HTTP/1.1
Host: localhost:8000
Accept: application/x\-yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 165
Content\-Type: application/x\-yaml
return:
\- \(aq20121130104633606931\(aq:
Arguments:
\- \(aq3\(aq
Function: test.fib
Start Time: 2012, Nov 30 10:46:33.606931
Target: jerry
Target\-type: glob
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-i localhost:8000/jobs/20121130104633606931
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /jobs/20121130104633606931 HTTP/1.1
Host: localhost:8000
Accept: application/x\-yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 73
Content\-Type: application/x\-yaml
info:
\- Arguments:
\- \(aq3\(aq
Function: test.fib
Minions:
\- jerry
Start Time: 2012, Nov 30 10:46:33.606931
Target: \(aq*\(aq
Target\-type: glob
User: saltdev
jid: \(aq20121130104633606931\(aq
return:
\- jerry:
\- \- 0
\- 1
\- 1
\- 2
\- 6.9141387939453125e\-06
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fB/run\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Run
Class to run commands without normal session handling
.INDENT 7.0
.TP
.B POST(**kwargs)
Run commands bypassing the \fI\%normal session handling\fP
.INDENT 7.0
.TP
.B POST /run
This entry point is primarily for "one\-off" commands. Each request
must pass full Salt authentication credentials. Otherwise this URL
is identical to the \fI\%root URL (/)\fP\&.
.sp
\fIlowstate\fP data describing Salt commands must be sent in the
request body.
.INDENT 7.0
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-sS localhost:8000/run \e
\-H \(aqAccept: application/x\-yaml\(aq \e
\-d client=\(aqlocal\(aq \e
\-d tgt=\(aq*\(aq \e
\-d fun=\(aqtest.ping\(aq \e
\-d username=\(aqsaltdev\(aq \e
\-d password=\(aqsaltdev\(aq \e
\-d eauth=\(aqpam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
POST /run HTTP/1.1
Host: localhost:8000
Accept: application/x\-yaml
Content\-Length: 75
Content\-Type: application/x\-www\-form\-urlencoded
client=local&tgt=*&fun=test.ping&username=saltdev&password=saltdev&eauth=pam
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 73
Content\-Type: application/x\-yaml
return:
\- ms\-0: true
ms\-1: true
ms\-2: true
ms\-3: true
ms\-4: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fB/events\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Events
Expose the Salt event bus
.sp
The event bus on the Salt master exposes a large variety of things, notably
when executions are started on the master and also when minions ultimately
return their results. This URL provides a real\-time window into a running
Salt infrastructure.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIevents\fP
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B GET(token=None)
An HTTP stream of the Salt master event bus
.sp
This stream is formatted per the Server Sent Events (SSE) spec. Each
event is formatted as JSON.
.INDENT 7.0
.TP
.B GET /events
.INDENT 7.0
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-NsS localhost:8000/events
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /events HTTP/1.1
Host: localhost:8000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.sp
Note, the \fBtag\fP field is not part of the spec. SSE compliant clients
should ignore unknown fields. This addition allows non\-compliant
clients to only watch for certain tags without having to deserialze the
JSON object each time.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Connection: keep\-alive
Cache\-Control: no\-cache
Content\-Type: text/event\-stream;charset=utf\-8
retry: 400
tag: salt/job/20130802115730568475/new
data: {\(aqtag\(aq: \(aqsalt/job/20130802115730568475/new\(aq, \(aqdata\(aq: {\(aqminions\(aq: [\(aqms\-4\(aq, \(aqms\-3\(aq, \(aqms\-2\(aq, \(aqms\-1\(aq, \(aqms\-0\(aq]}}
tag: salt/job/20130802115730568475/ret/jerry
data: {\(aqtag\(aq: \(aqsalt/job/20130802115730568475/ret/jerry\(aq, \(aqdata\(aq: {\(aqjid\(aq: \(aq20130802115730568475\(aq, \(aqreturn\(aq: True, \(aqretcode\(aq: 0, \(aqsuccess\(aq: True, \(aqcmd\(aq: \(aq_return\(aq, \(aqfun\(aq: \(aqtest.ping\(aq, \(aqid\(aq: \(aqms\-1\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The event stream can be easily consumed via JavaScript:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Note, you must be authenticated!
var source = new EventSource(\(aq/events\(aq);
source.onopen = function() { console.debug(\(aqopening\(aq) };
source.onerror = function(e) { console.debug(\(aqerror!\(aq, e) };
source.onmessage = function(e) {
console.debug(\(aqTag: \(aq, e.data.tag)
console.debug(\(aqData: \(aq, e.data.data)
};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or using CORS:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var source = new EventSource(\(aq/events\(aq, {withCredentials: true});
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Some browser clients lack CORS support for the \fBEventSource()\fP API. Such
clients may instead pass the \fIX\-Auth\-Token\fP value as an URL
parameter:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-NsS localhost:8000/events/6d1b722e
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is also possible to consume the stream via the shell.
.sp
Records are separated by blank lines; the \fBdata:\fP and \fBtag:\fP
prefixes will need to be removed manually before attempting to
unserialize the JSON.
.sp
curl\(aqs \fB\-N\fP flag turns off input buffering which is required to
process the stream incrementally.
.sp
Here is a basic example of printing each event as it comes in:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-NsS localhost:8000/events |\e
while IFS= read \-r line ; do
echo $line
done
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here is an example of using awk to filter events based on tag:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-NsS localhost:8000/events |\e
awk \(aq
BEGIN { RS=""; FS="\e\en" }
$1 ~ /^tag: salt\e/job\e/[0\-9]+\e/new$/ { print $0 }
\(aq
tag: salt/job/20140112010149808995/new
data: {"tag": "salt/job/20140112010149808995/new", "data": {"tgt_type": "glob", "jid": "20140112010149808995", "tgt": "jerry", "_stamp": "2014\-01\-12_01:01:49.809617", "user": "shouse", "arg": [], "fun": "test.ping", "minions": ["jerry"]}}
tag: 20140112010149808995
data: {"tag": "20140112010149808995", "data": {"fun_args": [], "jid": "20140112010149808995", "return": true, "retcode": 0, "success": true, "cmd": "_return", "_stamp": "2014\-01\-12_01:01:49.819316", "fun": "test.ping", "id": "jerry"}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fB/hook\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Webhook
A generic web hook entry point that fires an event on Salt\(aqs event bus
.sp
External services can POST data to this URL to trigger an event in Salt.
For example, Amazon SNS, Jenkins\-CI or Travis\-CI, or GitHub web hooks.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Be mindful of security
.sp
Salt\(aqs Reactor can run any code. A Reactor SLS that responds to a hook
event is responsible for validating that the event came from a trusted
source and contains valid data.
.sp
\fBThis is a generic interface and securing it is up to you!\fP
.sp
This URL requires authentication however not all external services can
be configured to authenticate. For this reason authentication can be
selectively disabled for this URL. Follow best practices \-\- always use
SSL, pass a secret key, configure the firewall to only allow traffic
from a known source, etc.
.UNINDENT
.UNINDENT
.sp
The event data is taken from the request body. The
\fIContent\-Type\fP header is respected for the payload.
.sp
The event tag is prefixed with \fBsalt/netapi/hook\fP and the URL path is
appended to the end. For example, a \fBPOST\fP request sent to
\fB/hook/mycompany/myapp/mydata\fP will produce a Salt event with the tag
\fBsalt/netapi/hook/mycompany/myapp/mydata\fP\&.
.sp
The following is an example \fB\&.travis.yml\fP file to send notifications to
Salt of successful test runs:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
language: python
script: python \-m unittest tests
after_success:
\- |
curl \-sSk https://saltapi\-url.example.com:8000/hook/travis/build/success \-d branch="${TRAVIS_BRANCH}" \-d commit="${TRAVIS_COMMIT}"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIevents\fP, \fIreactor\fP
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B POST(*args, **kwargs)
Fire an event in Salt with a custom event tag and data
.INDENT 7.0
.TP
.B POST /hook
.INDENT 7.0
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.IP \(bu 2
\fB413\fP \-\- request body is too large
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-sS localhost:8000/hook \-d foo=\(aqFoo!\(aq \-d bar=\(aqBar!\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
POST /hook HTTP/1.1
Host: localhost:8000
Content\-Length: 16
Content\-Type: application/x\-www\-form\-urlencoded
foo=Foo&bar=Bar!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 14
Content\-Type: application/json
{"success": true}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As a practical example, an internal continuous\-integration build
server could send an HTTP POST request to the URL
\fBhttps://localhost:8000/hook/mycompany/build/success\fP which contains
the result of a build and the SHA of the version that was built as
JSON. That would then produce the following event in Salt that could be
used to kick off a deployment via Salt\(aqs Reactor:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
Event fired at Fri Feb 14 17:40:11 2014
*************************
Tag: salt/netapi/hook/mycompany/build/success
Data:
{\(aq_stamp\(aq: \(aq2014\-02\-14_17:40:11.440996\(aq,
\(aqheaders\(aq: {
\(aqX\-My\-Secret\-Key\(aq: \(aqF0fAgoQjIT@W\(aq,
\(aqContent\-Length\(aq: \(aq37\(aq,
\(aqContent\-Type\(aq: \(aqapplication/json\(aq,
\(aqHost\(aq: \(aqlocalhost:8000\(aq,
\(aqRemote\-Addr\(aq: \(aq127.0.0.1\(aq},
\(aqpost\(aq: {\(aqrevision\(aq: \(aqaa22a3c4b2e7\(aq, \(aqresult\(aq: True}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt\(aqs Reactor could listen for the event:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
reactor:
\- \(aqsalt/netapi/hook/mycompany/build/*\(aq:
\- /srv/reactor/react_ci_builds.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And finally deploy the new build:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% set secret_key = data.get(\(aqheaders\(aq, {}).get(\(aqX\-My\-Secret\-Key\(aq) %}
{% set build = data.get(\(aqpost\(aq, {}) %}
{% if secret_key == \(aqF0fAgoQjIT@W\(aq and build.result == True %}
deploy_my_app:
cmd.state.sls:
\- tgt: \(aqapplication*\(aq
\- arg:
\- myapp.deploy
\- kwarg:
pillar:
revision: {{ revision }}
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fB/key\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Keys
Convenience URLs for working with minion keys
.sp
New in version 2014.7.0.
.sp
These URLs wrap the functionality provided by the \fBkey wheel
module\fP functions.
.INDENT 7.0
.TP
.B GET(mid=None)
Show the list of minion keys or detail on a specific key
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B GET /keys/(mid)
List all keys or show a specific key
.INDENT 7.0
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-i localhost:8000/keys
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /keys HTTP/1.1
Host: localhost:8000
Accept: application/x\-yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 165
Content\-Type: application/x\-yaml
return:
local:
\- master.pem
\- master.pub
minions:
\- jerry
minions_pre: []
minions_rejected: []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-i localhost:8000/keys/jerry
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /keys/jerry HTTP/1.1
Host: localhost:8000
Accept: application/x\-yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 73
Content\-Type: application/x\-yaml
return:
minions:
jerry: 51:93:b3:d0:9f:3a:6d:e5:28:67:c2:4b:27:d6:cd:2b
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B POST(mid, keysize=None, force=None, **kwargs)
Easily generate keys for a minion and auto\-accept the new key
.sp
New in version 2014.7.0.
.sp
Example partial kickstart script to bootstrap a new minion:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
%post
mkdir \-p /etc/salt/pki/minion
curl \-sSk https://localhost:8000/keys \e
\-d mid=jerry \e
\-d username=kickstart \e
\-d password=kickstart \e
\-d eauth=pam \e
| tar \-C /etc/salt/pki/minion \-xf \-
mkdir \-p /etc/salt/minion.d
printf \(aqmaster: 10.0.0.5\enid: jerry\(aq > /etc/salt/minion.d/id.conf
%end
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B POST /keys
Generate a public and private key and return both as a tarball
.sp
Authentication credentials must be passed in the request.
.INDENT 7.0
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-sSk https://localhost:8000/keys \e
\-d mid=jerry \e
\-d username=kickstart \e
\-d password=kickstart \e
\-d eauth=pam \e
\-o jerry\-salt\-keys.tar
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
POST /keys HTTP/1.1
Host: localhost:8000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response:\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 OK
Content\-Length: 10240
Content\-Disposition: attachment; filename="saltkeys\-jerry.tar"
Content\-Type: application/x\-tar
jerry.pub0000644000000000000000000000070300000000000010730 0ustar 00000000000000
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS \fB/ws\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.WebsocketEndpoint
Open a WebSocket connection to Salt\(aqs event bus
.sp
The event bus on the Salt master exposes a large variety of things, notably
when executions are started on the master and also when minions ultimately
return their results. This URL provides a real\-time window into a running
Salt infrastructure. Uses websocket as the transport mechanism.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
\fIevents\fP
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B GET(token=None, **kwargs)
Return a websocket connection of Salt\(aqs event stream
.INDENT 7.0
.TP
.B GET /ws/(token)
.INDENT 7.0
.TP
.B Query Parameters
.INDENT 7.0
.IP \(bu 2
\fBformat_events\fP \-\-
.sp
The event stream will undergo server\-side
formatting if the \fBformat_events\fP URL parameter is included
in the request. This can be useful to avoid formatting on the
client\-side:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-NsS <...snip...> localhost:8000/ws?format_events
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B Request Headers
.INDENT 7.0
.IP \(bu 2
\fBX\-Auth\-Token\fP \-\- an authentication token from
\fI\%Login\fP\&.
.UNINDENT
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB101\fP \-\- switching to the websockets protocol
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBExample request:\fP
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B curl \-NsSk
\-H \(aqX\-Auth\-Token: ffedf49d\(aq \-H \(aqHost: localhost:8000\(aq \-H \(aqConnection: Upgrade\(aq \-H \(aqUpgrade: websocket\(aq \-H \(aqOrigin: https://localhost:8000\(aq \-H \(aqSec\-WebSocket\-Version: 13\(aq \-H \(aqSec\-WebSocket\-Key: \(aq"$(echo \-n $RANDOM | base64)" localhost:8000/ws
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
GET /ws HTTP/1.1
Connection: Upgrade
Upgrade: websocket
Host: localhost:8000
Origin: https://localhost:8000
Sec\-WebSocket\-Version: 13
Sec\-WebSocket\-Key: s65VsgHigh7v/Jcf4nXHnA==
X\-Auth\-Token: ffedf49d
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec\-WebSocket\-Accept: mWZjBV9FCglzn1rIKJAxrTFlnJE=
Sec\-WebSocket\-Version: 13
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
An authentication token \fBmay optionally\fP be passed as part of the URL
for browsers that cannot be configured to send the authentication
header or cookie:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-NsS <...snip...> localhost:8000/ws/ffedf49d
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The event stream can be easily consumed via JavaScript:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
// Note, you must be authenticated!
var source = new Websocket(\(aqws://localhost:8000/ws/d0ce6c1a\(aq);
source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); };
source.onmessage = function(e) { console.debug(e.data); };
source.send(\(aqwebsocket client ready\(aq)
source.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or via Python, using the Python module \fI\%websocket\-client\fP for example.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Note, you must be authenticated!
from websocket import create_connection
ws = create_connection(\(aqws://localhost:8000/ws/d0ce6c1a\(aq)
ws.send(\(aqwebsocket client ready\(aq)
# Look at https://pypi.python.org/pypi/websocket\-client/ for more
# examples.
while listening_to_events:
print ws.recv()
ws.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Above examples show how to establish a websocket connection to Salt and
activating real time updates from Salt\(aqs event stream by signaling
\fBwebsocket client ready\fP\&.
.UNINDENT
.UNINDENT
.SS \fB/stats\fP
.INDENT 0.0
.TP
.B class salt.netapi.rest_cherrypy.app.Stats
Expose statistics on the running CherryPy server
.INDENT 7.0
.TP
.B GET()
Return a dump of statistics collected from the CherryPy server
.INDENT 7.0
.TP
.B GET /stats
.INDENT 7.0
.TP
.B Request Headers
.INDENT 7.0
.IP \(bu 2
\fBX\-Auth\-Token\fP \-\- a session token from \fI\%Login\fP\&.
.IP \(bu 2
\fBAccept\fP \-\- the desired response format.
.UNINDENT
.TP
.B Response Headers
.INDENT 7.0
.IP \(bu 2
\fBContent\-Type\fP \-\- the format of the response body; depends on the
\fIAccept\fP request header.
.UNINDENT
.TP
.B Status Codes
.INDENT 7.0
.IP \(bu 2
\fB200\fP \-\- success
.IP \(bu 2
\fB401\fP \-\- authentication required
.IP \(bu 2
\fB406\fP \-\- requested Content\-Type not available
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS rest_tornado
.SS A non\-blocking REST API for Salt
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
tornado Python module
.UNINDENT
.TP
.B configuration
All authentication is done through Salt\(aqs \fIexternal auth\fP system which requires additional configuration not described
here.
.UNINDENT
.sp
In order to run rest_tornado with the salt\-master
add the following to the Salt master config file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rest_tornado:
# can be any port
port: 8000
ssl_crt: /etc/pki/api/certs/server.crt
# no need to specify ssl_key if cert and key
# are in one single file
ssl_key: /etc/pki/api/certs/server.key
debug: False
disable_ssl: False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Authentication
.sp
Authentication is performed by passing a session token with each request.
Tokens are generated via the \fI\%SaltAuthHandler\fP URL.
.sp
The token may be sent in one of two ways:
.INDENT 0.0
.IP \(bu 2
Include a custom header named \fIX\-Auth\-Token\fP\&.
.IP \(bu 2
Sent via a cookie. This option is a convenience for HTTP clients that
automatically handle cookie support (such as browsers).
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
You can bypass the session handling via the \fI\%RunSaltAPIHandler\fP URL.
.UNINDENT
.UNINDENT
.SS Usage
.sp
Commands are sent to a running Salt master via this module by sending HTTP
requests to the URLs detailed below.
.INDENT 0.0
.INDENT 3.5
.IP "Content negotiation"
.sp
This REST interface is flexible in what data formats it will accept as well
as what formats it will return (e.g., JSON, YAML, x\-www\-form\-urlencoded).
.INDENT 0.0
.IP \(bu 2
Specify the format of data in the request body by including the
\fIContent\-Type\fP header.
.IP \(bu 2
Specify the desired data format for the response body with the
\fIAccept\fP header.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Data sent in \fI\%POST\fP and \fI\%PUT\fP requests must be in
the format of a list of lowstate dictionaries. This allows multiple commands to
be executed in a single HTTP request.
.INDENT 0.0
.TP
.B lowstate
A dictionary containing various keys that instruct Salt which command
to run, where that command lives, any parameters for that command, any
authentication credentials, what returner to use, etc.
.sp
Salt uses the lowstate data format internally in many places to pass
command data between functions. Salt also uses lowstate for the
\fILocalClient()\fP Python API interface.
.UNINDENT
.sp
The following example (in JSON format) causes Salt to execute two commands:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[{
"client": "local",
"tgt": "*",
"fun": "test.fib",
"arg": ["10"]
},
{
"client": "runner",
"fun": "jobs.lookup_jid",
"jid": "20130603122505459265"
}]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple commands in a Salt API request will be executed in serial and makes
no gaurantees that all commands will run. Meaning that if test.fib (from the
example above) had an exception, the API would still execute "jobs.lookup_jid".
.sp
Responses to these lowstates are an in\-order list of dicts containing the
return data, a yaml response could look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- ms\-1: true
ms\-2: true
\- ms\-1: foo
ms\-2: bar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the event of an exception while executing a command the return for that lowstate
will be a string, for example if no minions matched the first lowstate we would get
a return like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- No minions matched the target. No command was sent, no jid was assigned.
\- ms\-1: true
ms\-2: true
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.IP "x\-www\-form\-urlencoded"
.sp
Sending JSON or YAML in the request body is simple and most flexible,
however sending data in urlencoded format is also supported with the
caveats below. It is the default format for HTML forms, many JavaScript
libraries, and the \fBcurl\fP command.
.sp
For example, the equivalent to running \fBsalt \(aq*\(aq test.ping\fP is sending
\fBfun=test.ping&arg&client=local&tgt=*\fP in the HTTP request body.
.sp
Caveats:
.INDENT 0.0
.IP \(bu 2
Only a single command may be sent per HTTP request.
.IP \(bu 2
Repeating the \fBarg\fP parameter multiple times will cause those
parameters to be combined into a single list.
.sp
Note, some popular frameworks and languages (notably jQuery, PHP, and
Ruby on Rails) will automatically append empty brackets onto repeated
parameters. E.g., \fBarg=one\fP, \fBarg=two\fP will be sent as \fBarg[]=one\fP,
\fBarg[]=two\fP\&. This is not supported; send JSON or YAML instead.
.UNINDENT
.UNINDENT
.UNINDENT
.SS A Websockets add\-on to saltnado
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
tornado Python module
.UNINDENT
.UNINDENT
.sp
In order to enable saltnado_websockets you must add websockets: True to your
saltnado config block.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rest_tornado:
# can be any port
port: 8000
ssl_crt: /etc/pki/api/certs/server.crt
# no need to specify ssl_key if cert and key
# are in one single file
ssl_key: /etc/pki/api/certs/server.key
debug: False
disable_ssl: False
websockets: True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS All Events
.sp
Exposes \fBall\fP "real\-time" events from Salt\(aqs event bus on a websocket connection.
It should be noted that "Real\-time" here means these events are made available
to the server as soon as any salt related action (changes to minions, new jobs etc) happens.
Clients are however assumed to be able to tolerate any network transport related latencies.
Functionality provided by this endpoint is similar to the \fB/events\fP end point.
.sp
The event bus on the Salt master exposes a large variety of things, notably
when executions are started on the master and also when minions ultimately
return their results. This URL provides a real\-time window into a running
Salt infrastructure. Uses websocket as the transport mechanism.
.sp
Exposes GET method to return websocket connections.
All requests should include an auth token.
A way to obtain obtain authentication tokens is shown below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
% curl \-si localhost:8000/login \e
\-H "Accept: application/json" \e
\-d username=\(aqsalt\(aq \e
\-d password=\(aqsalt\(aq \e
\-d eauth=\(aqpam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Which results in the response
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"return": [{
"perms": [".*", "@runner", "@wheel"],
"start": 1400556492.277421,
"token": "d0ce6c1a37e99dcc0374392f272fe19c0090cca7",
"expire": 1400599692.277422,
"user": "salt",
"eauth": "pam"
}]
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example the \fBtoken\fP returned is \fBd0ce6c1a37e99dcc0374392f272fe19c0090cca7\fP and can be included
in subsequent websocket requests (as part of the URL).
.sp
The event stream can be easily consumed via JavaScript:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Note, you must be authenticated!
// Get the Websocket connection to Salt
var source = new Websocket(\(aqwss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq);
// Get Salt\(aqs "real time" event stream.
source.onopen = function() { source.send(\(aqwebsocket client ready\(aq); };
// Other handlers
source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); };
// e.data represents Salt\(aqs "real time" event data as serialized JSON.
source.onmessage = function(e) { console.debug(e.data); };
// Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
source.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or via Python, using the Python module
\fI\%websocket\-client\fP for example.
Or the tornado
\fI\%client\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note, you must be authenticated!
from websocket import create_connection
# Get the Websocket connection to Salt
ws = create_connection(\(aqwss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq)
# Get Salt\(aqs "real time" event stream.
ws.send(\(aqwebsocket client ready\(aq)
# Simple listener to print results of Salt\(aqs "real time" event stream.
# Look at https://pypi.python.org/pypi/websocket\-client/ for more examples.
while listening_to_events:
print ws.recv() # Salt\(aqs "real time" event data as serialized JSON.
# Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
ws.close()
# Please refer to https://github.com/liris/websocket\-client/issues/81 when using a self signed cert
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Above examples show how to establish a websocket connection to Salt and activating
real time updates from Salt\(aqs event stream by signaling \fBwebsocket client ready\fP\&.
.SS Formatted Events
.sp
Exposes \fBformatted\fP "real\-time" events from Salt\(aqs event bus on a websocket connection.
It should be noted that "Real\-time" here means these events are made available
to the server as soon as any salt related action (changes to minions, new jobs etc) happens.
Clients are however assumed to be able to tolerate any network transport related latencies.
Functionality provided by this endpoint is similar to the \fB/events\fP end point.
.sp
The event bus on the Salt master exposes a large variety of things, notably
when executions are started on the master and also when minions ultimately
return their results. This URL provides a real\-time window into a running
Salt infrastructure. Uses websocket as the transport mechanism.
.sp
Formatted events parses the raw "real time" event stream and maintains
a current view of the following:
.INDENT 0.0
.IP \(bu 2
minions
.IP \(bu 2
jobs
.UNINDENT
.sp
A change to the minions (such as addition, removal of keys or connection drops)
or jobs is processed and clients are updated.
Since we use salt\(aqs presence events to track minions,
please enable \fBpresence_events\fP
and set a small value for the \fBloop_interval\fP
in the salt master config file.
.sp
Exposes GET method to return websocket connections.
All requests should include an auth token.
A way to obtain obtain authentication tokens is shown below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
% curl \-si localhost:8000/login \e
\-H "Accept: application/json" \e
\-d username=\(aqsalt\(aq \e
\-d password=\(aqsalt\(aq \e
\-d eauth=\(aqpam\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Which results in the response
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"return": [{
"perms": [".*", "@runner", "@wheel"],
"start": 1400556492.277421,
"token": "d0ce6c1a37e99dcc0374392f272fe19c0090cca7",
"expire": 1400599692.277422,
"user": "salt",
"eauth": "pam"
}]
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example the \fBtoken\fP returned is \fBd0ce6c1a37e99dcc0374392f272fe19c0090cca7\fP and can be included
in subsequent websocket requests (as part of the URL).
.sp
The event stream can be easily consumed via JavaScript:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Note, you must be authenticated!
// Get the Websocket connection to Salt
var source = new Websocket(\(aqwss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq);
// Get Salt\(aqs "real time" event stream.
source.onopen = function() { source.send(\(aqwebsocket client ready\(aq); };
// Other handlers
source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); };
// e.data represents Salt\(aqs "real time" event data as serialized JSON.
source.onmessage = function(e) { console.debug(e.data); };
// Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
source.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or via Python, using the Python module
\fI\%websocket\-client\fP for example.
Or the tornado
\fI\%client\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Note, you must be authenticated!
from websocket import create_connection
# Get the Websocket connection to Salt
ws = create_connection(\(aqwss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq)
# Get Salt\(aqs "real time" event stream.
ws.send(\(aqwebsocket client ready\(aq)
# Simple listener to print results of Salt\(aqs "real time" event stream.
# Look at https://pypi.python.org/pypi/websocket\-client/ for more examples.
while listening_to_events:
print ws.recv() # Salt\(aqs "real time" event data as serialized JSON.
# Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
ws.close()
# Please refer to https://github.com/liris/websocket\-client/issues/81 when using a self signed cert
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Above examples show how to establish a websocket connection to Salt and activating
real time updates from Salt\(aqs event stream by signaling \fBwebsocket client ready\fP\&.
.SS Example responses
.sp
\fBMinion information\fP is a dictionary keyed by each connected minion\(aqs \fBid\fP (\fBmid\fP),
grains information for each minion is also included.
.sp
Minion information is sent in response to the following minion events:
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B connection drops
.INDENT 7.0
.IP \(bu 2
requires running \fBmanage.present\fP periodically every \fBloop_interval\fP seconds
.UNINDENT
.UNINDENT
.IP \(bu 2
minion addition
.IP \(bu 2
minon removal
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Not all grains are shown
data: {
"minions": {
"minion1": {
"id": "minion1",
"grains": {
"kernel": "Darwin",
"domain": "local",
"zmqversion": "4.0.3",
"kernelrelease": "13.2.0"
}
}
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBJob information\fP is also tracked and delivered.
.sp
Job information is also a dictionary
in which each job\(aqs information is keyed by salt\(aqs \fBjid\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
data: {
"jobs": {
"20140609153646699137": {
"tgt_type": "glob",
"jid": "20140609153646699137",
"tgt": "*",
"start_time": "2014\-06\-09T15:36:46.700315",
"state": "complete",
"fun": "test.ping",
"minions": {
"minion1": {
"return": true,
"retcode": 0,
"success": true
}
}
}
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Setup
.SS REST URI Reference
.INDENT 0.0
.IP \(bu 2
\fI\%/\fP
.IP \(bu 2
\fI\%/login\fP
.IP \(bu 2
\fI\%/minions\fP
.IP \(bu 2
\fI\%/jobs\fP
.IP \(bu 2
\fI\%/run\fP
.IP \(bu 2
\fI\%/events\fP
.IP \(bu 2
\fI\%/hook\fP
.UNINDENT
.SS \fB/\fP
.INDENT 0.0
.TP
.B salt.netapi.rest_tornado.saltnado.SaltAPIHandler
alias of \fB<Mock object at 0x119095550>\fP
.UNINDENT
.SS \fB/login\fP
.INDENT 0.0
.TP
.B salt.netapi.rest_tornado.saltnado.SaltAuthHandler
alias of \fB<Mock object at 0x1190955d0>\fP
.UNINDENT
.SS \fB/minions\fP
.INDENT 0.0
.TP
.B salt.netapi.rest_tornado.saltnado.MinionSaltAPIHandler
alias of \fB<Mock object at 0x11568af50>\fP
.UNINDENT
.SS \fB/jobs\fP
.INDENT 0.0
.TP
.B salt.netapi.rest_tornado.saltnado.JobsSaltAPIHandler
alias of \fB<Mock object at 0x11568a250>\fP
.UNINDENT
.SS \fB/run\fP
.INDENT 0.0
.TP
.B salt.netapi.rest_tornado.saltnado.RunSaltAPIHandler
alias of \fB<Mock object at 0x11568a6d0>\fP
.UNINDENT
.SS \fB/events\fP
.INDENT 0.0
.TP
.B salt.netapi.rest_tornado.saltnado.EventsSaltAPIHandler
alias of \fB<Mock object at 0x1193e8610>\fP
.UNINDENT
.SS \fB/hook\fP
.INDENT 0.0
.TP
.B salt.netapi.rest_tornado.saltnado.WebhookSaltAPIHandler
alias of \fB<Mock object at 0x1193e8f10>\fP
.UNINDENT
.SS rest_wsgi
.SS A minimalist REST API for Salt
.sp
This \fBrest_wsgi\fP module provides a no\-frills REST interface for sending
commands to the Salt master. There are no dependencies.
.sp
Extra care must be taken when deploying this module into production. Please
read this documentation in entirety.
.sp
All authentication is done through Salt\(aqs \fIexternal auth\fP
system.
.SS Usage
.INDENT 0.0
.IP \(bu 2
All requests must be sent to the root URL (\fB/\fP).
.IP \(bu 2
All requests must be sent as a POST request with JSON content in the request
body.
.IP \(bu 2
All responses are in JSON.
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBrest_cherrypy\fP
.sp
The \fBrest_cherrypy\fP module is
more full\-featured, production\-ready, and has builtin security features.
.UNINDENT
.UNINDENT
.SS Deployment
.sp
The \fBrest_wsgi\fP netapi module is a standard Python WSGI app. It can be
deployed one of two ways.
.SS Using a WSGI\-compliant web server
.sp
This module may be run via any WSGI\-compliant production server such as Apache
with mod_wsgi or Nginx with FastCGI.
.sp
It is strongly recommended that this app be used with a server that supports
HTTPS encryption since raw Salt authentication credentials must be sent with
every request. Any apps that access Salt through this interface will need to
manually manage authentication credentials (either username and password or a
Salt token). Tread carefully.
.SS \fBsalt\-api\fP using a development\-only server
.sp
If run directly via the salt\-api daemon it uses the \fI\%wsgiref.simple_server()\fP
that ships in the Python standard library. This is a single\-threaded server
that is intended for testing and development. \fBThis server does not use
encryption\fP; please note that raw Salt authentication credentials must be sent
with every HTTP request.
.sp
\fBRunning this module via salt\-api is not recommended!\fP
.sp
In order to start this module via the \fBsalt\-api\fP daemon the following must be
put into the Salt master config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rest_wsgi:
port: 8001
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Usage examples
.INDENT 0.0
.TP
.B POST /
\fBExample request\fP for a basic \fBtest.ping\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
% curl \-sS \-i \e
\-H \(aqContent\-Type: application/json\(aq \e
\-d \(aq[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local","tgt":"*","fun":"test.ping"}]\(aq localhost:8001
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.0 200 OK
Content\-Length: 89
Content\-Type: application/json
{"return": [{"ms\-\-4": true, "ms\-\-3": true, "ms\-\-2": true, "ms\-\-1": true, "ms\-\-0": true}]}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample request\fP for an asynchronous \fBtest.ping\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
% curl \-sS \-i \e
\-H \(aqContent\-Type: application/json\(aq \e
\-d \(aq[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local_async","tgt":"*","fun":"test.ping"}]\(aq localhost:8001
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.0 200 OK
Content\-Length: 103
Content\-Type: application/json
{"return": [{"jid": "20130412192112593739", "minions": ["ms\-\-4", "ms\-\-3", "ms\-\-2", "ms\-\-1", "ms\-\-0"]}]}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample request\fP for looking up a job ID:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
% curl \-sS \-i \e
\-H \(aqContent\-Type: application/json\(aq \e
\-d \(aq[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"runner","fun":"jobs.lookup_jid","jid":"20130412192112593739"}]\(aq localhost:8001
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBExample response\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.0 200 OK
Content\-Length: 89
Content\-Type: application/json
{"return": [{"ms\-\-4": true, "ms\-\-3": true, "ms\-\-2": true, "ms\-\-1": true, "ms\-\-0": true}]}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B form lowstate
A list of \fIlowstate\fP data appropriate for the
\fIclient\fP interface you are calling.
.TP
.B status 200
success
.TP
.B status 401
authentication required
.UNINDENT
.SS Full list of builtin output modules
.sp
Follow one of the below links for further information and examples
.TS
center;
|l|l|.
_
T{
\fBgrains\fP
T} T{
Special outputter for grains
T}
_
T{
\fBhighstate\fP
T} T{
Outputter for displaying results of state runs
T}
_
T{
\fBjson_out\fP
T} T{
Display return data in JSON format
T}
_
T{
\fBkey\fP
T} T{
Display salt\-key output
T}
_
T{
\fBnested\fP
T} T{
Recursively display nested data
T}
_
T{
\fBnewline_values_only\fP
T} T{
Display values only, separated by newlines
T}
_
T{
\fBno_out\fP
T} T{
Display no output
T}
_
T{
\fBno_return\fP
T} T{
Display output for minions that did not return
T}
_
T{
\fBoverstatestage\fP
T} T{
Display clean output of an overstate stage
T}
_
T{
\fBpprint_out\fP
T} T{
Python pretty\-print (pprint)
T}
_
T{
\fBraw\fP
T} T{
Display raw output data structure
T}
_
T{
\fBtxt\fP
T} T{
Simple text outputter
T}
_
T{
\fBvirt_query\fP
T} T{
virt.query outputter
T}
_
T{
\fByaml_out\fP
T} T{
Display return data in YAML format
T}
_
.TE
.SS salt.output.grains
.SS Special outputter for grains
.sp
This outputter is a more condensed version of the \fBnested\fP outputter, used by default to display grains when the
following functions are invoked:
.INDENT 0.0
.IP \(bu 2
\fBgrains.item\fP
.IP \(bu 2
\fBgrains.items\fP
.IP \(bu 2
\fBgrains.setval\fP
.UNINDENT
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myminion:
dictionary: {\(aqabc\(aq: 123, \(aqdef\(aq: 456}
list:
Hello
World
bar: baz
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.grains.output(grains)
Output the grains in a clean way
.UNINDENT
.SS salt.output.highstate
.SS Outputter for displaying results of state runs
.sp
The return data from the Highstate command is a standard data structure
which is parsed by the highstate outputter to deliver a clean and readable
set of information about the HighState run on minions.
.sp
Two configurations can be set to modify the highstate outputter. These values
can be set in the master config to change the output of the \fBsalt\fP command or
set in the minion config to change the output of the \fBsalt\-call\fP command.
.INDENT 0.0
.TP
.B state_verbose:
By default \fIstate_verbose\fP is set to \fITrue\fP, setting this to \fIFalse\fP will
instruct the highstate outputter to omit displaying anything in green, this
means that nothing with a result of True and no changes will not be printed
.TP
.B state_output:
The highstate outputter has five output modes, \fIfull\fP, \fIterse\fP, \fImixed\fP,
\fIchanges\fP and \fIfilter\fP\&. The default is set to full, which will display many
lines of detailed information for each executed chunk. If the \fIstate_output\fP
option is set to \fIterse\fP then the output is greatly simplified and shown in
only one line. If \fImixed\fP is used, then terse output will be used unless a
state failed, in which case full output will be used. If \fIchanges\fP is used,
then terse output will be used if there was no error and no changes,
otherwise full output will be used. If \fIfilter\fP is used, then either or both
of two different filters can be used: \fIexclude\fP or \fIterse\fP\&. These can be set
as such from the command line, or in the Salt config as
\fIstate_output_exclude\fP or \fIstate_output_terse\fP, respectively. The values to
exclude must be a comma\-separated list of \fITrue\fP, \fIFalse\fP and/or \fINone\fP\&.
Because of parsing nuances, if only one of these is used, it must still
contain a comma. For instance: \fIexclude=True,\fP\&.
.TP
.B state_tabular:
If \fIstate_output\fP uses the terse output, set this to \fITrue\fP for an aligned
output format. If you wish to use a custom format, this can be set to a
string.
.UNINDENT
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myminion:
\-\-\-\-\-\-\-\-\-\-
ID: test.ping
Function: module.run
Result: True
Comment: Module function test.ping executed
Changes:
\-\-\-\-\-\-\-\-\-\-
ret:
True
Summary
\-\-\-\-\-\-\-\-\-\-\-\-
Succeeded: 1
Failed: 0
\-\-\-\-\-\-\-\-\-\-\-\-
Total: 0
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.highstate.output(data)
The HighState Outputter is only meant to be used with the state.highstate
function, or a function that returns highstate return data.
.UNINDENT
.SS salt.output.json_out
.SS Display return data in JSON format
.INDENT 0.0
.TP
.B configuration
The output format can be configured in two ways:
Using the \fB\-\-out\-indent\fP CLI flag and specifying a positive integer or a
negative integer to group JSON from each minion to a single line.
.sp
Or setting the \fBoutput_indent\fP setting in the Master or Minion
configuration file with one of the following values:
.INDENT 7.0
.IP \(bu 2
\fBNull\fP: put each minion return on a single line.
.IP \(bu 2
\fBpretty\fP: use four\-space indents and sort the keys.
.IP \(bu 2
An integer: specify the indentation level.
.UNINDENT
.UNINDENT
.sp
Salt\(aqs outputters operate on a per\-minion basis. Each minion return will be
output as a single JSON object once it comes in to the master.
.sp
Some JSON parsers can guess when an object ends and a new one begins but many
can not. A good way to differentiate between each minion return is to use the
single\-line output format and to parse each line individually. Example output
(truncated):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{"dave": {"en0": {"hwaddr": "02:b0:26:32:4c:69", ...}}}
{"jerry": {"en0": {"hwaddr": "02:26:ab:0d:b9:0d", ...}}}
{"kevin": {"en0": {"hwaddr": "02:6d:7f:ce:9f:ee", ...}}}
{"mike": {"en0": {"hwaddr": "02:48:a2:4b:70:a0", ...}}}
{"phill": {"en0": {"hwaddr": "02:1d:cc:a2:33:55", ...}}}
{"stuart": {"en0": {"hwaddr": "02:9a:e0:ea:9e:3c", ...}}}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.json_out.output(data)
Print the output data in JSON
.UNINDENT
.SS salt.output.key
.SS Display salt\-key output
.sp
The \fBsalt\-key\fP command makes use of this outputter to format its output.
.INDENT 0.0
.TP
.B salt.output.key.output(data)
Read in the dict structure generated by the salt key API methods and
print the structure.
.UNINDENT
.SS salt.output.nested
.SS Recursively display nested data
.sp
This is the default outputter for most execution functions.
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myminion:
\-\-\-\-\-\-\-\-\-\-
foo:
\-\-\-\-\-\-\-\-\-\-
bar:
baz
dictionary:
\-\-\-\-\-\-\-\-\-\-
abc:
123
def:
456
list:
\- Hello
\- World
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.output.nested.NestDisplay
Manage the nested display contents
.INDENT 7.0
.TP
.B display(ret, indent, prefix, out)
Recursively iterate down through data structures to determine output
.UNINDENT
.INDENT 7.0
.TP
.B ustring(indent, color, msg, prefix=\(aq\(aq, suffix=\(aq\(aq, endc=None)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.nested.output(ret)
Display ret data
.UNINDENT
.SS salt.output.newline_values_only
.SS Display values only, separated by newlines
.sp
New in version Lithium.
.sp
This outputter is designed for Salt CLI return data. It will do the following
to the return dict:
.INDENT 0.0
.IP 1. 3
Get just the values (ignoring the minion IDs).
.IP 2. 3
Each value, if it is iterable, is split a separate line.
.IP 3. 3
Each minion\(aqs values are separated by newlines.
.UNINDENT
.sp
This results in a single string of return data containing all the values from
the various minions.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
As noted above, this outputter will discard the minion ID. If the minion ID
is important, then an outputter that returns the full return dictionary in
a parsable format (such as \fBjson\fP, \fBpprint,\fP, or \fByaml\fP) may be more
suitable.
.UNINDENT
.UNINDENT
.SS Example 1
.SS Input
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
\(aqmyminion\(aq: [\(aq127.0.0.1\(aq, \(aq10.0.0.1\(aq],
\(aqsecond\-minion\(aq: [\(aq127.0.0.1\(aq, \(aq10.0.0.2\(aq]
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Output
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
127.0.0.1
10.0.0.1
127.0.0.1
10.0.0.2
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example 2
.SS Input
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
\(aqmyminion\(aq: 8,
\(aqsecond\-minion\(aq: 10
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Output
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
8
10
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.newline_values_only.output(data)
Display modified ret data
.UNINDENT
.SS salt.output.no_out
.SS Display no output
.sp
No output is produced when this outputter is selected
.INDENT 0.0
.TP
.B salt.output.no_out.output(ret)
Don\(aqt display data. Used when you only are interested in the
return.
.UNINDENT
.SS salt.output.no_return
.SS Display output for minions that did not return
.sp
This outputter is used to display notices about which minions failed to return
when a salt function is run with \fB\-v\fP or \fB\-\-verbose\fP\&. It should not be
called directly from the CLI.
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virtucentos:
Minion did not return
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.output.no_return.NestDisplay
Create generator for nested output
.INDENT 7.0
.TP
.B display(ret, indent, prefix, out)
Recursively iterate down through data structures to determine output
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.no_return.output(ret)
Display ret data
.UNINDENT
.SS salt.output.overstatestage
.SS Display clean output of an overstate stage
.sp
This outputter is used to display \fIOverState\fP stages,
and should not be called directly.
.INDENT 0.0
.TP
.B salt.output.overstatestage.output(data)
Format the data for printing stage information from the overstate system
.UNINDENT
.SS salt.output.pprint_out
.SS Python pretty\-print (pprint)
.sp
The python pretty\-print system was once the default outputter. It simply
passes the return data through to \fBpprint.pformat\fP and prints the results.
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqsaltmine\(aq: {\(aqfoo\(aq: {\(aqbar\(aq: \(aqbaz\(aq,
\(aqdictionary\(aq: {\(aqabc\(aq: 123, \(aqdef\(aq: 456},
\(aqlist\(aq: [\(aqHello\(aq, \(aqWorld\(aq]}}}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.pprint_out.output(data)
Print out via pretty print
.UNINDENT
.SS salt.output.raw
.SS Display raw output data structure
.sp
This outputter simply displays the output as a python data structure, by
printing a string representation of it. It is similar to the \fBpprint\fP outputter, only the data is not nicely
formatted/indented.
.sp
This was the original outputter used by Salt before the outputter system was
developed.
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqmyminion\(aq: {\(aqfoo\(aq: {\(aqlist\(aq: [\(aqHello\(aq, \(aqWorld\(aq], \(aqbar\(aq: \(aqbaz\(aq, \(aqdictionary\(aq: {\(aqabc\(aq: 123, \(aqdef\(aq: 456}}}}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.raw.output(data)
Rather basic....
.UNINDENT
.SS salt.output.txt
.SS Simple text outputter
.sp
The txt outputter has been developed to make the output from shell
commands on minions appear as they do when the command is executed
on the minion.
.INDENT 0.0
.TP
.B salt.output.txt.output(data)
Output the data in lines, very nice for running commands
.UNINDENT
.SS salt.output.virt_query
.SS virt.query outputter
.sp
Used to display the output from the \fBvirt.query\fP
runner.
.INDENT 0.0
.TP
.B salt.output.virt_query.output(data)
Display output for the salt\-run virt.query function
.UNINDENT
.SS salt.output.yaml_out
.SS Display return data in YAML format
.sp
This outputter defaults to printing in YAML block mode for better readability.
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
saltmine:
foo:
bar: baz
dictionary:
abc: 123
def: 456
list:
\- Hello
\- World
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.output.yaml_out.output(data)
Print out YAML using the block mode
.UNINDENT
.SS 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
In Salt 0.10.0 the ability to execute runners from the master was added. This
allows for the master to return collective data from runners back to the
minions via the peer interface.
.sp
The peer interface is configured through two options in the master
configuration file. For minions to send commands from the master the \fBpeer\fP
configuration is used. To allow for minions to execute runners from the master
the \fBpeer_run\fP configuration is used.
.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 Peer Configuration
.sp
The configuration is done under the \fBpeer\fP 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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer:
.*:
\- .*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This configuration will allow minions with IDs ending in example.com access
to the test, ps, and pkg module functions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer:
.*example.com:
\- test.*
\- ps.*
\- pkg.*
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer:
.*example.com:
\- test.*
\- ps.*
\- pkg.*
.*foo.org:
\- test.*
\- ps.*
\- pkg.*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Peer Runner Communication
.sp
Configuration to allow minions to execute runners from the master is done via
the \fBpeer_run\fP option on the master. The \fBpeer_run\fP configuration follows
the same logic as the \fBpeer\fP option. The only difference is that access is
granted to runner modules.
.sp
To open up access to all minions to all runners:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer_run:
.*:
\- .*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This configuration will allow minions with IDs ending in example.com access
to the manage and jobs runner functions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
peer_run:
.*example.com:
\- manage.*
\- jobs.*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Using Peer Communication
.sp
The publish module was created to manage peer communication. The publish module
comes with a number of functions to execute peer communication in different
ways. Currently there are three functions in the publish module. These examples
will show how to test the peer system via the salt\-call command.
.sp
To execute test.ping on all minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-call publish.publish \e* test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To execute the manage.up runner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-call publish.runner manage.up
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To match minions using other matchers, use \fBexpr_form\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-call publish.publish \(aqwebserv* and not G@os:Ubuntu\(aq test.ping expr_form=\(aqcompound\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Pillars
.sp
Salt includes a number of built\-in external pillars, listed at
\fIall\-salt.pillars\fP\&.
.sp
You may also wish to look at the standard pillar documentation, at
\fIpillar\-configuration\fP
.sp
The source for the built\-in Salt pillars can be found here:
\fI\%https://github.com/saltstack/salt/blob/develop/salt/pillar\fP
.SS Full list of builtin pillar modules
.TS
center;
|l|l|.
_
T{
\fBcmd_json\fP
T} T{
Execute a command and read the output as JSON.
T}
_
T{
\fBcmd_yaml\fP
T} T{
Execute a command and read the output as YAML.
T}
_
T{
\fBcmd_yamlex\fP
T} T{
Execute a command and read the output as YAMLEX.
T}
_
T{
\fBcobbler\fP
T} T{
A module to pull data from Cobbler via its API into the Pillar dictionary
T}
_
T{
\fBdjango_orm\fP
T} T{
Generate Pillar data from Django models through the Django ORM
T}
_
T{
\fBetcd_pillar\fP
T} T{
Use etcd data as a Pillar source
T}
_
T{
\fBforeman\fP
T} T{
A module to pull data from Foreman via its API into the Pillar dictionary
T}
_
T{
\fBgit_pillar\fP
T} T{
Clone a remote git repository and use the filesystem as a Pillar source
T}
_
T{
\fBhiera\fP
T} T{
Use hiera data as a Pillar source
T}
_
T{
\fBlibvirt\fP
T} T{
Load up the libvirt keys into Pillar for a given minion if said keys have been generated using the libvirt key runner
T}
_
T{
\fBmongo\fP
T} T{
Read Pillar data from a mongodb collection
T}
_
T{
\fBmysql\fP
T} T{
Retrieve Pillar data by doing a MySQL query
T}
_
T{
\fBpillar_ldap\fP
T} T{
Use LDAP data as a Pillar source
T}
_
T{
\fBpuppet\fP
T} T{
Execute an unmodified puppet_node_classifier and read the output as YAML.
T}
_
T{
\fBreclass_adapter\fP
T} T{
Use the "reclass" database as a Pillar source
T}
_
T{
\fBredismod\fP
T} T{
Read pillar data from a Redis backend
T}
_
T{
\fBs3\fP
T} T{
Copy pillar data from a bucket in Amazon S3
T}
_
T{
\fBsvn_pillar\fP
T} T{
Clone a remote SVN repository and use the filesystem as a Pillar source
T}
_
T{
\fBvirtkey\fP
T} T{
Accept a key from a hypervisor if the virt runner has already submitted an authorization request
T}
_
.TE
.SS salt.pillar.cmd_json
.sp
Execute a command and read the output as JSON. The JSON data is then directly overlaid onto the minion\(aqs Pillar data.
.INDENT 0.0
.TP
.B salt.pillar.cmd_json.ext_pillar(minion_id, pillar, command)
Execute a command and read the output as JSON
.UNINDENT
.SS salt.pillar.cmd_yaml
.sp
Execute a command and read the output as YAML. The YAML data is then directly overlaid onto the minion\(aqs Pillar data
.INDENT 0.0
.TP
.B salt.pillar.cmd_yaml.ext_pillar(minion_id, pillar, command)
Execute a command and read the output as YAML
.UNINDENT
.SS salt.pillar.cmd_yamlex
.sp
Execute a command and read the output as YAMLEX. The YAMLEX data is then
directly overlaid onto the minion\(aqs Pillar data
.INDENT 0.0
.TP
.B salt.pillar.cmd_yamlex.ext_pillar(minion_id, pillar, command)
Execute a command and read the output as YAMLEX
.UNINDENT
.SS salt.pillar.cobbler
.sp
A module to pull data from Cobbler via its API into the Pillar dictionary
.SS Configuring the Cobbler ext_pillar
.sp
The same cobbler.* parameters are used for both the Cobbler tops and Cobbler pillar
modules.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- cobbler:
key: cobbler # Nest results within this key. By default, values are not nested.
only: [parameters] # Add only these keys to pillar.
cobbler.url: https://example.com/cobbler_api #default is http://localhost/cobbler_api
cobbler.user: username # default is no username
cobbler.password: password # default is no password
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Module Documentation
.INDENT 0.0
.TP
.B salt.pillar.cobbler.ext_pillar(minion_id, pillar, key=None, only=())
Read pillar data from Cobbler via its API.
.UNINDENT
.SS salt.pillar.django_orm
.sp
Generate Pillar data from Django models through the Django ORM
.INDENT 0.0
.TP
.B maintainer
Micah Hausler <\fI\%micah.hausler@gmail.com\fP>
.TP
.B maturity
new
.UNINDENT
.SS Configuring the django_orm ext_pillar
.sp
To use this module, your Django project must be on the salt master server with
database access. This assumes you are using virtualenv with all the project\(aqs
requirements installed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- django_orm:
pillar_name: my_application
project_path: /path/to/project/
settings_module: my_application.settings
env_file: /path/to/env/file.sh
# Optional: If your project is not using the system python,
# add your virtualenv path below.
env: /path/to/virtualenv/
django_app:
# Required: the app that is included in INSTALLED_APPS
my_application.clients:
# Required: the model name
Client:
# Required: model field to use as the key in the rendered
# Pillar. Must be unique; must also be included in the
# \(ga\(gafields\(ga\(ga list below.
name: shortname
# Optional:
# See Django\(aqs QuerySet documentation for how to use .filter()
filter: {\(aqkw\(aq: \(aqargs\(aq}
# Required: a list of field names
# List items will be used as arguments to the .values() method.
# See Django\(aqs QuerySet documentation for how to use .values()
fields:
\- field_1
\- field_2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would return pillar data that would look like
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_application:
my_application.clients:
Client:
client_1:
field_1: data_from_field_1
field_2: data_from_field_2
client_2:
field_1: data_from_field_1
field_2: data_from_field_2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As another example, data from multiple database tables can be fetched using
Django\(aqs regular lookup syntax. Note, using ManyToManyFields will not currently
work since the return from values() changes if a ManyToMany is present.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- django_orm:
pillar_name: djangotutorial
project_path: /path/to/mysite
settings_module: mysite.settings
django_app:
mysite.polls:
Choices:
name: poll__question
fields:
\- poll__question
\- poll__id
\- choice_text
\- votes
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Module Documentation
.INDENT 0.0
.TP
.B salt.pillar.django_orm.ext_pillar(minion_id, pillar, pillar_name, project_path, settings_module, django_app, env=None, env_file=None, *args, **kwargs)
Connect to a Django database through the ORM and retrieve model fields
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBpillar_name\fP (\fI\%str\fP) \-\- The name of the pillar to be returned
.IP \(bu 2
\fBproject_path\fP (\fI\%str\fP) \-\- The full path to your Django project (the directory
manage.py is in)
.IP \(bu 2
\fBsettings_module\fP (\fI\%str\fP) \-\- The settings module for your project. This can be
found in your manage.py file
.IP \(bu 2
\fBdjango_app\fP (\fI\%str\fP) \-\- A dictionary containing your apps, models, and fields
.IP \(bu 2
\fBenv\fP (\fI\%str\fP) \-\- The full path to the virtualenv for your Django project
.IP \(bu 2
\fBenv_file\fP (\fI\%str\fP) \-\- An optional bash file that sets up your environment. The
file is run in a subprocess and the changed variables are then added
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.pillar.etcd_pillar
.sp
Use etcd data as a Pillar source
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
python\-etcd
.UNINDENT
.UNINDENT
.sp
In order to use an etcd server, a profile must be created in the master
configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_etcd_config:
etcd.host: 127.0.0.1
etcd.port: 4001
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After the profile is created, configure the external pillar system to use it.
Optionally, a root may be specified.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- etcd: my_etcd_config
ext_pillar:
\- etcd: my_etcd_config root=/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using these configuration profiles, multiple etcd sources may also be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- etcd: my_etcd_config
\- etcd: my_other_etcd_config
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBminion_id\fP may be used in the \fBroot\fP path to expose minion\-specific
information stored in etcd.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- etcd: my_etcd_config root=/salt/%(minion_id)s
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Minion\-specific values may override shared values when the minion\-specific root
appears after the shared root:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- etcd: my_etcd_config root=/salt\-shared
\- etcd: my_other_etcd_config root=/salt\-private/%(minion_id)s
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using the configuration above, the following commands could be used to share a
key with all minions but override its value for a specific minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
etcdctl set /salt\-shared/mykey my_value
etcdctl set /salt\-private/special_minion_id/mykey my_other_value
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.etcd_pillar.ext_pillar(minion_id, pillar, conf)
Check etcd for all data
.UNINDENT
.SS salt.pillar.foreman
.sp
A module to pull data from Foreman via its API into the Pillar dictionary
.SS Configuring the Foreman ext_pillar
.sp
Set the following Salt config to setup Foreman as external pillar source:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- foreman:
key: foreman # Nest results within this key
only: [\(aqhostgroup_name\(aq, \(aqparameters\(aq] # Add only these keys to pillar
foreman.url: https://example.com/foreman_api
foreman.user: username # default is admin
foreman.password: password # default is changeme
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following options are optional:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foreman.api: apiversion # default is 2 (1 is not supported yet)
foreman.verifyssl: False # default is True
foreman.certfile: /etc/ssl/certs/mycert.pem # default is None
foreman.keyfile: /etc/ssl/private/mykey.pem # default is None
foreman.cafile: /etc/ssl/certs/mycert.ca.pem # default is None
foreman.lookup_parameters: True # default is True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Module Documentation
.INDENT 0.0
.TP
.B salt.pillar.foreman.ext_pillar(minion_id, pillar, key=None, only=())
Read pillar data from Foreman via its API.
.UNINDENT
.SS salt.pillar.git_pillar
.sp
Clone a remote git repository and use the filesystem as a Pillar source
.sp
This external Pillar source can be configured in the master config file like
so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- git: master git://gitserver/git\-pillar.git root=subdirectory
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIroot=\fP parameter is optional and used to set the subdirectory from where
to look for Pillar files (such as \fBtop.sls\fP).
.sp
Changed in version 2014.7.0: The optional \fBroot\fP parameter will be added.
.sp
Note that this is not the same thing as configuring pillar data using the
\fBpillar_roots\fP parameter. The branch referenced in the
\fBext_pillar\fP entry above (\fBmaster\fP), would evaluate to the
\fBbase\fP environment, so this branch needs to contain a \fBtop.sls\fP with a
\fBbase\fP section in it, like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- foo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To use other environments from the same git repo as git_pillar sources, just
add additional lines, like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- git: master git://gitserver/git\-pillar.git
\- git: dev git://gitserver/git\-pillar.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To remap a specific branch to a specific environment separate the branch name
and the environment name with a colon:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- git: develop:dev git://gitserver/git\-pillar.git
\- git: master:prod git://gitserver/git\-pillar.git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this case, the \fBdev\fP branch would need its own \fBtop.sls\fP with a \fBdev\fP
section in it, like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dev:
\(aq*\(aq:
\- bar
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.pillar.git_pillar.GitPillar(branch, repo_location, opts)
Deal with the remote git repository for Pillar
.INDENT 7.0
.TP
.B envs()
Return a list of refs that can be used as environments
.UNINDENT
.INDENT 7.0
.TP
.B update()
Ensure you are following the latest changes on the remote
.sp
Return boolean whether it worked
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.git_pillar.envs(branch, repo_location)
Return a list of refs that can be used as environments
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.git_pillar.ext_pillar(minion_id, repo_string, pillar_dirs)
Execute a command and read the output as YAML
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.git_pillar.update(branch, repo_location)
Ensure you are following the latest changes on the remote
.sp
return boolean whether it worked
.UNINDENT
.SS salt.pillar.hiera
.sp
Use hiera data as a Pillar source
.INDENT 0.0
.TP
.B salt.pillar.hiera.ext_pillar(minion_id, pillar, conf)
Execute hiera and return the data
.UNINDENT
.SS salt.pillar.libvirt
.sp
Load up the libvirt keys into Pillar for a given minion if said keys have been generated using the libvirt key runner
.INDENT 0.0
.TP
.B salt.pillar.libvirt.ext_pillar(minion_id, pillar, command)
Read in the generated libvirt keys
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.libvirt.gen_hyper_keys(minion_id, country=\(aqUS\(aq, state=\(aqUtah\(aq, locality=\(aqSalt Lake City\(aq, organization=\(aqSalted\(aq)
Generate the keys to be used by libvirt hypervisors, this routine gens
the keys and applies them to the pillar for the hypervisor minions
.UNINDENT
.SS salt.pillar.mongo
.sp
Read Pillar data from a mongodb collection
.INDENT 0.0
.TP
.B depends
pymongo (for salt\-master)
.UNINDENT
.sp
This module will load a node\-specific pillar dictionary from a mongo
collection. It uses the node\(aqs id for lookups and can load either the whole
document, or just a specific field from that
document as the pillar dictionary.
.SS Salt Master Mongo Configuration
.sp
The module shares the same base mongo connection variables as
\fBsalt.returners.mongo_return\fP\&. These variables go in your master
config file.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBmongo.db\fP \- The mongo database to connect to. Defaults to \fB\(aqsalt\(aq\fP\&.
.IP \(bu 2
\fBmongo.host\fP \- The mongo host to connect to. Supports replica sets by
specifying all hosts in the set, comma\-delimited. Defaults to \fB\(aqsalt\(aq\fP\&.
.IP \(bu 2
\fBmongo.port\fP \- The port that the mongo database is running on. Defaults
to \fB27017\fP\&.
.IP \(bu 2
\fBmongo.user\fP \- The username for connecting to mongo. Only required if
you are using mongo authentication. Defaults to \fB\(aq\(aq\fP\&.
.IP \(bu 2
\fBmongo.password\fP \- The password for connecting to mongo. Only required
if you are using mongo authentication. Defaults to \fB\(aq\(aq\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Configuring the Mongo ext_pillar
.sp
The Mongo ext_pillar takes advantage of the fact that the Salt Master
configuration file is yaml. It uses a sub\-dictionary of values to adjust
specific features of the pillar. This is the explicit single\-line dictionary
notation for yaml. One may be able to get the easier\-to\-read multi\-line dict to
work correctly with some experimentation.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- mongo: {collection: vm, id_field: name, re_pattern: \e.example\e.com, fields: [customer_id, software, apache_vhosts]}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the example above, we\(aqve decided to use the \fBvm\fP collection in the
database to store the data. Minion ids are stored in the \fBname\fP field on
documents in that collection. And, since minion ids are FQDNs in most cases,
we\(aqll need to trim the domain name in order to find the minion by hostname in
the collection. When we find a minion, return only the \fBcustomer_id\fP,
\fBsoftware\fP, and \fBapache_vhosts\fP fields, as that will contain the data we
want for a given node. They will be available directly inside the \fBpillar\fP
dict in your SLS templates.
.SS Module Documentation
.INDENT 0.0
.TP
.B salt.pillar.mongo.ext_pillar(minion_id, pillar, collection=\(aqpillar\(aq, id_field=\(aq_id\(aq, re_pattern=None, re_replace=\(aq\(aq, fields=None)
Connect to a mongo database and read per\-node pillar information.
.INDENT 7.0
.TP
.B Parameters:
.INDENT 7.0
.IP \(bu 2
\fIcollection\fP: The mongodb collection to read data from. Defaults to
\fB\(aqpillar\(aq\fP\&.
.IP \(bu 2
\fIid_field\fP: The field in the collection that represents an individual
minion id. Defaults to \fB\(aq_id\(aq\fP\&.
.IP \(bu 2
\fIre_pattern\fP: If your naming convention in the collection is shorter
than the minion id, you can use this to trim the name.
\fIre_pattern\fP will be used to match the name, and \fIre_replace\fP will
be used to replace it. Backrefs are supported as they are in the
Python standard library. If \fBNone\fP, no mangling of the name will
be performed \- the collection will be searched with the entire
minion id. Defaults to \fBNone\fP\&.
.IP \(bu 2
\fIre_replace\fP: Use as the replacement value in node ids matched with
\fIre_pattern\fP\&. Defaults to \(aq\(aq. Feel free to use backreferences here.
.IP \(bu 2
\fIfields\fP: The specific fields in the document to use for the pillar
data. If \fBNone\fP, will use the entire document. If using the
entire document, the \fB_id\fP field will be converted to string. Be
careful with other fields in the document as they must be string
serializable. Defaults to \fBNone\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.pillar.mysql
.sp
Retrieve Pillar data by doing a MySQL query
.INDENT 0.0
.TP
.B maturity
new
.TP
.B depends
python\-mysqldb
.TP
.B platform
all
.UNINDENT
.SS Theory of mysql ext_pillar
.sp
Ok, here\(aqs the theory for how this works...
.INDENT 0.0
.IP \(bu 2
If there\(aqs a keyword arg of mysql_query, that\(aqll go first.
.IP \(bu 2
Then any non\-keyword args are processed in order.
.IP \(bu 2
Finally, remaining keywords are processed.
.UNINDENT
.sp
We do this so that it\(aqs backward compatible with older configs.
Keyword arguments are sorted before being appended, so that they\(aqre predictable,
but they will always be applied last so overall it\(aqs moot.
.sp
For each of those items we process, it depends on the object type:
.INDENT 0.0
.IP \(bu 2
Strings are executed as is and the pillar depth is determined by the number
of fields returned.
.IP \(bu 2
A list has the first entry used as the query, the second as the pillar depth.
.IP \(bu 2
A mapping uses the keys "query" and "depth" as the tuple
.UNINDENT
.sp
You can retrieve as many fields as you like, how the get used depends on the
exact settings.
.SS Configuring the mysql ext_pillar
.sp
First an example of how legacy queries were specified.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- mysql:
mysql_query: "SELECT pillar,value FROM pillars WHERE minion_id = %s"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, a list of queries can be passed in
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- mysql:
\- "SELECT pillar,value FROM pillars WHERE minion_id = %s"
\- "SELECT pillar,value FROM more_pillars WHERE minion_id = %s"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or you can pass in a mapping
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- mysql:
main: "SELECT pillar,value FROM pillars WHERE minion_id = %s"
extras: "SELECT pillar,value FROM more_pillars WHERE minion_id = %s"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The query can be provided as a string as we have just shown, but they can be
provided as lists
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- mysql:
\- "SELECT pillar,value FROM pillars WHERE minion_id = %s"
2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or as a mapping
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- mysql:
\- query: "SELECT pillar,value FROM pillars WHERE minion_id = %s"
depth: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The depth defines how the dicts are constructed.
Essentially if you query for fields a,b,c,d for each row you\(aqll get:
.INDENT 0.0
.IP \(bu 2
With depth 1: {a: {"b": b, "c": c, "d": d}}
.IP \(bu 2
With depth 2: {a: {b: {"c": c, "d": d}}}
.IP \(bu 2
With depth 3: {a: {b: {c: d}}}
.UNINDENT
.sp
Depth greater than 3 wouldn\(aqt be different from 3 itself.
Depth of 0 translates to the largest depth needed, so 3 in this case.
(max depth == key count \- 1)
.sp
The legacy compatibility translates to depth 1.
.sp
Then they are merged the in a similar way to plain pillar data, in the order
returned by MySQL.
.sp
Thus subsequent results overwrite previous ones when they collide.
.sp
If you specify \fIas_list: True\fP in the mapping expression it will convert
collisions to lists.
.sp
If you specify \fIwith_lists: \(aq...\(aq\fP in the mapping expression it will
convert the specified depths to list. The string provided is a sequence
numbers that are comma separated. The string \(aq1,3\(aq will result in:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
a,b,c,d,e,1 # field 1 same, field 3 differs
a,b,c,f,g,2 # ^^^^
a,z,h,y,j,3 # field 1 same, field 3 same
a,z,h,y,k,4 # ^^^^
^ ^
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These columns define list grouping
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{a: [
{c: [
{e: 1},
{g: 2}
]
},
{h: [
{j: 3, k: 4 }
]
}
]}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The range for with_lists is 1 to number_of_fields, inclusive.
Numbers outside this range are ignored.
.sp
Finally, if you use pass the queries in via a mapping, the key will be the
first level name where as passing them in as a list will place them in the
root. This isolates the query results in to their own subtrees.
This may be a help or hindrance to your aims and can be used as such.
.sp
You can basically use any SELECT query that gets you the information, you
could even do joins or subqueries in case your minion_id is stored elsewhere.
It is capable of handling single rows or multiple rows per minion.
.sp
MySQL configuration of the MySQL returner is being used (mysql.db, mysql.user,
mysql.pass, mysql.port, mysql.host)
.sp
Required python modules: MySQLdb
.SS More complete example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mysql:
user: \(aqsalt\(aq
pass: \(aqsuper_secret_password\(aq
db: \(aqsalt_db\(aq
ext_pillar:
\- mysql:
fromdb:
query: \(aqSELECT col1,col2,col3,col4,col5,col6,col7
FROM some_random_table
WHERE minion_pattern LIKE %s\(aq
depth: 5
as_list: True
with_lists: [1,3]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.mysql.ext_pillar(minion_id, pillar, *args, **kwargs)
Execute queries, merge and return as a dict
.UNINDENT
.INDENT 0.0
.TP
.B class salt.pillar.mysql.merger
This class receives and processes the database rows in a database
agnostic way.
.INDENT 7.0
.TP
.B as_list = False
.UNINDENT
.INDENT 7.0
.TP
.B depth = 0
.UNINDENT
.INDENT 7.0
.TP
.B enter_root(root)
Set self.focus for kwarg queries
.UNINDENT
.INDENT 7.0
.TP
.B extract_queries(args, kwargs)
This function normalizes the config block in to a set of queries we
can use. The return is a list of consistently laid out dicts.
.UNINDENT
.INDENT 7.0
.TP
.B field_names = None
.UNINDENT
.INDENT 7.0
.TP
.B focus = None
.UNINDENT
.INDENT 7.0
.TP
.B num_fields = 0
.UNINDENT
.INDENT 7.0
.TP
.B process_fields(field_names, depth)
The primary purpose of this function is to store the sql field list
and the depth to which we process.
.UNINDENT
.INDENT 7.0
.TP
.B process_results(rows)
This function takes a list of database results and iterates over,
merging them in to a dict form.
.UNINDENT
.INDENT 7.0
.TP
.B result = None
.UNINDENT
.INDENT 7.0
.TP
.B with_lists = None
.UNINDENT
.UNINDENT
.SS salt.pillar.pillar_ldap
.sp
Use LDAP data as a Pillar source
.sp
This pillar module parses a config file (specified in the salt master config),
and executes a series of LDAP searches based on that config. Data returned by
these searches is aggregated, with data items found later in the LDAP search
order overriding data found earlier on.
.sp
The final result set is merged with the pillar data.
.INDENT 0.0
.TP
.B salt.pillar.pillar_ldap.ext_pillar(minion_id, pillar, config_file)
Execute LDAP searches and return the aggregated data
.UNINDENT
.SS salt.pillar.puppet
.sp
Execute an unmodified puppet_node_classifier and read the output as YAML. The YAML data is then directly overlaid onto the minion\(aqs Pillar data.
.INDENT 0.0
.TP
.B salt.pillar.puppet.ext_pillar(minion_id, pillar, command)
Execute an unmodified puppet_node_classifier and read the output as YAML
.UNINDENT
.SS salt.pillar.reclass_adapter
.sp
Use the "reclass" database as a Pillar source
.sp
This \fBext_pillar\fP plugin provides access to the \fBreclass\fP database, such
that Pillar data for a specific minion are fetched using \fBreclass\fP\&.
.sp
You can find more information about \fBreclass\fP at
\fI\%http://reclass.pantsfullofunix.net\fP\&.
.sp
To use the plugin, add it to the \fBext_pillar\fP list in the Salt master config
and tell \fBreclass\fP by way of a few options how and where to find the
inventory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- reclass:
storage_type: yaml_fs
inventory_base_uri: /srv/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would cause \fBreclass\fP to read the inventory from YAML files in
\fB/srv/salt/nodes\fP and \fB/srv/salt/classes\fP\&.
.sp
If you are also using \fBreclass\fP as \fBmaster_tops\fP plugin, and you want to
avoid having to specify the same information for both, use YAML anchors (take
note of the differing data types for \fBext_pillar\fP and \fBmaster_tops\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
reclass: &reclass
storage_type: yaml_fs
inventory_base_uri: /srv/salt
reclass_source_path: ~/code/reclass
ext_pillar:
\- reclass: *reclass
master_tops:
reclass: *reclass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you want to run reclass from source, rather than installing it, you can
either let the master know via the \fBPYTHONPATH\fP environment variable, or by
setting the configuration option, like in the example above.
.INDENT 0.0
.TP
.B salt.pillar.reclass_adapter.ext_pillar(minion_id, pillar, **kwargs)
Obtain the Pillar data from \fBreclass\fP for the given \fBminion_id\fP\&.
.UNINDENT
.SS salt.pillar.redismod
.SS Read pillar data from a Redis backend
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
redis Python module (on master)
.UNINDENT
.UNINDENT
.SS Salt Master Redis Configuration
.sp
The module shares the same base Redis connection variables as
\fBsalt.returners.redis_return\fP\&. These variables go in your master
config file.
.INDENT 0.0
.IP \(bu 2
\fBredis.db\fP \- The Redis database to use. Defaults to \fB0\fP\&.
.IP \(bu 2
\fBredis.host\fP \- The Redis host to connect to. Defaults to \fB\(aqsalt\(aq\fP\&.
.IP \(bu 2
\fBredis.port\fP \- The port that the Redis database is listening on. Defaults
to \fB6379\fP\&.
.IP \(bu 2
\fBredis.password\fP \- The password for authenticating with Redis. Only
required if you are using master auth. Defaults to \fBNone\fP\&.
.UNINDENT
.SS Configuring the Redis ext_pillar
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- redis: {function: key_value}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.redismod.ext_pillar(minion_id, pillar, function, **kwargs)
Grabs external pillar data based on configured function
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.redismod.key_json(minion_id, pillar, pillar_key=None)
Pulls a string from redis and deserializes it from json. Deserialized
dictionary data loaded directly into top level if pillar_key is not set.
.INDENT 7.0
.TP
.B pillar_key
Pillar key to return data into
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.redismod.key_value(minion_id, pillar, pillar_key=\(aqredis_pillar\(aq)
Looks for key in redis matching minion_id, returns a structure based on the
data type of the redis key. String for string type, dict for hash type and
lists for lists, sets and sorted sets.
.INDENT 7.0
.TP
.B pillar_key
Pillar key to return data into
.UNINDENT
.UNINDENT
.SS salt.pillar.s3
.sp
Copy pillar data from a bucket in Amazon S3
.sp
The S3 pillar can be configured in the master config file with the following
options
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- s3:
bucket: my.fancy.pillar.bucket
keyid: KASKFJWAKJASJKDAJKSD
key: ksladfDLKDALSFKSD93q032sdDasdfasdflsadkf
multiple_env: False
environment: base
verify_ssl: True
service_url: s3.amazonaws.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIbucket=\fP parameter specifies the target S3 bucket. It is required.
.sp
The \fIkeyid=\fP parameter specifies the key id to use when access the S3 bucket.
It is required.
.sp
The \fIkey=\fP parameter specifies the key to use when access the S3 bucket. It
is required.
.sp
The \fImultiple_env=\fP defaults to False. It specifies whether the pillar should
interpret top level folders as pillar environments (see mode section below).
.sp
The \fIenvironment=\fP defaults to \(aqbase\(aq. It specifies which environment the
bucket represents when in single environments mode (see mode section below). It
is ignored if multiple_env is True.
.sp
The \fIverify_ssl=\fP parameter defaults to True. It specifies whether to check for
valid S3 SSL certificates. \fINOTE\fP If you use bucket names with periods, this
must be set to False else an invalid certificate error will be thrown (issue
#12200).
.sp
The \fIservice_url=\fP parameter defaults to \(aqs3.amazonaws.com\(aq. It specifies the
base url to use for accessing S3.
.sp
This pillar can operate in two modes, single environment per bucket or multiple
environments per bucket.
.sp
Single environment mode must have this bucket structure:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
s3://<bucket name>/<files>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple environment mode must have this bucket structure:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
s3://<bucket name>/<environment>/<files>
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.pillar.s3.S3Credentials(key, keyid, bucket, service_url, verify_ssl=True)
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.s3.ext_pillar(minion_id, pillar, bucket, key, keyid, verify_ssl, multiple_env=False, environment=\(aqbase\(aq, service_url=None)
Execute a command and read the output as YAML
.UNINDENT
.SS salt.pillar.svn_pillar
.sp
Clone a remote SVN repository and use the filesystem as a Pillar source
.sp
This external Pillar source can be configured in the master config file like
so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- svn: trunk svn://svnserver/repo root=subdirectory
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIroot=\fP parameter is optional and used to set the subdirectory from where
to look for Pillar files (such as \fBtop.sls\fP).
.sp
Changed in version 2014.7.0: The optional \fBroot\fP parameter will be added.
.sp
Note that this is not the same thing as configuring pillar data using the
\fBpillar_roots\fP parameter. The branch referenced in the
\fBext_pillar\fP entry above (\fBmaster\fP), would evaluate to the
\fBbase\fP environment, so this branch needs to contain a \fBtop.sls\fP with a
\fBbase\fP section in it, like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- foo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To use other environments from the same SVN repo as svn_pillar sources, just
add additional lines, like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- svn: trunk svn://svnserver/repo
\- svn: dev svn://svnserver/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this case, the \fBdev\fP branch would need its own \fBtop.sls\fP with a \fBdev\fP
section in it, like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dev:
\(aq*\(aq:
\- bar
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.pillar.svn_pillar.SvnPillar(branch, repo_location, root, opts)
Deal with the remote SVN repository for Pillar
.INDENT 7.0
.TP
.B pillar_dir()
Returns the directory of the pillars (repo cache + branch + root)
.UNINDENT
.INDENT 7.0
.TP
.B update()
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.pillar.svn_pillar.ext_pillar(minion_id, pillar, repo_string)
Execute a command and read the output as YAML
.UNINDENT
.SS salt.pillar.virtkey
.sp
Accept a key from a hypervisor if the virt runner has already submitted an authorization request
.INDENT 0.0
.TP
.B salt.pillar.virtkey.ext_pillar(hyper_id, pillar, name, key)
Accept the key for the VM on the hyper, if authorized.
.UNINDENT
.SS Renderers
.sp
The Salt state system operates by gathering information from common data
types such as lists, dictionaries and strings that would be familiar
to any developer.
.sp
SLS files are translated from whatever data templating format they are written
in back into Python data types to be consumed by Salt.
.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,
\fBWempy + YAML\fP, \fBJinja + json\fP, \fBMako + json\fP and \fBWempy + json\fP\&.
.sp
Renderers can be written to support any template type. 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 Pythonic data structure used by the state
system.
.SS Multiple Renderers
.sp
A default renderer is selected in the master configuration file by providing
a value to the \fBrenderer\fP key.
.sp
When evaluating an SLS, more than one renderer can be used.
.sp
When rendering SLS files, Salt checks for the presence of a Salt\-specific
shebang line.
.sp
The shebang line directly calls the name of the renderer as it is specified
within Salt. One of the most common reasons to use multiple renderers is to
use the Python or \fBpy\fP renderer.
.sp
Below, the first line is a shebang that references the \fBpy\fP renderer.
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.SS Composing Renderers
.sp
A renderer can be composed from other renderers by connecting them in a series
of pipes(\fB|\fP).
.sp
In fact, the default \fBJinja + YAML\fP renderer is implemented by connecting a YAML
renderer to a Jinja renderer. Such renderer configuration is specified as: \fBjinja | yaml\fP\&.
.sp
Other renderer combinations are possible:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fByaml\fP
i.e, just YAML, no templating.
.TP
.B \fBmako | yaml\fP
pass the input to the \fBmako\fP renderer, whose output is then fed into the
\fByaml\fP renderer.
.TP
.B \fBjinja | mako | yaml\fP
This one allows you to use both jinja and mako templating syntax in the
input and then parse the final rendered output as YAML.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The following is a contrived example SLS file using the \fBjinja | mako | yaml\fP renderer:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!jinja|mako|yaml
An_Example:
cmd.run:
\- name: |
echo "Using Salt ${grains[\(aqsaltversion\(aq]}" \e
"from path {{grains[\(aqsaltpath\(aq]}}."
\- cwd: /
<%doc> ${...} is Mako\(aqs notation, and so is this comment. </%doc>
{# Similarly, {{...}} is Jinja\(aqs notation, and so is this comment. #}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For backward compatibility, \fBjinja | yaml\fP can also be written as
\fByaml_jinja\fP, and similarly, the \fByaml_mako\fP, \fByaml_wempy\fP,
\fBjson_jinja\fP, \fBjson_mako\fP, and \fBjson_wempy\fP renderers are all supported.
.sp
Keep in mind that not all renderers can be used alone or with any other renderers.
For example, the template renderers shouldn\(aqt be used alone as their outputs are
just strings, which still need to be parsed by another renderer to turn them into
highstate data structures.
.sp
For example, it doesn\(aqt make sense to specify \fByaml | jinja\fP because the
output of the YAML renderer is a highstate data structure (a dict in Python), which
cannot be used as the input to a template renderer. Therefore, when combining
renderers, you should know what each renderer accepts as input and what it returns
as output.
.SS Writing Renderers
.sp
A custom renderer must be a Python module placed in the rendered directory and the
module implement the \fBrender\fP function.
.sp
The \fBrender\fP function will be passed the path of the SLS file as an argument.
.sp
The purpose of of \fBrender\fP function is to parse the passed file and to return
the Python data structure derived from the file.
.sp
Custom renderers must be placed in a \fB_renderers\fP directory within the
\fBfile_roots\fP specified by the master config file.
.INDENT 0.0
.TP
.B Custom renderers are distributed when any of the following are run:
\fBstate.highstate\fP
.sp
\fBsaltutil.sync_renderers\fP
.sp
\fBsaltutil.sync_all\fP
.UNINDENT
.sp
Any custom renderers which have been synced to a minion, that are named the
same as one of Salt\(aqs default set of renderers, will take the place of the
default renderer with the same name.
.SS Examples
.sp
The best place to find examples of renderers is in the Salt source code.
.sp
Documentation for renderers included with Salt can be found here:
.sp
\fI\%https://github.com/saltstack/salt/blob/develop/salt/renderers\fP
.sp
Here is a simple YAML renderer example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import yaml
def render(yaml_data, env=\(aq\(aq, sls=\(aq\(aq, **kws):
if not isinstance(yaml_data, basestring):
yaml_data = yaml_data.read()
data = yaml.load(yaml_data)
return data if data else {}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Full List of Renderers
.SS Full list of builtin renderer modules
.TS
center;
|l|l|.
_
T{
\fBgpg\fP
T} T{
Renderer that will decrypt GPG ciphers
T}
_
T{
\fBjinja\fP
T} T{
Jinja loading utils to enable a more powerful backend for jinja templates
T}
_
T{
\fBjson\fP
T} T{
JSON Renderer for Salt
T}
_
T{
\fBmako\fP
T} T{
Mako Renderer for Salt
T}
_
T{
\fBmsgpack\fP
T} T{
T}
_
T{
\fBpy\fP
T} T{
Pure python state renderer
T}
_
T{
\fBpydsl\fP
T} T{
A Python\-based DSL
T}
_
T{
\fBpyobjects\fP
T} T{
Python renderer that includes a Pythonic Object based interface
T}
_
T{
\fBstateconf\fP
T} T{
A flexible renderer that takes a templating engine and a data format
T}
_
T{
\fBwempy\fP
T} T{
T}
_
T{
\fByaml\fP
T} T{
YAML Renderer for Salt
T}
_
T{
\fByamlex\fP
T} T{
T}
_
.TE
.SS salt.renderers.gpg
.sp
Renderer that will decrypt GPG ciphers
.sp
Any key in the SLS file can be a GPG cipher, and this renderer will decrypt
it before passing it off to Salt. This allows you to safely store secrets in
source control, in such a way that only your Salt master can decrypt them and
distribute them only to the minions that need them.
.sp
The typical use\-case would be to use ciphers in your pillar data, and keep a
secret key on your master. You can put the public key in source control so that
developers can add new secrets quickly and easily.
.sp
This renderer requires the python\-gnupg package. Be careful to install the
\fBpython\-gnupg\fP package, not the \fBgnupg\fP package, or you will get errors.
.sp
To set things up, you will first need to generate a keypair. On your master,
run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# gpg \-\-gen\-key \-\-homedir /etc/salt/gpgkeys
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Do not supply a password for your keypair, and use a name that makes sense
for your application. Be sure to back up your gpg directory someplace safe!
.sp
To retrieve the public key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# gpg \-\-armor \-\-homedir /etc/salt/gpgkeys \-\-armor \-\-export <KEY\-NAME> > exported_pubkey.gpg
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now, to encrypt secrets, copy the public key to your local machine and run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ gpg \-\-import exported_pubkey.gpg
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To generate a cipher from a secret:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo \-n"supersecret" | gpg \-\-homedir \-\-armor \-\-encrypt \-r <KEY\-name>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Set up the renderer on your master by adding something like this line to your
config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
renderer: jinja | yaml | gpg
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now you can include your ciphers in your pillar data like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
a\-secret: |
\-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\-
Version: GnuPG v1
hQEMAweRHKaPCfNeAQf9GLTN16hCfXAbPwU6BbBK0unOc7i9/etGuVc5CyU9Q6um
QuetdvQVLFO/HkrC4lgeNQdM6D9E8PKonMlgJPyUvC8ggxhj0/IPFEKmrsnv2k6+
cnEfmVexS7o/U1VOVjoyUeliMCJlAz/30RXaME49Cpi6No2+vKD8a4q4nZN1UZcG
RhkhC0S22zNxOXQ38TBkmtJcqxnqT6YWKTUsjVubW3bVC+u2HGqJHu79wmwuN8tz
m4wBkfCAd8Eyo2jEnWQcM4TcXiF01XPL4z4g1/9AAxh+Q4d8RIRP4fbw7ct4nCJv
Gr9v2DTF7HNigIMl4ivMIn9fp+EZurJNiQskLgNbktJGAeEKYkqX5iCuB1b693hJ
FKlwHiJt5yA8X2dDtfk8/Ph1Jx2TwGS+lGjlZaNqp3R1xuAZzXzZMLyZDe5+i3RJ
skqmFTbOiA==
=Eqsm
\-\-\-\-\-END PGP MESSAGE\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.gpg.decrypt_ciphertext(c, gpg)
Given a block of ciphertext as a string, and a gpg object, try to decrypt
the cipher and return the decrypted string. If the cipher cannot be
decrypted, log the error, and return the ciphertext back out.
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.gpg.decrypt_object(o, gpg)
Recursively try to decrypt any object. If the object is a string, and
it contains a valid GPG header, decrypt it, otherwise keep going until
a string is found.
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.gpg.render(data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, **kwargs)
Create a gpg object given a gpg_keydir, and then use it to try to decrypt
the data to be rendered.
.UNINDENT
.SS salt.renderers.jinja
.sp
Jinja loading utils to enable a more powerful backend for jinja templates
.SS Jinja in States
.sp
The most basic usage of Jinja in state files is using control structures to
wrap conditional or redundant state elements:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if grains[\(aqos\(aq] != \(aqFreeBSD\(aq %}
tcsh:
pkg:
\- installed
{% endif %}
motd:
file.managed:
{% if grains[\(aqos\(aq] == \(aqFreeBSD\(aq %}
\- name: /etc/motd
{% elif grains[\(aqos\(aq] == \(aqDebian\(aq %}
\- name: /etc/motd.tail
{% endif %}
\- source: salt://motd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, the first if block will only be evaluated on minions that
aren\(aqt running FreeBSD, and the second block changes the file name based on the
\fIos\fP grain.
.sp
Writing \fBif\-else\fP blocks can lead to very redundant state files however. In
this case, using \fBpillars\fP, or using a previously
defined variable might be easier:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set motd = [\(aq/etc/motd\(aq] %}
{% if grains[\(aqos\(aq] == \(aqDebian\(aq %}
{% set motd = [\(aq/etc/motd.tail\(aq, \(aq/var/run/motd\(aq] %}
{% endif %}
{% for motdfile in motd %}
{{ motdfile }}:
file.managed:
\- source: salt://motd
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using a variable set by the template, the \fI\%for loop\fP will iterate over the
list of MOTD files to update, adding a state block for each file.
.SS Include and Import
.sp
Includes and \fI\%imports\fP can be used to share common, reusable state configuration
between state files and between files.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% from \(aqlib.sls\(aq import test %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would import the \fBtest\fP template variable or macro, not the \fBtest\fP
state element, from the file \fBlib.sls\fP\&. In the case that the included file
performs checks again grains, or something else that requires context, passing
the context into the included file is required:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% from \(aqlib.sls\(aq import test with context %}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Macros
.sp
\fI\%Macros\fP are helpful for eliminating redundant code, however stripping whitespace
from the template block, as well as contained blocks, may be necessary to
emulate a variable return from the macro.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# init.sls
{% from \(aqlib.sls\(aq import pythonpkg with context %}
python\-virtualenv:
pkg.installed:
\- name: {{ pythonpkg(\(aqvirtualenv\(aq) }}
python\-fabric:
pkg.installed:
\- name: {{ pythonpkg(\(aqfabric\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# lib.sls
{% macro pythonpkg(pkg) \-%}
{%\- if grains[\(aqos\(aq] == \(aqFreeBSD\(aq \-%}
py27\-{{ pkg }}
{%\- elif grains[\(aqos\(aq] == \(aqDebian\(aq \-%}
python\-{{ pkg }}
{%\- endif \-%}
{%\- endmacro %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would define a \fI\%macro\fP that would return a string of the full package name,
depending on the packaging system\(aqs naming convention. The whitespace of the
macro was eliminated, so that the macro would return a string without line
breaks, using \fI\%whitespace control\fP\&.
.SS Template Inheritance
.sp
\fI\%Template inheritance\fP works fine from state files and files. The search path
starts at the root of the state tree or pillar.
.SS Filters
.sp
Saltstack extends \fI\%builtin filters\fP with his custom filters:
.INDENT 0.0
.TP
.B strftime
Converts any time related object into a time based string. It requires a
valid \fI\%strftime directives\fP\&. An
\fI\%exhaustive list\fP can be found in
the official Python documentation. Fuzzy dates are parsed by \fI\%timelib\fP python
module. Some examples are available on this pages.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{{ "2002/12/25"|strftime("%y") }}
{{ "1040814000"|strftime("%Y\-%m\-%d") }}
{{ datetime|strftime("%u") }}
{{ "now"|strftime }}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Jinja in Files
.sp
\fI\%Jinja\fP can be used in the same way in managed files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# redis.sls
/etc/redis/redis.conf:
file.managed:
\- source: salt://redis.conf
\- template: jinja
\- context:
bind: 127.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# lib.sls
{% set port = 6379 %}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# redis.conf
{% from \(aqlib.sls\(aq import port with context %}
port {{ port }}
bind {{ bind }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As an example, configuration was pulled from the file context and from an
external template file.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Macros and variables can be shared across templates. They should not be
starting with one or more underscores, and should be managed by one of the
following tags: \fImacro\fP, \fIset\fP, \fIload_yaml\fP, \fIload_json\fP, \fIimport_yaml\fP and
\fIimport_json\fP\&.
.UNINDENT
.UNINDENT
.SS Calling Salt Functions
.sp
The Jinja renderer provides a shorthand lookup syntax for the \fBsalt\fP
dictionary of \fIexecution function\fP\&.
.sp
New in version 2014.7.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# The following two function calls are equivalent.
{{ salt[\(aqcmd.run\(aq](\(aqwhoami\(aq) }}
{{ salt.cmd.run(\(aqwhoami\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Debugging
.sp
The \fBshow_full_context\fP function can be used to output all variables present
in the current Jinja context.
.sp
New in version 2014.7.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Context is: {{ show_full_context() }}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.jinja.render(template_file, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, context=None, tmplpath=None, **kws)
Render the template_file, passing the functions and grains into the
Jinja rendering system.
.INDENT 7.0
.TP
.B Return type
string
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.utils.jinja.SerializerExtension(environment)
Yaml and Json manipulation.
.sp
\fBFormat filters\fP
.sp
Allows to jsonify or yamlify any data structure. For example, this dataset:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
data = {
\(aqfoo\(aq: True,
\(aqbar\(aq: 42,
\(aqbaz\(aq: [1, 2, 3],
\(aqqux\(aq: 2.0
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
yaml = {{ data|yaml }}
json = {{ data|json }}
python = {{ data|python }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will be rendered as:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
yaml = {bar: 42, baz: [1, 2, 3], foo: true, qux: 2.0}
json = {"baz": [1, 2, 3], "foo": true, "bar": 42, "qux": 2.0}
python = {\(aqbar\(aq: 42, \(aqbaz\(aq: [1, 2, 3], \(aqfoo\(aq: True, \(aqqux\(aq: 2.0}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The yaml filter takes an optional flow_style parameter to control the
default\-flow\-style parameter of the YAML dumper.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{{ data|yaml(False) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will be rendered as:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
bar: 42
baz:
\- 1
\- 2
\- 3
foo: true
qux: 2.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBLoad filters\fP
.sp
Strings and variables can be deserialized with \fBload_yaml\fP and
\fBload_json\fP tags and filters. It allows one to manipulate data directly
in templates, easily:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{%\- set yaml_src = "{foo: it works}"|load_yaml %}
{%\- set json_src = "{\(aqbar\(aq: \(aqfor real\(aq}"|load_yaml %}
Dude, {{ yaml_src.foo }} {{ json_src.bar }}!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will be rendered has:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
Dude, it works for real!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBLoad tags\fP
.sp
Salt implements \fBimport_yaml\fP and \fBimport_json\fP tags. They work like
the \fI\%import tag\fP, except that the document is also deserialized.
.sp
Syntaxes are {% load_yaml as [VARIABLE] %}[YOUR DATA]{% endload %}
and {% load_json as [VARIABLE] %}[YOUR DATA]{% endload %}
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% load_yaml as yaml_src %}
foo: it works
{% endload %}
{% load_json as json_src %}
{
"bar": "for real"
}
{% endload %}
Dude, {{ yaml_src.foo }} {{ json_src.bar }}!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will be rendered has:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
Dude, it works for real!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBImport tags\fP
.sp
External files can be imported and made available as a Jinja variable.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% import_yaml "myfile.yml" as myfile %}
{% import_json "defaults.json" as defaults %}
{% import_text "completeworksofshakespeare.txt" as poems %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBCatalog\fP
.sp
\fBimport_*\fP and \fBload_*\fP tags will automatically expose their
target variable to import. This feature makes catalog of data to
handle.
.sp
for example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# doc1.sls
{% load_yaml as var1 %}
foo: it works
{% endload %}
{% load_yaml as var2 %}
bar: for real
{% endload %}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# doc2.sls
{% from "doc1.sls" import var1, var2 as local2 %}
{{ var1.foo }} {{ local2.bar }}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.renderers.json
.sp
JSON Renderer for Salt
.INDENT 0.0
.TP
.B salt.renderers.json.render(json_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws)
Accepts JSON as a string or as a file object and runs it through the JSON
parser.
.INDENT 7.0
.TP
.B Return type
A Python data structure
.UNINDENT
.UNINDENT
.SS salt.renderers.mako
.sp
Mako Renderer for Salt
.INDENT 0.0
.TP
.B salt.renderers.mako.render(template_file, saltenv=\(aqbase\(aq, sls=\(aq\(aq, context=None, tmplpath=None, **kws)
Render the template_file, passing the functions and grains into the
Mako rendering system.
.INDENT 7.0
.TP
.B Return type
string
.UNINDENT
.UNINDENT
.SS salt.renderers.msgpack
.INDENT 0.0
.TP
.B salt.renderers.msgpack.render(msgpack_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws)
Accepts a message pack string or a file object, renders said data back to
a python dict.
.INDENT 7.0
.TP
.B Return type
A Python data structure
.UNINDENT
.UNINDENT
.SS salt.renderers.py
.sp
Pure python state renderer
.sp
The SLS file should contain a function called \fBrun\fP which returns high state
data.
.sp
In this module, a few objects are defined for you, giving access to Salt\(aqs
execution functions, grains, pillar, etc. They are:
.INDENT 0.0
.IP \(bu 2
\fB__salt__\fP \- \fIExecution functions\fP (i.e.
\fB__salt__[\(aqtest.echo\(aq](\(aqfoo\(aq)\fP)
.IP \(bu 2
\fB__grains__\fP \- \fIGrains\fP (i.e. \fB__grains__[\(aqos\(aq]\fP)
.IP \(bu 2
\fB__pillar__\fP \- \fIPillar data\fP (i.e. \fB__pillar__[\(aqfoo\(aq]\fP)
.IP \(bu 2
\fB__opts__\fP \- Minion configuration options
.IP \(bu 2
\fB__env__\fP \- The effective salt fileserver environment (i.e. \fBbase\fP). Also
referred to as a "saltenv". \fB__env__\fP should not be modified in a pure
python SLS file. To use a different environment, the environment should be
set when executing the state. This can be done in a couple different ways:
.INDENT 2.0
.IP \(bu 2
Using the \fBsaltenv\fP argument on the salt CLI (i.e. \fBsalt \(aq*\(aq state.sls foo.bar.baz saltenv=env_name\fP).
.IP \(bu 2
By adding a \fBsaltenv\fP argument to an individual state within the SLS
file. In other words, adding a line like this to the state\(aqs data
structure: \fB{\(aqsaltenv\(aq: \(aqenv_name\(aq}\fP
.UNINDENT
.IP \(bu 2
\fB__sls__\fP \- The SLS path of the file. For example, if the root of the base
environment is \fB/srv/salt\fP, and the SLS file is
\fB/srv/salt/foo/bar/baz.sls\fP, then \fB__sls__\fP in that file will be
\fBfoo.bar.baz\fP\&.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!py
def run():
config = {}
if __grains__[\(aqos\(aq] == \(aqUbuntu\(aq:
user = \(aqubuntu\(aq
group = \(aqubuntu\(aq
home = \(aq/home/{0}\(aq.format(user)
else:
user = \(aqroot\(aq
group = \(aqroot\(aq
home = \(aq/root/\(aq
config[\(aqs3cmd\(aq] = {
\(aqpkg\(aq: [
\(aqinstalled\(aq,
{\(aqname\(aq: \(aqs3cmd\(aq},
],
}
config[home + \(aq/.s3cfg\(aq] = {
\(aqfile.managed\(aq: [
{\(aqsource\(aq: \(aqsalt://s3cfg/templates/s3cfg\(aq},
{\(aqtemplate\(aq: \(aqjinja\(aq},
{\(aquser\(aq: user},
{\(aqgroup\(aq: group},
{\(aqmode\(aq: 600},
{\(aqcontext\(aq: {
\(aqaws_key\(aq: __pillar__[\(aqAWS_ACCESS_KEY_ID\(aq],
\(aqaws_secret_key\(aq: __pillar__[\(aqAWS_SECRET_ACCESS_KEY\(aq],
},
},
],
}
return config
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.py.render(template, saltenv=\(aqbase\(aq, sls=\(aq\(aq, tmplpath=None, **kws)
Render the python module\(aqs components
.INDENT 7.0
.TP
.B Return type
string
.UNINDENT
.UNINDENT
.SS salt.renderers.pydsl
.sp
A Python\-based DSL
.INDENT 0.0
.TP
.B maintainer
Jack Kuan <\fI\%kjkuan@gmail.com\fP>
.TP
.B maturity
new
.TP
.B platform
all
.UNINDENT
.sp
The \fIpydsl\fP renderer allows one to author salt formulas (.sls files) in pure
Python using a DSL that\(aqs easy to write and easy to read. Here\(aqs an example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pydsl
apache = state(\(aqapache\(aq)
apache.pkg.installed()
apache.service.running()
state(\(aq/var/www/index.html\(aq) \e
.file(\(aqmanaged\(aq,
source=\(aqsalt://webserver/index.html\(aq) \e
.require(pkg=\(aqapache\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice that any Python code is allow in the file as it\(aqs really a Python
module, so you have the full power of Python at your disposal. In this module,
a few objects are defined for you, including the usual (with \fB__\fP added)
\fB__salt__\fP dictionary, \fB__grains__\fP, \fB__pillar__\fP, \fB__opts__\fP,
\fB__env__\fP, and \fB__sls__\fP, plus a few more:
.INDENT 0.0
.INDENT 3.5
\fB__file__\fP
.INDENT 0.0
.INDENT 3.5
local file system path to the sls module.
.UNINDENT
.UNINDENT
.sp
\fB__pydsl__\fP
.INDENT 0.0
.INDENT 3.5
Salt PyDSL object, useful for configuring DSL behavior per sls rendering.
.UNINDENT
.UNINDENT
.sp
\fBinclude\fP
.INDENT 0.0
.INDENT 3.5
Salt PyDSL function for creating \fIinclude\-declaration\fP\(aqs.
.UNINDENT
.UNINDENT
.sp
\fBextend\fP
.INDENT 0.0
.INDENT 3.5
Salt PyDSL function for creating \fIextend\-declaration\fP\(aqs.
.UNINDENT
.UNINDENT
.sp
\fBstate\fP
.INDENT 0.0
.INDENT 3.5
Salt PyDSL function for creating \fIID\-declaration\fP\(aqs.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
A state \fIID\-declaration\fP is created with a \fBstate(id)\fP function call.
Subsequent \fBstate(id)\fP call with the same id returns the same object. This
singleton access pattern applies to all declaration objects created with the
DSL.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state(\(aqexample\(aq)
assert state(\(aqexample\(aq) is state(\(aqexample\(aq)
assert state(\(aqexample\(aq).cmd is state(\(aqexample\(aq).cmd
assert state(\(aqexample\(aq).cmd.running is state(\(aqexample\(aq).cmd.running
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIid\fP argument is optional. If omitted, an UUID will be generated and used as
the \fIid\fP\&.
.sp
\fBstate(id)\fP returns an object under which you can create a
\fIstate\-declaration\fP object by accessing an attribute named after \fIany\fP
state module available in Salt.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state(\(aqexample\(aq).cmd
state(\(aqexample\(aq).file
state(\(aqexample\(aq).pkg
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, a \fIfunction\-declaration\fP object can be created from a
\fIstate\-declaration\fP object by one of the following two ways:
.INDENT 0.0
.IP 1. 3
by calling a method named after the state function on the \fIstate\-declaration\fP object.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state(\(aqexample\(aq).file.managed(...)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 2. 3
by directly calling the attribute named for the \fIstate\-declaration\fP, and
supplying the state function name as the first argument.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state(\(aqexample\(aq).file(\(aqmanaged\(aq, ...)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With either way of creating a \fIfunction\-declaration\fP object, any
\fIfunction\-arg\-declaration\fP\(aqs can be passed as keyword arguments to the
call. Subsequent calls of a \fIfunction\-declaration\fP will update the arg
declarations.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state(\(aqexample\(aq).file(\(aqmanaged\(aq, source=\(aqsalt://webserver/index.html\(aq)
state(\(aqexample\(aq).file.managed(source=\(aqsalt://webserver/index.html\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As a shortcut, the special \fIname\fP argument can also be passed as the
first or second positional argument depending on the first or second
way of calling the \fIstate\-declaration\fP object. In the following
two examples \fIls \-la\fP is the \fIname\fP argument.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state(\(aqexample\(aq).cmd.run(\(aqls \-la\(aq, cwd=\(aq/\(aq)
state(\(aqexample\(aq).cmd(\(aqrun\(aq, \(aqls \-la\(aq, cwd=\(aq/\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, a \fIrequisite\-declaration\fP object with its
\fIrequisite\-reference\fP\(aqs can be created by invoking one of the
requisite methods (see \fBState Requisites\fP) on either a \fIfunction\-declaration\fP
object or a \fIstate\-declaration\fP object. The return value of a
requisite call is also a \fIfunction\-declaration\fP object, so you
can chain several requisite calls together.
.sp
Arguments to a requisite call can be a list of \fIstate\-declaration\fP objects
and/or a set of keyword arguments whose names are state modules and values are
IDs of \fIID\-declaration\fP\(aqs or names of \fIname\-declaration\fP\(aqs.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache2 = state(\(aqapache2\(aq)
apache2.pkg.installed()
state(\(aqlibapache2\-mod\-wsgi\(aq).pkg.installed()
# you can call requisites on function declaration
apache2.service.running() \e
.require(apache2.pkg,
pkg=\(aqlibapache2\-mod\-wsgi\(aq) \e
.watch(file=\(aq/etc/apache2/httpd.conf\(aq)
# or you can call requisites on state declaration.
# this actually creates an anonymous function declaration object
# to add the requisites.
apache2.service.require(state(\(aqlibapache2\-mod\-wsgi\(aq).pkg,
pkg=\(aqapache2\(aq) \e
.watch(file=\(aq/etc/apache2/httpd.conf\(aq)
# we still need to set the name of the function declaration.
apache2.service.running()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fIinclude\-declaration\fP objects can be created with the \fBinclude\fP function,
while \fIextend\-declaration\fP objects can be created with the \fBextend\fP function,
whose arguments are just \fIfunction\-declaration\fP objects.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(\(aqedit.vim\(aq, \(aqhttp.server\(aq)
extend(state(\(aqapache2\(aq).service.watch(file=\(aq/etc/httpd/httpd.conf\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBinclude\fP function, by default, causes the included sls file to be rendered
as soon as the \fBinclude\fP function is called. It returns a list of rendered module
objects; sls files not rendered with the pydsl renderer return \fBNone\fP\(aqs.
This behavior creates no \fIinclude\-declaration\fP\(aqs in the resulting high state
data structure.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import types
# including multiple sls returns a list.
_, mod = include(\(aqa\-non\-pydsl\-sls\(aq, \(aqa\-pydsl\-sls\(aq)
assert _ is None
assert isinstance(slsmods[1], types.ModuleType)
# including a single sls returns a single object
mod = include(\(aqa\-pydsl\-sls\(aq)
# myfunc is a function that calls state(...) to create more states.
mod.myfunc(1, 2, "three")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice how you can define a reusable function in your pydsl sls module and then
call it via the module returned by \fBinclude\fP\&.
.sp
It\(aqs still possible to do late includes by passing the \fBdelayed=True\fP keyword
argument to \fBinclude\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(\(aqedit.vim\(aq, \(aqhttp.server\(aq, delayed=True)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Above will just create a \fIinclude\-declaration\fP in the rendered result, and
such call always returns \fBNone\fP\&.
.SS Special integration with the \fIcmd\fP state
.sp
Taking advantage of rendering a Python module, PyDSL allows you to declare a
state that calls a pre\-defined Python function when the state is executed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
greeting = "hello world"
def helper(something, *args, **kws):
print greeting # hello world
print something, args, kws # test123 [\(aqa\(aq, \(aqb\(aq, \(aqc\(aq] {\(aqx\(aq: 1, \(aqy\(aq: 2}
state().cmd.call(helper, "test123", \(aqa\(aq, \(aqb\(aq, \(aqc\(aq, x=1, y=2)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIcmd.call\fP state function takes care of calling our \fBhelper\fP function
with the arguments we specified in the states, and translates the return value
of our function into a structure expected by the state system.
See \fBsalt.states.cmd.call()\fP for more information.
.SS Implicit ordering of states
.sp
Salt states are explicitly ordered via \fIrequisite\-declaration\fP\(aqs.
However, with \fIpydsl\fP it\(aqs possible to let the renderer track the order
of creation for \fIfunction\-declaration\fP objects, and implicitly add
\fBrequire\fP requisites for your states to enforce the ordering. This feature
is enabled by setting the \fBordered\fP option on \fB__pydsl__\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
this feature is only available if your minions are using Python >= 2.7.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(\(aqsome.sls.file\(aq)
A = state(\(aqA\(aq).cmd.run(cwd=\(aq/var/tmp\(aq)
extend(A)
__pydsl__.set(ordered=True)
for i in range(10):
i = str(i)
state(i).cmd.run(\(aqecho \(aq+i, cwd=\(aq/\(aq)
state(\(aq1\(aq).cmd.run(\(aqecho one\(aq)
state(\(aq2\(aq).cmd.run(name=\(aqecho two\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice that the \fBordered\fP option needs to be set after any \fBextend\fP calls.
This is to prevent \fIpydsl\fP from tracking the creation of a state function that\(aqs
passed to an \fBextend\fP call.
.sp
Above example should create states from \fB0\fP to \fB9\fP that will output \fB0\fP,
\fBone\fP, \fBtwo\fP, \fB3\fP, ... \fB9\fP, in that order.
.sp
It\(aqs important to know that \fIpydsl\fP tracks the \fIcreations\fP of
\fIfunction\-declaration\fP objects, and automatically adds a \fBrequire\fP requisite
to a \fIfunction\-declaration\fP object that requires the last
\fIfunction\-declaration\fP object created before it in the sls file.
.sp
This means later calls (perhaps to update the function\(aqs \fIfunction\-arg\-declaration\fP) to a previously created function declaration will not change the
order.
.SS Render time state execution
.sp
When Salt processes a salt formula file, the file is rendered to salt\(aqs
high state data representation by a renderer before the states can be executed.
In the case of the \fIpydsl\fP renderer, the .sls file is executed as a python module
as it is being rendered which makes it easy to execute a state at render time.
In \fIpydsl\fP, executing one or more states at render time can be done by calling a
configured \fIID\-declaration\fP object.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pydsl
s = state() # save for later invocation
# configure it
s.cmd.run(\(aqecho at render time\(aq, cwd=\(aq/\(aq)
s.file.managed(\(aqtarget.txt\(aq, source=\(aqsalt://source.txt\(aq)
s() # execute the two states now
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once an \fIID\-declaration\fP is called at render time it is detached from the
sls module as if it was never defined.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If \fIimplicit ordering\fP is enabled (ie, via \fB__pydsl__.set(ordered=True)\fP) then
the \fIfirst\fP invocation of a \fIID\-declaration\fP object must be done before a
new \fIfunction\-declaration\fP is created.
.UNINDENT
.UNINDENT
.SS Integration with the stateconf renderer
.sp
The \fBsalt.renderers.stateconf\fP renderer offers a few interesting features that
can be leveraged by the \fIpydsl\fP renderer. In particular, when using with the \fIpydsl\fP
renderer, we are interested in \fIstateconf\fP\(aqs sls namespacing feature (via dot\-prefixed
id declarations), as well as, the automatic \fIstart\fP and \fIgoal\fP states generation.
.sp
Now you can use \fIpydsl\fP with \fIstateconf\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pydsl|stateconf \-ps
include(\(aqxxx\(aq, \(aqyyy\(aq)
# ensure that states in xxx run BEFORE states in this file.
extend(state(\(aq.start\(aq).stateconf.require(stateconf=\(aqxxx::goal\(aq))
# ensure that states in yyy run AFTER states in this file.
extend(state(\(aq.goal\(aq).stateconf.require_in(stateconf=\(aqyyy::start\(aq))
__pydsl__.set(ordered=True)
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB\-s\fP enables the generation of a stateconf \fIstart\fP state, and \fB\-p\fP lets us pipe
high state data rendered by \fIpydsl\fP to \fIstateconf\fP\&. This example shows that by
\fBrequire\fP\-ing or \fBrequire_in\fP\-ing the included sls\(aq \fIstart\fP or \fIgoal\fP states,
it\(aqs possible to ensure that the included sls files can be made to execute before
or after a state in the including sls file.
.SS Importing custom Python modules
.sp
To use a custom Python module inside a PyDSL state, place the module somewhere that
it can be loaded by the Salt loader, such as \fI_modules\fP in the \fI/srv/salt\fP directory.
.sp
Then, copy it to any minions as necessary by using \fIsaltutil.sync_modules\fP\&.
.sp
To import into a PyDSL SLS, one must bypass the Python importer and insert it manually
by getting a reference from Python\(aqs \fIsys.modules\fP dictionary.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pydsl|stateconf \-ps
def main():
my_mod = sys.modules[\(aqsalt.loaded.ext.module.my_mod\(aq]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.pydsl.render(template, saltenv=\(aqbase\(aq, sls=\(aq\(aq, tmplpath=None, rendered_sls=None, **kws)
.UNINDENT
.SS salt.renderers.pyobjects
.sp
Python renderer that includes a Pythonic Object based interface
.INDENT 0.0
.TP
.B maintainer
Evan Borgstrom <\fI\%evan@borgstrom.ca\fP>
.UNINDENT
.sp
Let\(aqs take a look at how you use pyobjects in a state file. Here\(aqs a quick
example that ensures the \fB/tmp\fP directory is in the correct state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
File.managed("/tmp", user=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq1777\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Nice and Pythonic!
.sp
By using the "shebang" syntax to switch to the pyobjects renderer we can now
write our state data using an object based interface that should feel at home
to python developers. You can import any module and do anything that you\(aqd
like (with caution, importing sqlalchemy, django or other large frameworks has
not been tested yet). Using the pyobjects renderer is exactly the same as
using the built\-in Python renderer with the exception that pyobjects provides
you with an object based interface for generating state data.
.SS Creating state data
.sp
Pyobjects takes care of creating an object for each of the available states on
the minion. Each state is represented by an object that is the CamelCase
version of its name (ie. \fBFile\fP, \fBService\fP, \fBUser\fP, etc), and these
objects expose all of their available state functions (ie. \fBFile.managed\fP,
\fBService.running\fP, etc).
.sp
The name of the state is split based upon underscores (\fB_\fP), then each part
is capitalized and finally the parts are joined back together.
.sp
Some examples:
.INDENT 0.0
.IP \(bu 2
\fBpostgres_user\fP becomes \fBPostgresUser\fP
.IP \(bu 2
\fBssh_known_hosts\fP becomes \fBSshKnownHosts\fP
.UNINDENT
.SS Context Managers and requisites
.sp
How about something a little more complex. Here we\(aqre going to get into the
core of how to use pyobjects to write states.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
with Pkg.installed("nginx"):
Service.running("nginx", enable=True)
with Service("nginx", "watch_in"):
File.managed("/etc/nginx/conf.d/mysite.conf",
owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0444\(aq,
source=\(aqsalt://nginx/mysite.conf\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The objects that are returned from each of the magic method calls are setup to
be used a Python context managers (\fBwith\fP) and when you use them as such all
declarations made within the scope will \fBautomatically\fP use the enclosing
state as a requisite!
.sp
The above could have also been written use direct requisite statements as.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
Pkg.installed("nginx")
Service.running("nginx", enable=True, require=Pkg("nginx"))
File.managed("/etc/nginx/conf.d/mysite.conf",
owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0444\(aq,
source=\(aqsalt://nginx/mysite.conf\(aq,
watch_in=Service("nginx"))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can use the direct requisite statement for referencing states that are
generated outside of the current file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
# some\-other\-package is defined in some other state file
Pkg.installed("nginx", require=Pkg("some\-other\-package"))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The last thing that direct requisites provide is the ability to select which
of the SaltStack requisites you want to use (require, require_in, watch,
watch_in, use & use_in) when using the requisite as a context manager.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
with Service("my\-service", "watch_in"):
...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above example would cause all declarations inside the scope of the context
manager to automatically have their \fBwatch_in\fP set to
\fBService("my\-service")\fP\&.
.SS Including and Extending
.sp
To include other states use the \fBinclude()\fP function. It takes one name per
state to include.
.sp
To extend another state use the \fBextend()\fP function on the name when creating
a state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
include(\(aqhttp\(aq, \(aqssh\(aq)
Service.running(extend(\(aqapache\(aq),
watch=[File(\(aq/etc/httpd/extra/httpd\-vhosts.conf\(aq)])
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Importing from other state files
.sp
Like any Python project that grows you will likely reach a point where you want
to create reusability in your state tree and share objects between state files,
Map Data (described below) is a perfect example of this.
.sp
To facilitate this Python\(aqs \fBimport\fP statement has been augmented to allow
for a special case when working with a Salt state tree. If you specify a Salt
url (\fBsalt://...\fP) as the target for importing from then the pyobjects
renderer will take care of fetching the file for you, parsing it with all of
the pyobjects features available and then place the requested objects in the
global scope of the template being rendered.
.sp
This works for both types of import statements, \fBimport X\fP and
\fBfrom X import Y\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
import salt://myfile.sls
from salt://something/data.sls import Object
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See the Map Data section for a more practical use.
.sp
Caveats:
.INDENT 0.0
.IP \(bu 2
You cannot use the \fBas\fP syntax, you can only import objects using their
existing name.
.IP \(bu 2
Imported objects are ALWAYS put into the global scope of your template,
regardless of where your import statement is.
.UNINDENT
.SS Salt object
.sp
In the spirit of the object interface for creating state data pyobjects also
provides a simple object interface to the \fB__salt__\fP object.
.sp
A function named \fBsalt\fP exists in scope for your sls files and will dispatch
its attributes to the \fB__salt__\fP dictionary.
.sp
The following lines are functionally equivalent:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
ret = salt.cmd.run(bar)
ret = __salt__[\(aqcmd.run\(aq](bar)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Pillar, grain, mine & config data
.sp
Pyobjects provides shortcut functions for calling \fBpillar.get\fP,
\fBgrains.get\fP, \fBmine.get\fP & \fBconfig.get\fP on the \fB__salt__\fP object. This
helps maintain the readability of your state files.
.sp
Each type of data can be access by a function of the same name: \fBpillar()\fP,
\fBgrains()\fP, \fBmine()\fP and \fBconfig()\fP\&.
.sp
The following pairs of lines are functionally equivalent:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
value = pillar(\(aqfoo:bar:baz\(aq, \(aqqux\(aq)
value = __salt__[\(aqpillar.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq)
value = grains(\(aqpkg:apache\(aq)
value = __salt__[\(aqgrains.get\(aq](\(aqpkg:apache\(aq)
value = mine(\(aqos:Fedora\(aq, \(aqnetwork.interfaces\(aq, \(aqgrain\(aq)
value = __salt__[\(aqmine.get\(aq](\(aqos:Fedora\(aq, \(aqnetwork.interfaces\(aq, \(aqgrain\(aq)
value = config(\(aqfoo:bar:baz\(aq, \(aqqux\(aq)
value = __salt__[\(aqconfig.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Map Data
.sp
When building complex states or formulas you often need a way of building up a
map of data based on grain data. The most common use of this is tracking the
package and service name differences between distributions.
.sp
To build map data using pyobjects we provide a class named Map that you use to
build your own classes with inner classes for each set of values for the
different grain matches.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
class Samba(Map):
merge = \(aqsamba:lookup\(aq
class Debian:
server = \(aqsamba\(aq
client = \(aqsamba\-client\(aq
service = \(aqsamba\(aq
class Ubuntu:
__grain__ = \(aqos\(aq
service = \(aqsmbd\(aq
class RedHat:
server = \(aqsamba\(aq
client = \(aqsamba\(aq
service = \(aqsmb\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To use this new data you can import it into your state file and then access
your attributes. To access the data in the map you simply access the attribute
name on the base class that is extending Map. Assuming the above Map was in the
file \fBsamba/map.sls\fP, you could do the following.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!pyobjects
from salt://samba/map.sls import Samba
with Pkg.installed("samba", names=[Samba.server, Samba.client]):
Service.running("samba", name=Samba.service)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS TODO
.INDENT 0.0
.IP \(bu 2
Interface for working with reactor files
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.pyobjects.load_states()
This loads our states into the salt __context__
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.pyobjects.render(template, saltenv=\(aqbase\(aq, sls=\(aq\(aq, salt_data=True, **kwargs)
.UNINDENT
.SS salt.renderers.stateconf
.INDENT 0.0
.TP
.B maintainer
Jack Kuan <\fI\%kjkuan@gmail.com\fP>
.TP
.B maturity
new
.TP
.B platform
all
.UNINDENT
.sp
This module provides a custom renderer that processes a salt file with a
specified templating engine (e.g., Jinja) and a chosen data renderer (e.g., YAML),
extracts arguments for any \fBstateconf.set\fP state, and provides the extracted
arguments (including Salt\-specific args, such as \fBrequire\fP, etc) as template
context. The goal is to make writing reusable/configurable/parameterized
salt files easier and cleaner.
.sp
To use this renderer, either set it as the default renderer via the
\fBrenderer\fP option in master/minion\(aqs config, or use the shebang line in each
individual sls file, like so: \fB#!stateconf\fP\&. Note, due to the way this
renderer works, it must be specified as the first renderer in a render
pipeline. That is, you cannot specify \fB#!mako|yaml|stateconf\fP, for example.
Instead, you specify them as renderer arguments: \fB#!stateconf mako . yaml\fP\&.
.sp
Here\(aqs a list of features enabled by this renderer.
.INDENT 0.0
.IP \(bu 2
Prefixes any state id (declaration or reference) that starts with a dot (\fB\&.\fP)
to avoid duplicated state ids when the salt file is included by other salt
files.
.sp
For example, in the \fIsalt://some/file.sls\fP, a state id such as \fB\&.sls_params\fP
will be turned into \fBsome.file::sls_params\fP\&. Example:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!stateconf yaml . jinja
\&.vim:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Above will be translated into:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
some.file::vim:
pkg.installed:
\- name: vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice how that if a state under a dot\-prefixed state id has no \fBname\fP
argument then one will be added automatically by using the state id with
the leading dot stripped off.
.sp
The leading dot trick can be used with extending state ids as well,
so you can include relatively and extend relatively. For example, when
extending a state in \fIsalt://some/other_file.sls\fP, e.g.,:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!stateconf yaml . jinja
include:
\- .file
extend:
.file::sls_params:
stateconf.set:
\- name1: something
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Above will be pre\-processed into:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- some.file
extend:
some.file::sls_params:
stateconf.set:
\- name1: something
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Adds a \fBsls_dir\fP context variable that expands to the directory containing
the rendering salt file. So, you can write \fBsalt://{{sls_dir}}/...\fP to
reference templates files used by your salt file.
.IP \(bu 2
Recognizes the special state function, \fBstateconf.set\fP, that configures a
default list of named arguments usable within the template context of
the salt file. Example:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!stateconf yaml . jinja
\&.sls_params:
stateconf.set:
\- name1: value1
\- name2: value2
\- name3:
\- value1
\- value2
\- value3
\- require_in:
\- cmd: output
# \-\-\- end of state config \-\-\-
\&.output:
cmd.run:
\- name: |
echo \(aqname1={{sls_params.name1}}
name2={{sls_params.name2}}
name3[1]={{sls_params.name3[1]}}
\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This even works with \fBinclude\fP + \fBextend\fP so that you can override
the default configured arguments by including the salt file and then
\fBextend\fP the \fBstateconf.set\fP states that come from the included salt
file. (\fIIMPORTANT: Both the included and the extending sls files must use the
stateconf renderer for this \(ga\(gaextend\(ga\(ga to work!\fP)
.sp
Notice that the end of configuration marker (\fB# \-\-\- end of state config \-\-\fP)
is needed to separate the use of \(aqstateconf.set\(aq form the rest of your salt
file. The regex that matches such marker can be configured via the
\fBstateconf_end_marker\fP option in your master or minion config file.
.sp
Sometimes, it is desirable to set a default argument value that\(aqs based on
earlier arguments in the same \fBstateconf.set\fP\&. For example, it may be
tempting to do something like this:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!stateconf yaml . jinja
\&.apache:
stateconf.set:
\- host: localhost
\- port: 1234
\- url: \(aqhttp://{{host}}:{{port}}/\(aq
# \-\-\- end of state config \-\-\-
\&.test:
cmd.run:
\- name: echo \(aq{{apache.url}}\(aq
\- cwd: /
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, this won\(aqt work. It can however be worked around like so:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!stateconf yaml . jinja
\&.apache:
stateconf.set:
\- host: localhost
\- port: 1234
{# \- url: \(aqhttp://{{host}}:{{port}}/\(aq #}
# \-\-\- end of state config \-\-\-
# {{ apache.setdefault(\(aqurl\(aq, "http://%(host)s:%(port)s/" % apache) }}
\&.test:
cmd.run:
\- name: echo \(aq{{apache.url}}\(aq
\- cwd: /
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Adds support for relative include and exclude of .sls files. Example:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
#!stateconf yaml . jinja
include:
\- .apache
\- .db.mysql
exclude:
\- sls: .users
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the above is written in a salt file at \fIsalt://some/where.sls\fP then
it will include \fIsalt://some/apache.sls\fP and \fIsalt://some/db/mysql.sls\fP,
and exclude \fIsalt://some/users.ssl\fP\&. Actually, it does that by rewriting
the above \fBinclude\fP and \fBexclude\fP into:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- some.apache
\- some.db.mysql
exclude:
\- sls: some.users
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Optionally (enabled by default, \fIdisable\fP via the \fI\-G\fP renderer option,
e.g., in the shebang line: \fB#!stateconf \-G\fP), generates a
\fBstateconf.set\fP goal state (state id named as \fB\&.goal\fP by default,
configurable via the master/minion config option, \fBstateconf_goal_state\fP)
that requires all other states in the salt file. Note, the \fB\&.goal\fP
state id is subject to dot\-prefix rename rule mentioned earlier.
.sp
Such goal state is intended to be required by some state in an including
salt file. For example, in your webapp salt file, if you include a
sls file that is supposed to setup Tomcat, you might want to make sure that
all states in the Tomcat sls file will be executed before some state in
the webapp sls file.
.IP \(bu 2
Optionally (enable via the \fI\-o\fP renderer option, e.g., in the shebang line:
\fB#!stateconf \-o\fP), orders the states in a sls file by adding a
\fBrequire\fP requisite to each state such that every state requires the
state defined just before it. The order of the states here is the order
they are defined in the sls file. (Note: this feature is only available
if your minions are using Python >= 2.7. For Python2.6, it should also
work if you install the \fIordereddict\fP module from PyPI)
.sp
By enabling this feature, you are basically agreeing to author your sls
files in a way that gives up the explicit (or implicit?) ordering imposed
by the use of \fBrequire\fP, \fBwatch\fP, \fBrequire_in\fP or \fBwatch_in\fP
requisites, and instead, you rely on the order of states you define in
the sls files. This may or may not be a better way for you. However, if
there are many states defined in a sls file, then it tends to be easier
to see the order they will be executed with this feature.
.sp
You are still allowed to use all the requisites, with a few restrictions.
You cannot \fBrequire\fP or \fBwatch\fP a state defined \fIafter\fP the current
state. Similarly, in a state, you cannot \fBrequire_in\fP or \fBwatch_in\fP
a state defined \fIbefore\fP it. Breaking any of the two restrictions above
will result in a state loop. The renderer will check for such incorrect
uses if this feature is enabled.
.sp
Additionally, \fBnames\fP declarations cannot be used with this feature
because the way they are compiled into low states make it impossible to
guarantee the order in which they will be executed. This is also checked
by the renderer. As a workaround for not being able to use \fBnames\fP,
you can achieve the same effect, by generate your states with the
template engine available within your sls file.
.sp
Finally, with the use of this feature, it becomes possible to easily make
an included sls file execute all its states \fIafter\fP some state (say, with
id \fBX\fP) in the including sls file. All you have to do is to make state,
\fBX\fP, \fBrequire_in\fP the first state defined in the included sls file.
.UNINDENT
.sp
When writing sls files with this renderer, one should avoid using what can be
defined in a \fBname\fP argument of a state as the state\(aqs id. That is, avoid
writing states like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/path/to/some/file:
file.managed:
\- source: salt://some/file
cp /path/to/some/file file2:
cmd.run:
\- cwd: /
\- require:
\- file: /path/to/some/file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instead, define the state id and the \fBname\fP argument separately for each
state. Also, the ID should be something meaningful and easy to reference within
a requisite (which is a good habit anyway, and such extra indirection would
also makes the sls file easier to modify later). Thus, the above states should
be written like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
add\-some\-file:
file.managed:
\- name: /path/to/some/file
\- source: salt://some/file
copy\-files:
cmd.run:
\- name: cp /path/to/some/file file2
\- cwd: /
\- require:
\- file: add\-some\-file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Moreover, when referencing a state from a requisite, you should reference the
state\(aqs id plus the state name rather than the state name plus its \fBname\fP
argument. (Yes, in the above example, you can actually \fBrequire\fP the
\fBfile: /path/to/some/file\fP, instead of the \fBfile: add\-some\-file\fP). The
reason is that this renderer will re\-write or rename state id\(aqs and their
references for state id\(aqs prefixed with \fB\&.\fP\&. So, if you reference \fBname\fP
then there\(aqs no way to reliably rewrite such reference.
.SS salt.renderers.wempy
.INDENT 0.0
.TP
.B salt.renderers.wempy.render(template_file, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, context=None, **kws)
Render the data passing the functions and grains into the rendering system
.INDENT 7.0
.TP
.B Return type
string
.UNINDENT
.UNINDENT
.SS salt.renderers.yaml
.SS Understanding YAML
.sp
The default renderer for SLS files is the YAML renderer. YAML is a
markup language with many powerful features. However, Salt uses
a small subset of YAML that maps over very commonly used data structures,
like lists and dictionaries. It is the job of the YAML renderer to take
the YAML data structure and compile it into a Python data structure for
use by Salt.
.sp
Though YAML syntax may seem daunting and terse at first, there are only
three very simple rules to remember when writing YAML for SLS files.
.SS Rule One: Indentation
.sp
YAML uses a fixed indentation scheme to represent relationships between
data layers. Salt requires that the indentation for each level consists
of exactly two spaces. Do not use tabs.
.SS Rule Two: Colons
.sp
Python dictionaries are, of course, simply key\-value pairs. Users from other
languages may recognize this data type as hashes or associative arrays.
.sp
Dictionary keys are represented in YAML as strings terminated by a trailing colon.
Values are represented by either a string following the colon, separated by a space:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_key: my_value
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In Python, the above maps to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqmy_key\(aq: \(aqmy_value\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In Python, the above maps to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqmy_key\(aq: \(aqmy_value\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Dictionaries can be nested:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
first_level_dict_key:
second_level_dict_key: value_in_second_level_dict
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And in Python:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqfirst_level_dict_key\(aq: {\(aqsecond_level_dict_key\(aq: \(aqvalue_in_second_level_dict\(aq }
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Rule Three: Dashes
.sp
To represent lists of items, a single dash followed by a space is used. Multiple
items are a part of the same list as a function of their having the same level of indentation.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\- list_value_one
\- list_value_two
\- list_value_three
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lists can be the value of a key\-value pair. This is quite common in Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_dictionary:
\- list_value_one
\- list_value_two
\- list_value_three
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reference
.sp
YAML Renderer for Salt
.INDENT 0.0
.TP
.B salt.renderers.yaml.get_yaml_loader(argline)
Return the ordered dict yaml loader
.UNINDENT
.INDENT 0.0
.TP
.B salt.renderers.yaml.render(yaml_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, **kws)
Accepts YAML as a string or as a file object and runs it through the YAML
parser.
.INDENT 7.0
.TP
.B Return type
A Python data structure
.UNINDENT
.UNINDENT
.SS salt.renderers.yamlex
.sp
YAMLEX renderer is a replacement of the YAML renderer.
It\(aqs 100% YAML with a pinch of Salt magic:
.INDENT 0.0
.IP \(bu 2
All mappings are automatically OrderedDict
.IP \(bu 2
All strings are automatically str obj
.IP \(bu 2
data aggregation with !aggregation yaml tag, based on the \fBsalt.utils.aggregation\fP module.
.IP \(bu 2
data aggregation over documents for pillar
.UNINDENT
.sp
Instructed aggregation within the \fB!aggregation\fP and the \fB!reset\fP tags:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!yamlex
foo: !aggregate first
foo: !aggregate second
bar: !aggregate {first: foo}
bar: !aggregate {second: bar}
baz: !aggregate 42
qux: !aggregate default
!reset qux: !aggregate my custom data
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
is roughly equivalent to
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo: [first, second]
bar: {first: foo, second: bar}
baz: [42]
qux: [my custom data]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reference
.INDENT 0.0
.TP
.B salt.renderers.yamlex.render(sls_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws)
Accepts YAML_EX as a string or as a file object and runs it through the YAML_EX
parser.
.INDENT 7.0
.TP
.B Return type
A Python data structure
.UNINDENT
.UNINDENT
.SS Returners
.sp
By default the return values of the commands sent to the Salt minions are
returned to the Salt master, however anything at all can be done with the results
data.
.sp
By using a Salt returner, results data can be redirected to external data\-stores
for analysis and archival.
.sp
Returners pull their configuration values from the Salt minions. Returners are only
configured once, which is generally at load time.
.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.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIFull list of builtin returners\fP
.UNINDENT
.UNINDENT
.SS Using Returners
.sp
All Salt commands will return the command data back to the master. Specifying
returners will ensure that the data is _also_ sent to the specified returner
interfaces.
.sp
Specifying what returners to use is done when the command is invoked:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping \-\-return redis_return
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This command will ensure that the redis_return returner is used.
.sp
It is also possible to specify multiple returners:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping \-\-return mongo_return,redis_return,cassandra_return
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this scenario all three returners will be called and the data from the
test.ping command will be sent out to the three named returners.
.SS Writing a Returner
.sp
A returner is a Python module which contains a function called \fBreturner\fP\&.
.sp
The \fBreturner\fP function must accept a single argument for 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 implemented below:
.INDENT 0.0
.INDENT 3.5
.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 connection
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
.UNINDENT
.UNINDENT
.sp
The above example of a returner set to send the data to a Redis server
serializes the data as JSON and sets it in redis.
.sp
Place custom returners in a \fB_returners\fP directory within the
\fBfile_roots\fP specified by the master config file.
.INDENT 0.0
.TP
.B Custom returners are distributed when any of the following are called:
\fBstate.highstate\fP
.sp
\fBsaltutil.sync_returners\fP
.sp
\fBsaltutil.sync_all\fP
.UNINDENT
.sp
Any custom returners which have been synced to a minion that are named the
same as one of Salt\(aqs default set of returners will take the place of the
default returner with the same name.
.sp
Note that a returner\(aqs default name is its filename (i.e. \fBfoo.py\fP becomes
returner \fBfoo\fP), but that its name can be overridden by using a
\fI__virtual__ function\fP\&. A good example of this can be
found in the \fI\%redis\fP returner, which is named \fBredis_return.py\fP but is
loaded as simply \fBredis\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
try:
import redis
HAS_REDIS = True
except ImportError:
HAS_REDIS = False
__virtualname__ = \(aqredis\(aq
def __virtual__():
if not HAS_REDIS:
return False
return __virtualname__
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Full List of Returners
.SS Full list of builtin returner modules
.TS
center;
|l|l|.
_
T{
\fBcarbon_return\fP
T} T{
Take data from salt and "return" it into a carbon receiver
T}
_
T{
\fBcassandra_return\fP
T} T{
Return data to a Cassandra ColumnFamily
T}
_
T{
\fBcouchbase_return\fP
T} T{
Simple returner for Couchbase.
T}
_
T{
\fBcouchdb_return\fP
T} T{
Simple returner for CouchDB.
T}
_
T{
\fBelasticsearch_return\fP
T} T{
Return data to an elasticsearch server for indexing.
T}
_
T{
\fBetcd_return\fP
T} T{
Return data to an etcd server or cluster
T}
_
T{
\fBlocal\fP
T} T{
The local returner is used to test the returner interface, it just prints the
T}
_
T{
\fBlocal_cache\fP
T} T{
Return data to local job cache
T}
_
T{
\fBmemcache_return\fP
T} T{
Return data to a memcache server
T}
_
T{
\fBmongo_future_return\fP
T} T{
Return data to a mongodb server
T}
_
T{
\fBmongo_return\fP
T} T{
Return data to a mongodb server
T}
_
T{
\fBmulti_returner\fP
T} T{
Read/Write multiple returners
T}
_
T{
\fBmysql\fP
T} T{
Return data to a mysql server
T}
_
T{
\fBodbc\fP
T} T{
Return data to an ODBC compliant server.
T}
_
T{
\fBpostgres\fP
T} T{
Return data to a postgresql server
T}
_
T{
\fBredis_return\fP
T} T{
Return data to a redis server
T}
_
T{
\fBsentry_return\fP
T} T{
Salt returner that report execution results back to sentry.
T}
_
T{
\fBsmtp_return\fP
T} T{
Return salt data via email
T}
_
T{
\fBsqlite3_return\fP
T} T{
Insert minion return data into a sqlite3 database
T}
_
T{
\fBsyslog_return\fP
T} T{
Return data to the host operating system\(aqs syslog facility
T}
_
.TE
.SS salt.returners.carbon_return
.sp
Take data from salt and "return" it into a carbon receiver
.sp
Add the following configuration to the minion configuration files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
carbon.host: <server ip address>
carbon.port: 2003
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Errors when trying to convert data to numbers may be ignored by setting
\fBcarbon.skip_on_error\fP to \fITrue\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
carbon.skip_on_error: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default, data will be sent to carbon using the plaintext protocol. To use
the pickle protocol, set \fBcarbon.mode\fP to \fBpickle\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
carbon.mode: pickle
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Carbon settings may also be configured as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
carbon:
host: <server IP or hostname>
port: <carbon port>
skip_on_error: True
mode: (pickle|text)
To use the carbon returner, append \(aq\-\-return carbon\(aq to the salt command. ex:
salt \(aq*\(aq test.ping \-\-return carbon
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.carbon_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.carbon_return.returner(ret)
Return data to a remote carbon server using the text metric protocol
.sp
Each metric will look like:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
[module].[function].[minion_id].[metric path [...]].[metric name]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.returners.cassandra_return
.sp
Return data to a Cassandra ColumnFamily
.sp
Here\(aqs an example Keyspace / ColumnFamily setup that works with this
returner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
create keyspace salt;
use salt;
create column family returns
with key_validation_class=\(aqUTF8Type\(aq
and comparator=\(aqUTF8Type\(aq
and default_validation_class=\(aqUTF8Type\(aq;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Required python modules: pycassa
.INDENT 0.0
.INDENT 3.5
To use the cassandra returner, append \(aq\-\-return cassandra\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return cassandra
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.cassandra_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.cassandra_return.returner(ret)
Return data to a Cassandra ColumnFamily
.UNINDENT
.SS salt.returners.couchbase_return
.sp
Simple returner for Couchbase. Optional configuration
settings are listed below, along with sane defaults.
.sp
couchbase.host: \(aqsalt\(aq
couchbase.port: 8091
couchbase.bucket: \(aqsalt\(aq
couchbase.skip_verify_views: False
.INDENT 0.0
.INDENT 3.5
To use the couchbase returner, append \(aq\-\-return couchbase\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return couchbase
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
All of the return data will be stored in documents as follows:
.SS JID
.sp
load: load obj
tgt_minions: list of minions targeted
nocache: should we not cache the return data
.SS JID/MINION_ID
.sp
return: return_data
out: out_data
.INDENT 0.0
.TP
.B salt.returners.couchbase_return.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchbase_return.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchbase_return.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchbase_return.prep_jid(nocache=False, passed_jid=None)
Return a job id and prepare the job id directory
This is the function responsible for making sure jids don\(aqt collide (unless its passed a jid)
So do what you have to do to make sure that stays the case
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchbase_return.returner(load)
Return data to the local job cache
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchbase_return.save_load(jid, clear_load)
Save the load to the specified jid
.UNINDENT
.SS salt.returners.couchdb_return
.sp
Simple returner for CouchDB. Optional configuration
settings are listed below, along with sane defaults.
.sp
couchdb.db: \(aqsalt\(aq
couchdb.url: \(aq\fI\%http://salt:5984/\fP\(aq
.INDENT 0.0
.INDENT 3.5
To use the couchdb returner, append \(aq\-\-return couchdb\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return couchdb
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.ensure_views()
This function makes sure that all the views that should
exist in the design document do exist.
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.get_fun(fun)
Return a dict with key being minion and value
being the job details of the last run of function \(aqfun\(aq.
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.get_jid(jid)
Get the document with a given JID.
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.get_jids()
List all the jobs that we have..
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.get_minions()
Return a list of minion identifiers from a request of the view.
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.get_valid_salt_views()
Returns a dict object of views that should be
part of the salt design document.
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.returner(ret)
Take in the return and shove it into the couchdb database.
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.couchdb_return.set_salt_view()
Helper function that sets the salt design
document. Uses get_valid_salt_views and some hardcoded values.
.UNINDENT
.SS salt.returners.elasticsearch_return
.sp
Return data to an elasticsearch server for indexing.
.INDENT 0.0
.TP
.B maintainer
Jurnell Cockhren <\fI\%jurnell.cockhren@sophicware.com\fP>
.TP
.B maturity
New
.TP
.B depends
\fI\%elasticsearch\-py\fP
.TP
.B platform
all
.UNINDENT
.sp
To enable this returner the elasticsearch python client must be installed
on the desired minions (all or some subset).
.sp
The required configuration is as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B elasticsearch:
host: \(aqsomehost.example.com:9200\(aq
index: \(aqsalt\(aq
number_of_shards: 1 (optional)
number_of_replicas: 0 (optional)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The above configuration can be placed in a targeted pillar, minion or
master configurations.
.sp
To use the returner per salt call:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return elasticsearch
.UNINDENT
.UNINDENT
.sp
In order to have the returner apply to all minions:
.INDENT 0.0
.INDENT 3.5
ext_job_cache: elasticsearch
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.elasticsearch_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.elasticsearch_return.returner(ret)
Process the return from Salt
.UNINDENT
.SS salt.returners.etcd_return
.sp
Return data to an etcd server or cluster
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
python\-etcd
.UNINDENT
.UNINDENT
.sp
In order to return to an etcd server, a profile should be created in the master
configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_etd_config:
etcd.host: 127.0.0.1
etcd.port: 4001
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is technically possible to configure etcd without using a profile, but this
is not considered to be a best practice, especially when multiple etcd servers
or clusters are available.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
etcd.host: 127.0.0.1
etcd.port: 4001
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Additionally, two more options must be specified in the top\-level configuration
in order to use the etcd returner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
etcd.returner: my_etcd_config
etcd.returner_root: /salt/return
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBetcd.returner\fP option specifies which configuration profile to use. The
\fBetcd.returner_root\fP option specifies the path inside etcd to use as the root
of the returner system.
.sp
Once the etcd options are configured, the returner may be used:
.sp
CLI Example:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return etcd
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.get_fun()
Return a dict of the last function called for all minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.returner(ret)
Return data to an etcd server or cluster
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.etcd_return.save_load(jid, load)
Save the load to the specified jid
.UNINDENT
.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
.INDENT 3.5
To use the local returner, append \(aq\-\-return local\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return local
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.local.returner(ret)
Print the return data to the terminal to verify functionality
.UNINDENT
.SS salt.returners.local_cache
.sp
Return data to local job cache
.INDENT 0.0
.TP
.B salt.returners.local_cache.clean_old_jobs()
Clean out the old jobs from the job cache
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.local_cache.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.local_cache.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.local_cache.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.local_cache.prep_jid(nocache=False, passed_jid=None)
Return a job id and prepare the job id directory
This is the function responsible for making sure jids don\(aqt collide (unless its passed a jid)
So do what you have to do to make sure that stays the case
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.local_cache.returner(load)
Return data to the local job cache
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.local_cache.save_load(jid, clear_load)
Save the load to the specified jid
.UNINDENT
.SS salt.returners.memcache_return
.sp
Return data to a memcache server
.sp
To enable this returner the minion will need the python client for memcache
installed and the following values configured in the minion or master
config, these are the defaults:
.INDENT 0.0
.INDENT 3.5
memcache.host: \(aqlocalhost\(aq
memcache.port: \(aq11211\(aq
.UNINDENT
.UNINDENT
.sp
python2\-memcache uses \(aqlocalhost\(aq and \(aq11211\(aq as syntax on connection.
.INDENT 0.0
.TP
.B salt.returners.memcache_return.get_fun(fun)
Return a dict of the last function called for all minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.memcache_return.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.memcache_return.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.memcache_return.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.memcache_return.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.memcache_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.memcache_return.returner(ret)
Return data to a memcache data store
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.memcache_return.save_load(jid, load)
Save the load to the specified jid
.UNINDENT
.SS salt.returners.mongo_future_return
.sp
Return data to a mongodb server
.sp
Required python modules: pymongo
.sp
This returner will send data from the minions to a MongoDB server. To
configure the settings for your MongoDB server, add the following lines
to the minion config files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongo.db: <database name>
mongo.host: <server ip address>
mongo.user: <MongoDB username>
mongo.password: <MongoDB user password>
mongo.port: 27017
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This mongo returner is being developed to replace the default mongodb returner
in the future and should not be considered API stable yet.
.INDENT 0.0
.INDENT 3.5
To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return mongo
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.get_fun(fun)
Return the most recent jobs that have executed the named function
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.get_jid(jid)
Return the return information associated with a jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.get_jids()
Return a list of job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.get_load(jid)
Return the load associated with a given job id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.returner(ret)
Return data to a mongodb server
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_future_return.save_load(jid, load)
Save the load for a given job id
.UNINDENT
.SS salt.returners.mongo_return
.sp
Return data to a mongodb server
.sp
Required python modules: pymongo
.sp
This returner will send data from the minions to a MongoDB server. To
configure the settings for your MongoDB server, add the following lines
to the minion config files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mongo.db: <database name>
mongo.host: <server ip address>
mongo.user: <MongoDB username>
mongo.password: <MongoDB user password>
mongo.port: 27017
To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. ex:
salt \(aq*\(aq test.ping \-\-return mongo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_return.get_fun(fun)
Return the most recent jobs that have executed the named function
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_return.get_jid(jid)
Return the return information associated with a jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mongo_return.returner(ret)
Return data to a mongodb server
.UNINDENT
.SS salt.returners.multi_returner
.sp
Read/Write multiple returners
.INDENT 0.0
.TP
.B salt.returners.multi_returner.clean_old_jobs()
Clean out the old jobs from all returners (if you have it)
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.multi_returner.get_jid(jid)
Merge the return data from all returners
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.multi_returner.get_jids()
Return all job data from all returners
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.multi_returner.get_load(jid)
Merge the load data from all returners
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.multi_returner.prep_jid(nocache=False, passed_jid=None)
Call both with prep_jid on all returners in multi_returner
.sp
TODO: finish this, what do do when you get different jids from 2 returners...
since our jids are time based, this make this problem hard, because they
aren\(aqt unique, meaning that we have to make sure that no one else got the jid
and if they did we spin to get a new one, which means "locking" the jid in 2
returners is non\-trivial
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.multi_returner.returner(load)
Write return to all returners in multi_returner
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.multi_returner.save_load(jid, clear_load)
Write load to all returners in multi_returner
.UNINDENT
.SS salt.returners.mysql
.sp
Return data to a mysql server
.INDENT 0.0
.TP
.B maintainer
Dave Boucha <\fI\%dave@saltstack.com\fP>, Seth House <\fI\%shouse@saltstack.com\fP>
.TP
.B maturity
new
.TP
.B depends
python\-mysqldb
.TP
.B platform
all
.UNINDENT
.sp
To enable this returner the minion will need the python client for mysql
installed and the following values configured in the minion or master
config, these are the defaults:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mysql.host: \(aqsalt\(aq
mysql.user: \(aqsalt\(aq
mysql.pass: \(aqsalt\(aq
mysql.db: \(aqsalt\(aq
mysql.port: 3306
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use the following mysql database schema:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
CREATE DATABASE \(gasalt\(ga
DEFAULT CHARACTER SET utf8
DEFAULT COLLATE utf8_general_ci;
USE \(gasalt\(ga;
\-\-
\-\- Table structure for table \(gajids\(ga
\-\-
DROP TABLE IF EXISTS \(gajids\(ga;
CREATE TABLE \(gajids\(ga (
\(gajid\(ga varchar(255) NOT NULL,
\(gaload\(ga mediumtext NOT NULL,
UNIQUE KEY \(gajid\(ga (\(gajid\(ga)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
\-\-
\-\- Table structure for table \(gasalt_returns\(ga
\-\-
DROP TABLE IF EXISTS \(gasalt_returns\(ga;
CREATE TABLE \(gasalt_returns\(ga (
\(gafun\(ga varchar(50) NOT NULL,
\(gajid\(ga varchar(255) NOT NULL,
\(gareturn\(ga mediumtext NOT NULL,
\(gaid\(ga varchar(255) NOT NULL,
\(gasuccess\(ga varchar(10) NOT NULL,
\(gafull_ret\(ga mediumtext NOT NULL,
\(gaalter_time\(ga TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
KEY \(gaid\(ga (\(gaid\(ga),
KEY \(gajid\(ga (\(gajid\(ga),
KEY \(gafun\(ga (\(gafun\(ga)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Required python modules: MySQLdb
.INDENT 0.0
.INDENT 3.5
To use the mysql returner, append \(aq\-\-return mysql\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return mysql
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.get_fun(fun)
Return a dict of the last function called for all minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.returner(ret)
Return data to a mysql server
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.mysql.save_load(jid, load)
Save the load to the specified jid id
.UNINDENT
.SS salt.returners.odbc
.sp
Return data to an ODBC compliant server. This driver was
developed with Microsoft SQL Server in mind, but theoretically
could be used to return data to any compliant ODBC database
as long as there is a working ODBC driver for it on your
minion platform.
.INDENT 0.0
.TP
.B maintainer
.INDENT 7.0
.IP C. 3
.INDENT 3.0
.IP R. 3
Oldham (\fI\%cr@saltstack.com\fP)
.UNINDENT
.UNINDENT
.TP
.B maturity
New
.TP
.B depends
unixodbc, pyodbc, freetds (for SQL Server)
.TP
.B platform
all
.UNINDENT
.sp
To enable this returner the minion will need
.sp
On Linux:
.INDENT 0.0
.INDENT 3.5
unixodbc (\fI\%http://www.unixodbc.org\fP)
pyodbc (\fIpip install pyodbc\fP)
The FreeTDS ODBC driver for SQL Server (\fI\%http://www.freetds.org\fP)
or another compatible ODBC driver
.UNINDENT
.UNINDENT
.sp
On Windows:
.INDENT 0.0
.INDENT 3.5
TBD
.UNINDENT
.UNINDENT
.sp
unixODBC and FreeTDS need to be configured via /etc/odbcinst.ini and
/etc/odbc.ini.
.sp
/etc/odbcinst.ini:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[TDS]
Description=TDS
Driver=/usr/lib/x86_64\-linux\-gnu/odbc/libtdsodbc.so
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(Note the above Driver line needs to point to the location of the FreeTDS
shared library. This example is for Ubuntu 14.04.)
.sp
/etc/odbc.ini:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[TS]
Description = "Salt Returner"
Driver=TDS
Server = <your server ip or fqdn>
Port = 1433
Database = salt
Trace = No
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Also you need the following values configured in the minion or master config.
Configure as you see fit:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
returner.odbc.dsn: \(aqTS\(aq
returner.odbc.user: \(aqsalt\(aq
returner.odbc.passwd: \(aqsalt\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Running the following commands against Microsoft SQL Server in the desired
database as the appropriate user should create the database tables
correctly. Replace with equivalent SQL for other ODBC\-compliant servers:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-
\-\- Table structure for table \(aqjids\(aq
\-\-
if OBJECT_ID(\(aqdbo.jids\(aq, \(aqU\(aq) is not null
DROP TABLE dbo.jids
CREATE TABLE dbo.jids (
jid varchar(255) PRIMARY KEY,
load varchar(MAX) NOT NULL
);
\-\-
\-\- Table structure for table \(aqsalt_returns\(aq
\-\-
IF OBJECT_ID(\(aqdbo.salt_returns\(aq, \(aqU\(aq) IS NOT NULL
DROP TABLE dbo.salt_returns;
CREATE TABLE dbo.salt_returns (
added datetime not null default (getdate()),
fun varchar(100) NOT NULL,
jid varchar(255) NOT NULL,
retval varchar(MAX) NOT NULL,
id varchar(255) NOT NULL,
success bit default(0) NOT NULL,
full_ret varchar(MAX)
);
CREATE INDEX salt_returns_added on dbo.salt_returns(added);
CREATE INDEX salt_returns_id on dbo.salt_returns(id);
CREATE INDEX salt_returns_jid on dbo.salt_returns(jid);
CREATE INDEX salt_returns_fun on dbo.salt_returns(fun);
To use this returner, append \(aq\-\-return odbc\(aq to the salt command. ex:
salt \(aq*\(aq status.diskusage \-\-return odbc
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.get_fun(fun)
Return a dict of the last function called for all minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.returner(ret)
Return data to an odbc server
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.odbc.save_load(jid, load)
Save the load to the specified jid id
.UNINDENT
.SS salt.returners.postgres
.sp
Return data to a postgresql server
.INDENT 0.0
.TP
.B maintainer
None
.TP
.B maturity
New
.TP
.B depends
psycopg2
.TP
.B platform
all
.UNINDENT
.sp
To enable this returner the minion will need the psycopg2 installed and
the following values configured in the minion or master config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
returner.postgres.host: \(aqsalt\(aq
returner.postgres.user: \(aqsalt\(aq
returner.postgres.passwd: \(aqsalt\(aq
returner.postgres.db: \(aqsalt\(aq
returner.postgres.port: 5432
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Running the following commands as the postgres user should create the database
correctly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
psql << EOF
CREATE ROLE salt WITH PASSWORD \(aqsalt\(aq;
CREATE DATABASE salt WITH OWNER salt;
EOF
psql \-h localhost \-U salt << EOF
\-\-
\-\- Table structure for table \(aqjids\(aq
\-\-
DROP TABLE IF EXISTS jids;
CREATE TABLE jids (
jid varchar(20) PRIMARY KEY,
load text NOT NULL
);
\-\-
\-\- Table structure for table \(aqsalt_returns\(aq
\-\-
DROP TABLE IF EXISTS salt_returns;
CREATE TABLE salt_returns (
added TIMESTAMP WITH TIME ZONE DEFAULT now(),
fun text NOT NULL,
jid varchar(20) NOT NULL,
return text NOT NULL,
id text NOT NULL,
success boolean
);
CREATE INDEX ON salt_returns (added);
CREATE INDEX ON salt_returns (id);
CREATE INDEX ON salt_returns (jid);
CREATE INDEX ON salt_returns (fun);
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Required python modules: psycopg2
.INDENT 0.0
.INDENT 3.5
To use the postgres returner, append \(aq\-\-return postgres\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return postgres
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.get_fun(fun)
Return a dict of the last function called for all minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.returner(ret)
Return data to a postgres server
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.postgres.save_load(jid, load)
Save the load to the specified jid id
.UNINDENT
.SS salt.returners.redis_return
.sp
Return data to a redis server
.sp
To enable this returner the minion will need the python client for redis
installed and the following values configured in the minion or master
config, these are the defaults:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
redis.db: \(aq0\(aq
redis.host: \(aqsalt\(aq
redis.port: 6379
.UNINDENT
.UNINDENT
.sp
To use the redis returner, append \(aq\-\-return redis\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return redis
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.get_fun(fun)
Return a dict of the last function called for all minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.get_jid(jid)
Return the information returned when the specified job id was executed
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.get_load(jid)
Return the load data that marks a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.returner(ret)
Return data to a redis data store
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.redis_return.save_load(jid, load)
Save the load to the specified jid
.UNINDENT
.SS salt.returners.sentry_return
.sp
Salt returner that report execution results back to sentry. The returner will
inspect the payload to identify errors and flag them as such.
.sp
Pillar need something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
raven:
servers:
\- http://192.168.1.1
\- https://sentry.example.com
public_key: deadbeefdeadbeefdeadbeefdeadbeef
secret_key: beefdeadbeefdeadbeefdeadbeefdead
project: 1
tags:
\- os
\- master
\- saltversion
\- cpuarch
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and \fI\%https://pypi.python.org/pypi/raven\fP installed
.sp
The tags list (optional) specifies grains items that will be used as sentry tags, allowing tagging of events
in the sentry ui.
.INDENT 0.0
.TP
.B salt.returners.sentry_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sentry_return.returner(ret)
Log outcome to sentry. The returner tries to identify errors and report them as such. All other
messages will be reported at info level.
.UNINDENT
.SS salt.returners.smtp_return
.sp
Return salt data via email
.sp
The following fields can be set in the minion conf file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
smtp.from (required)
smtp.to (required)
smtp.host (required)
smtp.port (optional, defaults to 25)
smtp.username (optional)
smtp.password (optional)
smtp.tls (optional, defaults to False)
smtp.subject (optional, but helpful)
smtp.gpgowner (optional)
smtp.fields (optional)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There are a few things to keep in mind:
.INDENT 0.0
.IP \(bu 2
If a username is used, a password is also required. It is recommended (but
not required) to use the TLS setting when authenticating.
.IP \(bu 2
You should at least declare a subject, but you don\(aqt have to.
.IP \(bu 2
The use of encryption, i.e. setting gpgowner in your settings, requires
python\-gnupg to be installed.
.IP \(bu 2
The field gpgowner specifies a user\(aqs ~/.gpg directory. This must contain a
gpg public key matching the address the mail is sent to. If left unset, no
encryption will be used.
.IP \(bu 2
smtp.fields lets you include the value(s) of various fields in the subject
line of the email. These are comma\-delimited. For instance:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
smtp.fields: id,fun
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\&...will display the id of the minion and the name of the function in the
subject line. You may also use \(aqjid\(aq (the job id), but it is generally
recommended not to use \(aqreturn\(aq, which contains the entire return data
structure (which can be very large). Also note that the subject is always
unencrypted.
.sp
To use the SMTP returner, append \(aq\-\-return smtp\(aq to the salt command. ex:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq test.ping \-\-return smtp
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.smtp_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.smtp_return.returner(ret)
Send an email with the data
.UNINDENT
.SS salt.returners.sqlite3
.sp
Insert minion return data into a sqlite3 database
.INDENT 0.0
.TP
.B maintainer
Mickey Malone <\fI\%mickey.malone@gmail.com\fP>
.TP
.B maturity
New
.TP
.B depends
None
.TP
.B platform
All
.UNINDENT
.sp
Sqlite3 is a serverless database that lives in a single file.
In order to use this returner the database file must exist,
have the appropriate schema defined, and be accessible to the
user whom the minion process is running as. This returner
requires the following values configured in the master or
minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
returner.sqlite3.database: /usr/lib/salt/salt.db
returner.sqlite3.timeout: 5.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Use the commands to create the sqlite3 database and tables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sqlite3 /usr/lib/salt/salt.db << EOF
\-\-
\-\- Table structure for table \(aqjids\(aq
\-\-
CREATE TABLE jids (
jid TEXT PRIMARY KEY,
load TEXT NOT NULL
);
\-\-
\-\- Table structure for table \(aqsalt_returns\(aq
\-\-
CREATE TABLE salt_returns (
fun TEXT KEY,
jid TEXT KEY,
id TEXT KEY,
fun_args TEXT,
date TEXT NOT NULL,
full_ret TEXT NOT NULL,
success TEXT NOT NULL
);
EOF
To use the sqlite returner, append \(aq\-\-return sqlite\(aq to the salt command. ex:
salt \(aq*\(aq test.ping \-\-return sqlite
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.get_fun(fun)
Return a dict of the last function called for all minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.get_jid(jid)
Return the information returned from a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.get_jids()
Return a list of all job ids
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.get_load(jid)
Return the load from a specified jid
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.get_minions()
Return a list of minions
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.returner(ret)
Insert minion return data into the sqlite3 database
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.sqlite3_return.save_load(jid, load)
Save the load to the specified jid
.UNINDENT
.SS salt.returners.syslog_return
.sp
Return data to the host operating system\(aqs syslog facility
.sp
Required python modules: syslog, json
.sp
The syslog returner simply reuses the operating system\(aqs syslog
facility to log return data
.sp
To use the syslog returner, append \(aq\-\-return syslog\(aq to the salt command. ex:
.INDENT 0.0
.INDENT 3.5
salt \(aq*\(aq test.ping \-\-return syslog
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.syslog_return.prep_jid(nocache, passed_jid=None)
Do any work necessary to prepare a JID, including sending a custom id
.UNINDENT
.INDENT 0.0
.TP
.B salt.returners.syslog_return.returner(ret)
Return data to the local syslog
.UNINDENT
.SS Full list of builtin roster modules
.TS
center;
|l|l|.
_
T{
\fBflat\fP
T} T{
Read in the roster from a flat file using the renderer system
T}
_
T{
\fBscan\fP
T} T{
Scan a netmask or ipaddr for open ssh ports
T}
_
.TE
.SS salt.roster.flat
.sp
Read in the roster from a flat file using the renderer system
.INDENT 0.0
.TP
.B class salt.roster.flat.RosterMatcher(raw, tgt, tgt_type, ipv=\(aqipv4\(aq)
Matcher for the roster data structure
.INDENT 7.0
.TP
.B get_data(minion)
Return the configured ip
.UNINDENT
.INDENT 7.0
.TP
.B ret_glob_minions()
Return minions that match via glob
.UNINDENT
.INDENT 7.0
.TP
.B ret_pcre_minions()
Return minions that match via pcre
.UNINDENT
.INDENT 7.0
.TP
.B targets()
Execute the correct tgt_type routine and return
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.roster.flat.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs)
Return the targets from the flat yaml file, checks opts for location but
defaults to /etc/salt/roster
.UNINDENT
.SS salt.roster.scan
.sp
Scan a netmask or ipaddr for open ssh ports
.INDENT 0.0
.TP
.B class salt.roster.scan.RosterMatcher(tgt, tgt_type)
Matcher for the roster data structure
.INDENT 7.0
.TP
.B targets()
Return ip addrs based on netmask, sitting in the "glob" spot because
it is the default
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.roster.scan.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs)
Return the targets from the flat yaml file, checks opts for location but
defaults to /etc/salt/roster
.UNINDENT
.SS Salt Runners
.sp
Salt runners are convenience applications executed with the salt\-run command.
.sp
Salt runners work similarly to Salt execution modules however they execute on the
Salt master itself instead of remote Salt minions.
.sp
A Salt runner can be a simple client call or a complex application.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIThe full list of runners\fP
.UNINDENT
.UNINDENT
.SS Full list of runner modules
.TS
center;
|l|l|.
_
T{
\fBcache\fP
T} T{
Return cached data from minions
T}
_
T{
\fBcloud\fP
T} T{
The Salt Cloud Runner
T}
_
T{
\fBdoc\fP
T} T{
A runner module to collect and display the inline documentation from the
T}
_
T{
\fBerror\fP
T} T{
Error generator to enable integration testing of salt runner error handling
T}
_
T{
\fBfileserver\fP
T} T{
Directly manage the Salt fileserver plugins
T}
_
T{
\fBgit_pillar\fP
T} T{
Directly manage the salt git_pillar plugin
T}
_
T{
\fBjobs\fP
T} T{
A convenience system to manage jobs, both active and already run
T}
_
T{
\fBlaunchd\fP
T} T{
Manage launchd plist files
T}
_
T{
\fBlxc\fP
T} T{
Control Linux Containers via Salt
T}
_
T{
\fBmanage\fP
T} T{
General management functions for salt, tools like seeing what hosts are up
T}
_
T{
\fBmine\fP
T} T{
A runner to access data from the salt mine
T}
_
T{
\fBnetwork\fP
T} T{
Network tools to run from the Master
T}
_
T{
\fBpillar\fP
T} T{
Functions to interact with the pillar compiler on the master
T}
_
T{
\fBqueue\fP
T} T{
General management and processing of queues.
T}
_
T{
\fBsearch\fP
T} T{
Runner frontend to search system
T}
_
T{
\fBstate\fP
T} T{
Execute overstate functions
T}
_
T{
\fBsurvey\fP
T} T{
A general map/reduce style salt runner for aggregating results returned by several different minions.
T}
_
T{
\fBthin\fP
T} T{
The thin runner is used to manage the salt thin systems.
T}
_
T{
\fBvirt\fP
T} T{
Control virtual machines via Salt
T}
_
T{
\fBwinrepo\fP
T} T{
Runner to manage Windows software repo
T}
_
.TE
.SS salt.runners.cache
.sp
Return cached data from minions
.INDENT 0.0
.TP
.B salt.runners.cache.clear_all(tgt=None, expr_form=\(aqglob\(aq)
Clear the cached pillar, grains, and mine data of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.clear_all
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cache.clear_grains(tgt=None, expr_form=\(aqglob\(aq)
Clear the cached grains data of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.clear_grains
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cache.clear_mine(tgt=None, expr_form=\(aqglob\(aq)
Clear the cached mine data of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.clear_mine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cache.clear_mine_func(tgt=None, expr_form=\(aqglob\(aq, clear_mine_func=None)
Clear the cached mine function data of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.clear_mine_func tgt=\(aq*\(aq clear_mine_func=\(aqnetwork.interfaces\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cache.clear_pillar(tgt=None, expr_form=\(aqglob\(aq)
Clear the cached pillar data of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.clear_pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cache.grains(tgt=None, expr_form=\(aqglob\(aq, **kwargs)
Return cached grains of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.grains
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cache.mine(tgt=None, expr_form=\(aqglob\(aq, **kwargs)
Return cached mine data of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.mine
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cache.pillar(tgt=None, expr_form=\(aqglob\(aq, **kwargs)
Return cached pillars of the targeted minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cache.pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.cloud
.SS The Salt Cloud Runner
.sp
This runner wraps the functionality of salt cloud making salt cloud routines
available to all internal apis via the runner system
.INDENT 0.0
.TP
.B salt.runners.cloud.action(fun=None, cloudmap=None, instances=None, provider=None, instance=None, **kwargs)
Execute a single action on the given map/provider/instance
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.create(provider, instances, **kwargs)
Create an instance using Salt Cloud
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run cloud.create my\-ec2\-config myinstance image=ami\-1624987f size=\(aqMicro Instance\(aq ssh_username=ec2\-user securitygroup=default delvol_on_destroy=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.destroy(instances)
Destroy the named vm(s)
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.full_query(query_type=\(aqlist_nodes_full\(aq)
List all available cloud provider data
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.list_images(provider=\(aqall\(aq)
List cloud provider images for the given providers
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.list_locations(provider=\(aqall\(aq)
List cloud provider sizes for the given providers
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.list_sizes(provider=\(aqall\(aq)
List cloud provider sizes for the given providers
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.map_run(path, **kwargs)
Execute a salt cloud map file
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.profile(prof, instances, **kwargs)
Create a cloud vm with the given profile and instances, instances can be a list
or comma delimited string
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.query(query_type=\(aqlist_nodes\(aq)
List cloud provider data for all providers
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.cloud.select_query(query_type=\(aqlist_nodes_select\(aq)
List selected nodes
.UNINDENT
.SS salt.runners.doc
.sp
A runner module to collect and display the inline documentation from the
various module types
.INDENT 0.0
.TP
.B salt.runners.doc.execution()
Collect all the sys.doc output from each minion and return the aggregate
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run doc.execution
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.doc.runner()
Return all inline documentation for runner modules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run doc.runner
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.doc.wheel()
Return all inline documentation for wheel modules
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run doc.wheel
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.error
.sp
Error generator to enable integration testing of salt runner error handling
.INDENT 0.0
.TP
.B salt.runners.error.error(name=None, message=\(aq\(aq)
If name is None Then return empty dict
.sp
Otherwise raise an exception with __name__ from name, message from message
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run error
salt\-run error.error name="Exception" message="This is an error."
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.fileserver
.sp
Directly manage the Salt fileserver plugins
.INDENT 0.0
.TP
.B salt.runners.fileserver.clear_cache(backend=None)
New in version 2015.2.0.
.sp
Clear the fileserver cache from VCS fileserver backends (\fBgit\fP, \fBhg\fP, \fBsvn\fP). Executing this runner with no arguments will
clear the cache for all enabled VCS fileserver backends, but this
can be narrowed using the \fBbackend\fP argument.
.INDENT 7.0
.TP
.B backend
Only clear the update lock for the specified backend(s). If all passed
backends start with a minus sign (\fB\-\fP), then these backends will be
excluded from the enabled backends. However, if there is a mix of
backends with and without a minus sign (ex: \fBbackend=\-roots,git\fP)
then the ones starting with a minus sign will be disregarded.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.clear_cache
salt\-run fileserver.clear_cache backend=git,hg
salt\-run fileserver.clear_cache hg
salt\-run fileserver.clear_cache \-roots
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.clear_lock(backend=None, remote=None)
New in version 2015.2.0.
.sp
Clear the fileserver update lock from VCS fileserver backends (\fBgit\fP, \fBhg\fP, \fBsvn\fP). This should only need to be done if a fileserver
update was interrupted and a remote is not updating (generating a warning
in the Master\(aqs log file). Executing this runner with no arguments will
remove all update locks from all enabled VCS fileserver backends, but this
can be narrowed by using the following arguments:
.INDENT 7.0
.TP
.B backend
Only clear the update lock for the specified backend(s).
.TP
.B remote
If not None, then any remotes which contain the passed string will have
their lock cleared. For example, a \fBremote\fP value of \fBgithub\fP will
remove the lock from all github.com remotes.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.clear_lock
salt\-run fileserver.clear_lock backend=git,hg
salt\-run fileserver.clear_lock backend=git remote=github
salt\-run fileserver.clear_lock remote=bitbucket
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.dir_list(saltenv=\(aqbase\(aq, backend=None, outputter=\(aqnested\(aq)
Return a list of directories in the given environment
.INDENT 7.0
.TP
.B saltenv
base
The salt fileserver environment to be listed
.TP
.B backend
Narrow fileserver backends to a subset of the enabled ones. If all
passed backends start with a minus sign (\fB\-\fP), then these backends
will be excluded from the enabled backends. However, if there is a mix
of backends with and without a minus sign (ex:
\fBbackend=\-roots,git\fP) then the ones starting with a minus sign will
be disregarded.
.sp
New in version 2015.2.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.dir_list
salt\-run fileserver.dir_list saltenv=prod
salt\-run fileserver.dir_list saltenv=dev backend=git
salt\-run fileserver.dir_list base hg,roots
salt\-run fileserver.dir_list \-git
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.empty_dir_list(saltenv=\(aqbase\(aq, backend=None, outputter=\(aqnested\(aq)
New in version 2015.2.0.
.sp
Return a list of empty directories in the given environment
.INDENT 7.0
.TP
.B saltenv
base
The salt fileserver environment to be listed
.TP
.B backend
Narrow fileserver backends to a subset of the enabled ones. If all
passed backends start with a minus sign (\fB\-\fP), then these backends
will be excluded from the enabled backends. However, if there is a mix
of backends with and without a minus sign (ex:
\fBbackend=\-roots,git\fP) then the ones starting with a minus sign will
be disregarded.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Some backends (such as \fBgit\fP and
\fBhg\fP) do not support empty directories.
So, passing \fBbackend=git\fP or \fBbackend=hg\fP will result in an
empty list being returned.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.empty_dir_list
salt\-run fileserver.empty_dir_list saltenv=prod
salt\-run fileserver.empty_dir_list backend=roots
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.envs(backend=None, sources=False, outputter=\(aqnested\(aq)
Return the available fileserver environments. If no backend is provided,
then the environments for all configured backends will be returned.
.INDENT 7.0
.TP
.B backend
Narrow fileserver backends to a subset of the enabled ones.
.sp
Changed in version 2015.2.0::: If all passed backends start with a minus sign (\fB\-\fP), then these
backends will be excluded from the enabled backends. However, if
there is a mix of backends with and without a minus sign (ex:
\fBbackend=\-roots,git\fP) then the ones starting with a minus
sign will be disregarded.
.sp
Additionally, fileserver backends can now be passed as a
comma\-separated list. In earlier versions, they needed to be passed
as a python list (ex: \fBbackend="[\(aqroots\(aq, \(aqgit\(aq]"\fP)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.envs
salt\-run fileserver.envs outputter=nested
salt\-run fileserver.envs backend=roots,git
salt\-run fileserver.envs git
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.file_list(saltenv=\(aqbase\(aq, backend=None, outputter=\(aqnested\(aq)
Return a list of files from the salt fileserver
.INDENT 7.0
.TP
.B saltenv
base
The salt fileserver environment to be listed
.TP
.B backend
Narrow fileserver backends to a subset of the enabled ones. If all
passed backends start with a minus sign (\fB\-\fP), then these backends
will be excluded from the enabled backends. However, if there is a mix
of backends with and without a minus sign (ex:
\fBbackend=\-roots,git\fP) then the ones starting with a minus sign will
be disregarded.
.sp
New in version 2015.2.0.
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.file_list
salt\-run fileserver.file_list saltenv=prod
salt\-run fileserver.file_list saltenv=dev backend=git
salt\-run fileserver.file_list base hg,roots
salt\-run fileserver.file_list \-git
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.lock(backend=None, remote=None)
New in version 2015.2.0.
.sp
Set a fileserver update lock for VCS fileserver backends (\fBgit\fP, \fBhg\fP, \fBsvn\fP).
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This will only operate on enabled backends (those configured in
.nf
:master_conf:\(gafileserver_backend\(ga
.fi
).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B backend
Only set the update lock for the specified backend(s).
.TP
.B remote
If not None, then any remotes which contain the passed string will have
their lock cleared. For example, a \fBremote\fP value of \fB*github.com*\fP
will remove the lock from all github.com remotes.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.lock
salt\-run fileserver.lock backend=git,hg
salt\-run fileserver.lock backend=git remote=\(aq*github.com*\(aq
salt\-run fileserver.lock remote=bitbucket
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.symlink_list(saltenv=\(aqbase\(aq, backend=None, outputter=\(aqnested\(aq)
Return a list of symlinked files and dirs
.INDENT 7.0
.TP
.B saltenv
base
The salt fileserver environment to be listed
.TP
.B backend
Narrow fileserver backends to a subset of the enabled ones. If all
passed backends start with a minus sign (\fB\-\fP), then these backends
will be excluded from the enabled backends. However, if there is a mix
of backends with and without a minus sign (ex:
\fBbackend=\-roots,git\fP) then the ones starting with a minus sign will
be disregarded.
.sp
New in version 2015.2.0.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.symlink_list
salt\-run fileserver.symlink_list saltenv=prod
salt\-run fileserver.symlink_list saltenv=dev backend=git
salt\-run fileserver.symlink_list base hg,roots
salt\-run fileserver.symlink_list \-git
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.fileserver.update(backend=None)
Update the fileserver cache. If no backend is provided, then the cache for
all configured backends will be updated.
.INDENT 7.0
.TP
.B backend
Narrow fileserver backends to a subset of the enabled ones.
.sp
Changed in version 2015.2.0: If all passed backends start with a minus sign (\fB\-\fP), then these
backends will be excluded from the enabled backends. However, if
there is a mix of backends with and without a minus sign (ex:
\fBbackend=\-roots,git\fP) then the ones starting with a minus
sign will be disregarded.
.sp
Additionally, fileserver backends can now be passed as a
comma\-separated list. In earlier versions, they needed to be passed
as a python list (ex: \fBbackend="[\(aqroots\(aq, \(aqgit\(aq]"\fP)
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run fileserver.update
salt\-run fileserver.update backend=roots,git
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.git_pillar
.sp
Directly manage the salt git_pillar plugin
.INDENT 0.0
.TP
.B salt.runners.git_pillar.update(branch, repo)
Execute an update for the configured git fileserver backend for Pillar
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run git_pillar.update branch=\(aqbranch\(aq repo=\(aqlocation\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.jobs
.sp
A convenience system to manage jobs, both active and already run
.INDENT 0.0
.TP
.B salt.runners.jobs.active()
Return a report on all actively running jobs from a job id centric
perspective
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run jobs.active
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.jobs.list_job(jid, ext_source=None)
List a specific job given by its jid
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run jobs.list_job 20130916125524463507
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.jobs.list_jobs(ext_source=None)
List all detectable jobs and associated functions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run jobs.list_jobs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.jobs.lookup_jid(jid, ext_source=None, missing=False)
Return the printout from a previously executed job
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run jobs.lookup_jid 20130916125524463507
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.jobs.print_job(jid, ext_source=None)
Print job available details, including return data.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run jobs.print_job
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.launchd
.sp
Manage launchd plist files
.INDENT 0.0
.TP
.B salt.runners.launchd.write_launchd_plist(program)
Write a launchd plist for managing salt\-master or salt\-minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run launchd.write_launchd_plist salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.lxc
.sp
Control Linux Containers via Salt
.INDENT 0.0
.TP
.B depends
lxc execution module
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.cloud_init(names, host=None, quiet=False, **kwargs)
Wrapper for using lxc.init in saltcloud compatibility mode
.INDENT 7.0
.TP
.B names
Name of the containers, supports a single name or a comma delimited
list of names.
.TP
.B host
Minion to start the container on. Required.
.TP
.B saltcloud_mode
init the container with the saltcloud opts format instead
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.find_guest(name, quiet=False)
Returns the host for a container.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.find_guest name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.find_guests(names)
Return a dict of hosts and named guests
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.freeze(name, quiet=False)
Freeze the named container
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.freeze name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.info(name, quiet=False)
Returns information about a container.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.info name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.init(names, host=None, saltcloud_mode=False, quiet=False, **kwargs)
Initialize a new container
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.init name host=minion_id [cpuset=cgroups_cpuset] \e
[cpushare=cgroups_cpushare] [memory=cgroups_memory] \e
[template=lxc template name] [clone=original name] \e
[nic=nic_profile] [profile=lxc_profile] \e
[nic_opts=nic_opts] [start=(true|false)] \e
[seed=(true|false)] [install=(true|false)] \e
[config=minion_config] [snapshot=(true|false)]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B names
Name of the containers, supports a single name or a comma delimited
list of names.
.TP
.B host
Minion to start the container on. Required.
.TP
.B saltcloud_mode
init the container with the saltcloud opts format instead
See lxc.init_interface module documentation
.TP
.B cpuset
cgroups cpuset.
.TP
.B cpushare
cgroups cpu shares.
.TP
.B memory
cgroups memory limit, in MB.
.TP
.B template
Name of LXC template on which to base this container
.TP
.B clone
Clone this container from an existing container
.TP
.B nic
Network interfaces profile (defined in config or pillar).
.TP
.B profile
A LXC profile (defined in config or pillar).
.TP
.B nic_opts
Extra options for network interfaces. E.g:
.sp
\fB{"eth0": {"mac": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1", "ipv6": "2001:db8::ff00:42:8329"}}\fP
.TP
.B start
Start the newly created container.
.TP
.B seed
Seed the container with the minion config and autosign its key.
Default: true
.TP
.B install
If salt\-minion is not already installed, install it. Default: true
.TP
.B config
Optional config parameters. By default, the id is set to
the name of the container.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.list_(host=None, quiet=False)
List defined containers (running, stopped, and frozen) for the named
(or all) host(s).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.list [host=minion_id]
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.purge(name, delete_key=True, quiet=False)
Purge the named container and delete its minion key if present.
WARNING: Destroys all data associated with the container.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.purge name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.start(name, quiet=False)
Start the named container.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.start name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.stop(name, quiet=False)
Stop the named container.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.stop name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.lxc.unfreeze(name, quiet=False)
Unfreeze the named container
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run lxc.unfreeze name
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.manage
.sp
General management functions for salt, tools like seeing what hosts are up
and what hosts are down
.INDENT 0.0
.TP
.B salt.runners.manage.bootstrap(version=\(aqdevelop\(aq, script=None, hosts=\(aq\(aq, root_user=True)
Bootstrap minions with salt\-bootstrap
.INDENT 7.0
.TP
.B version
develop
Git tag of version to install
.TP
.B script
\fI\%https://bootstrap.saltstack.com\fP
Script to execute
.TP
.B hosts
Comma separated hosts [example: hosts="host1.local,host2.local"]
.TP
.B root_user
True
Prepend \fBroot@\fP to each host.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.bootstrap hosts="host1,host2"
salt\-run manage.bootstrap hosts="host1,host2" version="v0.17"
salt\-run manage.bootstrap hosts="host1,host2" version="v0.17" script="https://bootstrap.saltstack.com/develop"
salt\-run manage.bootstrap hosts="ec2\-user@host1,ec2\-user@host2" root_user=False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.bootstrap_psexec(hosts=\(aq\(aq, master=None, version=None, arch=\(aqwin32\(aq, installer_url=None, username=None, password=None)
Bootstrap Windows minions via PsExec.
.INDENT 7.0
.TP
.B hosts
Comma separated list of hosts to deploy the Windows Salt minion.
.TP
.B master
Address of the Salt master passed as an argument to the installer.
.TP
.B version
Point release of installer to download. Defaults to the most recent.
.TP
.B arch
Architecture of installer to download. Defaults to win32.
.TP
.B installer_url
URL of minion installer executable. Defaults to the latest version from
\fI\%http://docs.saltstack.com/downloads\fP
.TP
.B username
Optional user name for login on remote computer.
.TP
.B password
Password for optional username. If omitted, PsExec will prompt for one
to be entered for each host.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.bootstrap_psexec hosts=\(aqhost1,host2\(aq
salt\-run manage.bootstrap_psexec hosts=\(aqhost1,host2\(aq version=\(aq0.17\(aq username=\(aqDOMAIN\eAdministrator\(aq
salt\-run manage.bootstrap_psexec hosts=\(aqhost1,host2\(aq installer_url=\(aqhttp://exampledomain/salt\-installer.exe\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.down(removekeys=False)
Print a list of all the down or unresponsive salt minions
Optionally remove keys of down minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.down
salt\-run manage.down removekeys=True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.key_regen()
This routine is used to regenerate all keys in an environment. This is
invasive! ALL KEYS IN THE SALT ENVIRONMENT WILL BE REGENERATED!!
.sp
The key_regen routine sends a command out to minions to revoke the master
key and remove all minion keys, it then removes all keys from the master
and prompts the user to restart the master. The minions will all reconnect
and keys will be placed in pending.
.sp
After the master is restarted and minion keys are in the pending directory
execute a salt\-key \-A command to accept the regenerated minion keys.
.sp
The master \fImust\fP be restarted within 60 seconds of running this command or
the minions will think there is something wrong with the keys and abort.
.sp
Only Execute this runner after upgrading minions and master to 0.15.1 or
higher!
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.key_regen
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.present(subset=None, show_ipv4=False)
Print a list of all minions that are up according to Salt\(aqs presence
detection, no commands will be sent
.INDENT 7.0
.TP
.B subset
None
Pass in a CIDR range to filter minions by IP address.
.TP
.B show_ipv4
False
Also show the IP address each minion is connecting from.
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.present
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.safe_accept(target, expr_form=\(aqglob\(aq)
Accept a minion\(aqs public key after checking the fingerprint over salt\-ssh
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.safe_accept my_minion
salt\-run manage.safe_accept minion1,minion2 expr_form=list
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.status(output=True)
Print the status of all known salt minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.status
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.up()
Print a list of all of the minions that are up
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.up
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.manage.versions()
Check the version of active minions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.versions
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.mine
.sp
A runner to access data from the salt mine
.INDENT 0.0
.TP
.B salt.runners.mine.get(tgt, fun, tgt_type=\(aqglob\(aq, output=\(aqyaml\(aq)
Gathers the data from the specified minions\(aq mine, pass in the target,
function to look up and the target type
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run mine.get \(aq*\(aq network.interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.network
.sp
Network tools to run from the Master
.INDENT 0.0
.TP
.B salt.runners.network.wol(mac, bcast=\(aq255.255.255.255\(aq, destport=9)
Send a "Magic Packet" to wake up a Minion
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run network.wol 08\-00\-27\-13\-69\-77
salt\-run network.wol 080027136977 255.255.255.255 7
salt\-run network.wol 08:00:27:13:69:77 255.255.255.255 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.network.wollist(maclist, bcast=\(aq255.255.255.255\(aq, destport=9)
Send a "Magic Packet" to wake up a list of Minions.
This list must contain one MAC hardware address per line
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run network.wollist \(aq/path/to/maclist\(aq
salt\-run network.wollist \(aq/path/to/maclist\(aq 255.255.255.255 7
salt\-run network.wollist \(aq/path/to/maclist\(aq 255.255.255.255 7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.pillar
.sp
Functions to interact with the pillar compiler on the master
.INDENT 0.0
.TP
.B salt.runners.pillar.show_pillar(minion=\(aq*\(aq, **kwargs)
Returns the compiled pillar either of a specific minion
or just the global available pillars. I assume that no minion
is using the id \fB*\fP\&.
.sp
CLI Example:
.sp
shows minion specific pillar:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run pillar.show_pillar \(aqwww.example.com\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
shows global pillar:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run pillar.show_pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
shows global pillar for \(aqdev\(aq pillar environment:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run pillar.show_pillar \(aqsaltenv=dev\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
API Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.config
import salt.runner
opts = salt.config.master_config(\(aq/etc/salt/master\(aq)
runner = salt.runner.RunnerClient(opts)
pillar = runner.cmd(\(aqpillar.show_pillar\(aq, [])
print pillar¬
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.pillar.show_top(minion=None, saltenv=\(aqbase\(aq)
Returns the compiled top data for pillar for a specific minion. If no
minion is specified, we use the first minion we find.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run pillar.show_top
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.queue
.sp
General management and processing of queues.
.sp
This runner facilitates interacting with various queue backends such as the
included sqlite3 queue or the planned AWS SQS and Redis queues
.sp
The queue functions such as \fIinsert\fP, \fIdelete\fP, and \fIpop\fP can be used for
typical management of the queue.
.sp
The \fIprocess_queue\fP function pops the requested number of items from the queue
and creates a Salt Event that can then be processed by a Reactor. The
\fIprocess_queue\fP function can be called manually, or can be configured to run on
a schedule with the Salt Scheduler or regular system cron. It is also possible
to use the peer system to allow a minion to call the runner.
.sp
This runner, as well as the Queues system, is not api stable at this time.
.sp
There are many things that could potentially be done with queues within Salt.
For the time being the focus will be on queueing infrastructure actions on
specific minions. The queues generally will be populated with minion IDs. When
the \fIprocess_queue\fP runner function is called events are created on the Salt
Event bus that indicate the queue and a list of one or more minion IDs. The
reactor is set up to match on event tags for a specific queue and then take
infrastructure actions on those minion IDs. These actions might be to delete
the minion\(aqs key from the master, use salt\-cloud to destroy the vm, or some
other custom action.
.INDENT 0.0
.TP
.B salt.runners.queue.delete(queue, items, backend=\(aqsqlite\(aq)
Delete an item or items from a queue
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run queue.delete myqueue myitem
salt\-run queue.delete myqueue myitem backend=sqlite
salt\-run queue.delete myqueue "[\(aqitem1\(aq, \(aqitem2\(aq, \(aqitem3\(aq]"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.queue.insert(queue, items, backend=\(aqsqlite\(aq)
Add an item or items to a queue
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run queue.insert myqueue myitem
salt\-run queue.insert myqueue "[\(aqitem1\(aq, \(aqitem2\(aq, \(aqitem3\(aq]"
salt\-run queue.insert myqueue myitem backend=sqlite
salt\-run queue.insert myqueue "[\(aqitem1\(aq, \(aqitem2\(aq, \(aqitem3\(aq]" backend=sqlite
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.queue.list_items(queue, backend=\(aqsqlite\(aq)
List contents of a queue
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run queue.list_items myqueue
salt\-run queue.list_items myqueue backend=sqlite
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.queue.list_length(queue, backend=\(aqsqlite\(aq)
Provide the number of items in a queue
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run queue.list_length myqueue
salt\-run queue.list_length myqueue backend=sqlite
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.queue.list_queues(backend=\(aqsqlite\(aq)
Return a list of Salt Queues on the backend
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
salt\-run queue.list_queues
salt\-run queue.list_queues backend=sqlite
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.queue.pop(queue, quantity=1, backend=\(aqsqlite\(aq)
Pop one or more or all items from a queue
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run queue.pop myqueue
salt\-run queue.pop myqueue 6
salt\-run queue.pop myqueue all
salt\-run queue.pop myqueue 6 backend=sqlite
salt\-run queue.pop myqueue all backend=sqlite
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.queue.process_queue(queue, quantity=1, backend=\(aqsqlite\(aq)
Pop items off a queue and create an event on the Salt event bus to be
processed by a Reactor.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run queue.process_queue myqueue
salt\-run queue.process_queue myqueue 6
salt\-run queue.process_queue myqueue all backend=sqlite
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.search
.sp
Runner frontend to search system
.INDENT 0.0
.TP
.B salt.runners.search.query(term)
Query the search system
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run search.query foo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.state
.sp
Execute overstate functions
.INDENT 0.0
.TP
.B salt.runners.state.event(tagmatch=\(aq*\(aq, count=\-1, quiet=False, sock_dir=None, pretty=False)
Watch Salt\(aqs event bus and block until the given tag is matched
.sp
New in version 2014.7.0.
.sp
This is useful for utilizing Salt\(aqs event bus from shell scripts or for
taking simple actions directly from the CLI.
.sp
Enable debug logging to see ignored events.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBtagmatch\fP \-\- the event is written to stdout for each tag that matches
this pattern; uses the same matching semantics as Salt\(aqs Reactor.
.IP \(bu 2
\fBcount\fP \-\- this number is decremented for each event that matches the
\fBtagmatch\fP parameter; pass \fB\-1\fP to listen forever.
.IP \(bu 2
\fBquiet\fP \-\- do not print to stdout; just block
.IP \(bu 2
\fBsock_dir\fP \-\- path to the Salt master\(aqs event socket file.
.IP \(bu 2
\fBpretty\fP \-\- Output the JSON all on a single line if \fBFalse\fP (useful
for shell tools); pretty\-print the JSON output if \fBTrue\fP\&.
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Reboot a minion and run highstate when it comes back online
salt \(aqjerry\(aq system.reboot && \e\e
salt\-run state.event \(aqsalt/minion/jerry/start\(aq count=1 quiet=True && \e\e
salt \(aqjerry\(aq state.highstate
# Reboot multiple minions and run highstate when all are back online
salt \-L \(aqkevin,stewart,dave\(aq system.reboot && \e\e
salt\-run state.event \(aqsalt/minion/*/start\(aq count=3 quiet=True && \e\e
salt \-L \(aqkevin,stewart,dave\(aq state.highstate
# Watch the event bus forever in a shell while\-loop.
salt\-run state.event | while read \-r tag data; do
echo $tag
echo $data | jq \-colour\-output .
done
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following example monitors Salt\(aqs event bus in a background process
watching for returns for a given job. Requires a POSIX environment and jq
<\fI\%http://stedolan.github.io/jq/\fP>.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/sh
# Usage: ./eventlisten.sh \(aq*\(aq test.sleep 10
# Mimic fnmatch from the Python stdlib.
fnmatch() { case "$2" in $1) return 0 ;; *) return 1 ;; esac ; }
count() { printf \(aq%s\en\(aq "$#" ; }
listen() {
events=\(aqevents\(aq
mkfifo $events
exec 3<>$events # Hold the fd open.
# Start listening to events before starting the command to avoid race
# conditions.
salt\-run state.event count=\-1 >&3 &
events_pid=$!
(
timeout=$(( 60 * 60 ))
sleep $timeout
kill \-s USR2 $$
) &
timeout_pid=$!
# Give the runner a few to connect to the event bus.
printf \(aqSubscribing to the Salt event bus...\en\(aq
sleep 4
trap \(aq
excode=$?; trap \- EXIT;
exec 3>&\-
kill \(aq"${timeout_pid}"\(aq
kill \(aq"${events_pid}"\(aq
rm \(aq"${events}"\(aq
exit
echo $excode
\(aq INT TERM EXIT
trap \(aq
printf \(aq\e\(aq\(aqTimeout reached; exiting.\en\(aq\e\(aq\(aq
exit 4
\(aq USR2
# Run the command and get the JID.
jid=$(salt \-\-async "$@")
jid="${jid#*: }" # Remove leading text up to the colon.
# Create the event tags to listen for.
start_tag="salt/job/${jid}/new"
ret_tag="salt/job/${jid}/ret/*"
# \(ga\(garead\(ga\(ga will block when no events are going through the bus.
printf \(aqWaiting for tag %s\en\(aq "$ret_tag"
while read \-r tag data; do
if fnmatch "$start_tag" "$tag"; then
minions=$(printf \(aq%s\en\(aq "${data}" | jq \-r \(aq.["minions"][]\(aq)
num_minions=$(count $minions)
printf \(aqWaiting for %s minions.\en\(aq "$num_minions"
continue
fi
if fnmatch "$ret_tag" "$tag"; then
mid="${tag##*/}"
printf \(aqGot return for %s.\en\(aq "$mid"
printf \(aqPretty\-printing event: %s\en\(aq "$tag"
printf \(aq%s\en\(aq "$data" | jq .
minions="$(printf \(aq%s\en\(aq "$minions" | sed \-e \(aq/\(aq"$mid"\(aq/d\(aq)"
num_minions=$(count $minions)
if [ $((num_minions)) \-eq 0 ]; then
printf \(aqAll minions returned.\en\(aq
break
else
printf \(aqRemaining minions: %s\en\(aq "$num_minions"
fi
else
printf \(aqSkipping tag: %s\en\(aq "$tag"
continue
fi
done <&3
}
listen "$@"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.state.orchestrate(mods, saltenv=\(aqbase\(aq, test=None, exclude=None, pillar=None)
New in version 0.17.0.
.sp
Execute a state run from the master, used as a powerful orchestration
system.
.sp
\fBSEE ALSO:\fP
.INDENT 7.0
.INDENT 3.5
More Orchestrate documentation
.INDENT 0.0
.IP \(bu 2
\fIFull Orchestrate Tutorial\fP
.IP \(bu 2
\fBDocs for the master\-side state module\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.orchestrate webserver
salt\-run state.orchestrate webserver saltenv=dev test=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Changed in version 2014.1.1: Runner renamed from \fBstate.sls\fP to \fBstate.orchestrate\fP
.sp
Changed in version 2014.7.0: Runner uses the pillar variable
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.state.over(saltenv=\(aqbase\(aq, os_fn=None)
New in version 0.11.0.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
\fBstate.over\fP is deprecated in favor of \fBstate.orchestrate\fP, and
will be removed in the Salt feature release codenamed Boron.
(Three feature releases after the 2014.7.0 release, which is codenamed
Helium)
.UNINDENT
.UNINDENT
.sp
Execute an overstate sequence to orchestrate the executing of states
over a group of systems
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.over base /path/to/myoverstate.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.state.show_stages(saltenv=\(aqbase\(aq, os_fn=None)
New in version 0.11.0.
.sp
Display the OverState\(aqs stage data
.sp
CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run state.show_stages
salt\-run state.show_stages saltenv=dev /root/overstate.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.survey
.sp
A general map/reduce style salt runner for aggregating results
returned by several different minions.
.sp
New in version 2014.7.0.
.sp
Aggregated results are sorted by the size of the minion pools which returned
matching results.
.sp
Useful for playing the game: " some of these things are not like the others... "
when identifying discrepancies in a large infrastructure managed by salt.
.INDENT 0.0
.TP
.B salt.runners.survey.diff(*args, **kwargs)
Return the DIFFERENCE of the result sets returned by each matching minion
pool
.sp
New in version 2014.7.0.
.sp
These pools are determined from the aggregated and sorted results of
a salt command.
This command displays the "diffs" as a series of 2\-way differences\-\- namely
the difference between the FIRST displayed minion pool
(according to sort order) and EACH SUBSEQUENT minion pool result set.
Differences are displayed according to the Python "difflib.unified_diff()"
as in the case of the salt execution module "file.get_diff".
.sp
This command is submitted via a salt runner using the general form:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B salt\-run survey.diff [survey_sort=up/down] <target>
<salt\-execution\-module> <salt\-execution\-module parameters>
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Optionally accept a "survey_sort=" parameter. Default: "survey_sort=down"
.sp
CLI Example #1: ( Example to display the "differences of files" )
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run survey.diff survey_sort=up "*" cp.get_file_str file:///etc/hosts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.survey.hash(*args, **kwargs)
Return the MATCHING minion pools from the aggregated and sorted results of
a salt command
.sp
New in version 2014.7.0.
.sp
This command is submitted via a salt runner using the
general form:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B salt\-run survey.hash [survey_sort=up/down] <target>
<salt\-execution\-module> <salt\-execution\-module parameters>
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Optionally accept a "survey_sort=" parameter. Default: "survey_sort=down"
.sp
CLI Example #1: ( functionally equivalent to "salt\-run manage.up" )
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run survey.hash "*" test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
CLI Example #2: ( find an "outlier" minion config file )
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run survey.hash "*" file.get_hash /etc/salt/minion survey_sort=up
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.thin
.sp
The thin runner is used to manage the salt thin systems.
.sp
Salt Thin is a transport\-less version of Salt that can be used to run routines
in a standalone way. This runner has tools which generate the standalone salt
system for easy consumption.
.INDENT 0.0
.TP
.B salt.runners.thin.generate(extra_mods=\(aq\(aq, overwrite=False, so_mods=\(aq\(aq)
Generate the salt\-thin tarball and print the location of the tarball
Optional additional mods to include (e.g. mako) can be supplied as a comma
delimited string. Permits forcing an overwrite of the output file as well.
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run thin.generate
salt\-run thin.generate mako
salt\-run thin.generate mako,wempy 1
salt\-run thin.generate overwrite=1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.runners.virt
.sp
Control virtual machines via Salt
.INDENT 0.0
.TP
.B salt.runners.virt.force_off(name)
Force power down the named virtual machine
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.hyper_info(hyper=None)
Return information about the hypervisors connected to this master
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.init(name, cpu, mem, image, hyper=None, seed=True, nic=\(aqdefault\(aq, install=True)
This routine is used to create a new virtual machine. This routines takes
a number of options to determine what the newly created virtual machine
will look like.
.INDENT 7.0
.TP
.B name
The mandatory name of the new virtual machine. The name option is
also the minion id, all minions must have an id.
.TP
.B cpu
The number of cpus to allocate to this new virtual machine.
.TP
.B mem
The amount of memory to allocate tot his virtual machine. The number
is interpreted in megabytes.
.TP
.B image
The network location of the virtual machine image, commonly a location
on the salt fileserver, but http, https and ftp can also be used.
.TP
.B hyper
The hypervisor to use for the new virtual machine, if this is omitted
Salt will automatically detect what hypervisor to use.
.TP
.B seed
Set to False to prevent Salt from seeding the new virtual machine.
.TP
.B nic
The nic profile to use, defaults to the "default" nic profile which
assumes a single network interface per vm associated with the "br0"
bridge on the master.
.TP
.B install
Set to False to prevent Salt from installing a minion on the new vm
before it spins up.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.list(hyper=None, quiet=False)
List the virtual machines on each hyper, this is a simplified query,
showing only the virtual machine names belonging to each hypervisor.
A single hypervisor can be passed in to specify an individual hypervisor
to list.
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.migrate(name, target=\(aq\(aq)
Migrate a vm from one hypervisor to another. This routine will just start
the migration and display information on how to look up the progress.
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.next_hyper()
Return the hypervisor to use for the next autodeployed vm. This queries
the available hypervisors and executes some math the determine the most
"available" next hypervisor.
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.pause(name)
Pause the named vm
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.purge(name, delete_key=True)
Destroy the named vm
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.query(hyper=None, quiet=False)
Query the virtual machines. When called without options all hypervisors
are detected and a full query is returned. A single hypervisor can be
passed in to specify an individual hypervisor to query.
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.reset(name)
Force power down and restart an existing vm
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.resume(name)
Resume a paused vm
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.start(name)
Start a named virtual machine
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.virt.vm_info(name, quiet=False)
Return the information on the named vm
.UNINDENT
.SS salt.runners.winrepo
.sp
Runner to manage Windows software repo
.INDENT 0.0
.TP
.B salt.runners.winrepo.genrepo()
Generate win_repo_cachefile based on sls files in the win_repo
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run winrepo.genrepo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.winrepo.update_git_repos()
Checkout git repos containing Windows Software Package Definitions
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run winrepo.update_git_repos
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Writing Salt Runners
.sp
A Salt runner is written in a similar manner to a Salt execution module.
Both are Python modules which contain functions and each public function
is a runner which may be executed via the \fIsalt\-run\fP command.
.sp
For example, if a Python module named \fBtest.py\fP is created in the runners
directory and contains a function called \fBfoo\fP, the \fBtest\fP runner could be
invoked with the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-run test.foo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To add custom runners, put them in a directory and add it to
\fBrunner_dirs\fP in the master configuration file.
.SS Examples
.sp
Examples of runners can be found in the Salt distribution:
.sp
\fI\%https://github.com/saltstack/salt/blob/develop/salt/runners\fP
.sp
A simple runner that returns a well\-formatted list of the minions that are
responding to Salt calls could look like this:
.INDENT 0.0
.INDENT 3.5
.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__[\(aqconf_file\(aq])
minions = client.cmd(\(aq*\(aq, \(aqtest.ping\(aq, timeout=1)
for minion in sorted(minions):
print minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS 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.
.SS Mod Aggregate State Runtime Modifications
.sp
New in version 2014.7.0.
.sp
The mod_aggregate system was added in the 2014.7.0 release of Salt and allows for
runtime modification of the executing state data. Simply put, it allows for the
data used by Salt\(aqs state system to be changed on the fly at runtime, kind of
like a configuration management JIT compiler or a runtime import system. All in
all, it makes Salt much more dynamic.
.SS How it Works
.sp
The best example is the \fBpkg\fP state. One of the major requests in Salt has long
been adding the ability to install all packages defined at the same time. The
mod_aggregate system makes this a reality. While executing Salt\(aqs state system,
when a \fBpkg\fP state is reached the \fBmod_aggregate\fP function in the state module
is called. For \fBpkg\fP this function scans all of the other states that are slated
to run, and picks up the references to \fBname\fP and \fBpkgs\fP, then adds them to
\fBpkgs\fP in the first state. The result is a single call to yum, apt\-get,
pacman, etc as part of the first package install.
.SS How to Use it
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Since this option changes the basic behavior of the state runtime, after
it is enabled states should be executed using \fItest=True\fP to ensure that
the desired behavior is preserved.
.UNINDENT
.UNINDENT
.SS In config files
.sp
The first way to enable aggregation is with a configuration option in either
the master or minion configuration files. Salt will invoke \fBmod_aggregate\fP
the first time it encounters a state module that has aggregate support.
.sp
If this option is set in the master config it will apply to all state runs on
all minions, if set in the minion config it will only apply to said minion.
.sp
Enable for all states:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_aggregate: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Enable for only specific state modules:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_aggregate:
\- pkg
.ft P
.fi
.UNINDENT
.UNINDENT
.SS In states
.sp
The second way to enable aggregation is with the state\-level \fBaggregate\fP
keyword. In this configuration, Salt will invoke the \fBmod_aggregate\fP function
the first time it encounters this keyword. Any additional occurances of the
keyword will be ignored as the aggregation has already taken place.
.sp
The following example will trigger \fBmod_aggregate\fP when the \fBlamp_stack\fP
state is processed resulting in a single call to the underlying package
manager.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
lamp_stack:
pkg.installed:
\- pkgs:
\- php
\- mysql\-client
\- aggregate: True
memcached:
pkg.installed:
\- name: memcached
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Adding mod_aggregate to a State Module
.sp
Adding a mod_aggregate routine to an existing state module only requires adding
an additional function to the state module called mod_aggregate.
.sp
The mod_aggregate function just needs to accept three parameters and return the
low data to use. Since mod_aggregate is working on the state runtime level it
does need to manipulate \fIlow data\fP\&.
.sp
The three parameters are \fIlow\fP, \fIchunks\fP and \fIrunning\fP\&. The \fIlow\fP option is the
low data for the state execution which is about to be called. The \fIchunks\fP is
the list of all of the low data dictionaries which are being executed by the
runtime and the \fIrunning\fP dictionary is the return data from all of the state
executions which have already be executed.
.sp
This example, simplified from the pkg state, shows how to create mod_aggregate functions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def mod_aggregate(low, chunks, running):
\(aq\(aq\(aq
The mod_aggregate function which looks up all packages in the available
low chunks and merges them into a single pkgs ref in the present low data
\(aq\(aq\(aq
pkgs = []
# What functions should we aggregate?
agg_enabled = [
\(aqinstalled\(aq,
\(aqlatest\(aq,
\(aqremoved\(aq,
\(aqpurged\(aq,
]
# The \(galow\(ga data is just a dict with the state, function (fun) and
# arguments passed in from the sls
if low.get(\(aqfun\(aq) not in agg_enabled:
return low
# Now look into what other things are set to execute
for chunk in chunks:
# The state runtime uses "tags" to track completed jobs, it may
# look familiar with the _|\-
tag = salt.utils.gen_state_tag(chunk)
if tag in running:
# Already ran the pkg state, skip aggregation
continue
if chunk.get(\(aqstate\(aq) == \(aqpkg\(aq:
if \(aq__agg__\(aq in chunk:
continue
# Check for the same function
if chunk.get(\(aqfun\(aq) != low.get(\(aqfun\(aq):
continue
# Pull out the pkg names!
if \(aqpkgs\(aq in chunk:
pkgs.extend(chunk[\(aqpkgs\(aq])
chunk[\(aq__agg__\(aq] = True
elif \(aqname\(aq in chunk:
pkgs.append(chunk[\(aqname\(aq])
chunk[\(aq__agg__\(aq] = True
if pkgs:
if \(aqpkgs\(aq in low:
low[\(aqpkgs\(aq].extend(pkgs)
else:
low[\(aqpkgs\(aq] = pkgs
# The low has been modified and needs to be returned to the state
# runtime for execution
return low
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Altering States
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This documentation has been moved \fIhere\fP\&.
.UNINDENT
.UNINDENT
.SS File State Backups
.sp
In 0.10.2 a new feature was added for backing up files that are replaced by
the file.managed and file.recurse states. The new feature is called the backup
mode. Setting the backup mode is easy, but it can be set in a number of
places.
.sp
The backup_mode can be set in the minion config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
backup_mode: minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or it can be set for each file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/ssh/sshd_config:
file.managed:
\- source: salt://ssh/sshd_config
\- backup: minion
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Backed\-up Files
.sp
The files will be saved in the minion cachedir under the directory named
\fBfile_backup\fP\&. The files will be in the location relative to where they
were under the root filesystem and be appended with a timestamp. This should
make them easy to browse.
.SS Interacting with Backups
.sp
Starting with version 0.17.0, it will be possible to list, restore, and delete
previously\-created backups.
.SS Listing
.sp
The backups for a given file can be listed using \fBfile.list_backups\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt foo.bar.com file.list_backups /tmp/foo.txt
foo.bar.com:
\-\-\-\-\-\-\-\-\-\-
0:
\-\-\-\-\-\-\-\-\-\-
Backup Time:
Sat Jul 27 2013 17:48:41.738027
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:41_738027_2013
Size:
13
1:
\-\-\-\-\-\-\-\-\-\-
Backup Time:
Sat Jul 27 2013 17:48:28.369804
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013
Size:
35
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Restoring
.sp
Restoring is easy using \fBfile.restore_backup\fP, just pass the path and the numeric id
found with \fBfile.list_backups\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt foo.bar.com file.restore_backup /tmp/foo.txt 1
foo.bar.com:
\-\-\-\-\-\-\-\-\-\-
comment:
Successfully restored /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013 to /tmp/foo.txt
result:
True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The existing file will be backed up, just in case, as can be seen if
\fBfile.list_backups\fP is run again:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt foo.bar.com file.list_backups /tmp/foo.txt
foo.bar.com:
\-\-\-\-\-\-\-\-\-\-
0:
\-\-\-\-\-\-\-\-\-\-
Backup Time:
Sat Jul 27 2013 18:00:19.822550
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_18:00:19_822550_2013
Size:
53
1:
\-\-\-\-\-\-\-\-\-\-
Backup Time:
Sat Jul 27 2013 17:48:41.738027
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:41_738027_2013
Size:
13
2:
\-\-\-\-\-\-\-\-\-\-
Backup Time:
Sat Jul 27 2013 17:48:28.369804
Location:
/var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013
Size:
35
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Since no state is being run, restoring a file will not trigger any watches
for the file. So, if you are restoring a config file for a service, it will
likely still be necessary to run a \fBservice.restart\fP\&.
.UNINDENT
.UNINDENT
.SS Deleting
.sp
Deleting backups can be done using mod:\fIfile.delete_backup
<salt.modules.file.delete_backup>\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt foo.bar.com file.delete_backup /tmp/foo.txt 0
foo.bar.com:
\-\-\-\-\-\-\-\-\-\-
comment:
Successfully removed /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_18:00:19_822550_2013
result:
True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Understanding State Compiler Ordering
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This tutorial is an intermediate level tutorial. Some basic understanding
of the state system and writing Salt Formulas is assumed.
.UNINDENT
.UNINDENT
.sp
Salt\(aqs state system is built to deliver all of the power of configuration
management systems without sacrificing simplicity. This tutorial is made to
help users understand in detail just how the order is defined for state
executions in Salt.
.sp
This tutorial is written to represent the behavior of Salt as of version
0.17.0.
.SS Compiler Basics
.sp
To understand ordering in depth some very basic knowledge about the state
compiler is very helpful. No need to worry though, this is very high level!
.SS High Data and Low Data
.sp
When defining Salt Formulas in YAML the data that is being represented is
referred to by the compiler as High Data. When the data is initially
loaded into the compiler it is a single large python dictionary, this
dictionary can be viewed raw by running:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This "High Data" structure is then compiled down to "Low Data". The Low
Data is what is matched up to create individual executions in Salt\(aqs
configuration management system. The
low data is an ordered list of single state calls to execute. Once the
low data is compiled the evaluation order can be seen.
.sp
The low data can be viewed by running:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_lowstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The state execution module contains MANY functions for evaluating the
state system and is well worth a read! These routines can be very useful
when debugging states or to help deepen one\(aqs understanding of Salt\(aqs
state system.
.UNINDENT
.UNINDENT
.sp
As an example, a state written thusly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
\- name: httpd
service.running:
\- name: httpd
\- watch:
\- file: apache_conf
\- pkg: apache
apache_conf:
file.managed:
\- name: /etc/httpd/conf.d/httpd.conf
\- source: salt://apache/httpd.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will have High Data which looks like this represented in json:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
"apache": {
"pkg": [
{
"name": "httpd"
},
"installed",
{
"order": 10000
}
],
"service": [
{
"name": "httpd"
},
{
"watch": [
{
"file": "apache_conf"
},
{
"pkg": "apache"
}
]
},
"running",
{
"order": 10001
}
],
"__sls__": "blah",
"__env__": "base"
},
"apache_conf": {
"file": [
{
"name": "/etc/httpd/conf.d/httpd.conf"
},
{
"source": "salt://apache/httpd.conf"
},
"managed",
{
"order": 10002
}
],
"__sls__": "blah",
"__env__": "base"
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The subsequent Low Data will look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[
{
"name": "httpd",
"state": "pkg",
"__id__": "apache",
"fun": "installed",
"__env__": "base",
"__sls__": "blah",
"order": 10000
},
{
"name": "httpd",
"watch": [
{
"file": "apache_conf"
},
{
"pkg": "apache"
}
],
"state": "service",
"__id__": "apache",
"fun": "running",
"__env__": "base",
"__sls__": "blah",
"order": 10001
},
{
"name": "/etc/httpd/conf.d/httpd.conf",
"source": "salt://apache/httpd.conf",
"state": "file",
"__id__": "apache_conf",
"fun": "managed",
"__env__": "base",
"__sls__": "blah",
"order": 10002
}
]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This tutorial discusses the Low Data evaluation and the state runtime.
.SS Ordering Layers
.sp
Salt defines 2 order interfaces which are evaluated in the state runtime and
defines these orders in a number of passes.
.SS Definition Order
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The Definition Order system can be disabled by turning the option
\fIstate_auto_order\fP to \fIFalse\fP in the master configuration file.
.UNINDENT
.UNINDENT
.sp
The top level of ordering is the \fIDefinition Order\fP\&. The \fIDefinition Order\fP
is the order in which states are defined in salt formulas. This is very
straightforward on basic states which do not contain \fBinclude\fP statements
or a \fBtop\fP file, as the states are just ordered from the top of the file,
but the include system starts to bring in some simple rules for how the
\fIDefinition Order\fP is defined.
.sp
Looking back at the "Low Data" and "High Data" shown above, the order key has
been transparently added to the data to enable the \fIDefinition Order\fP\&.
.SS The Include Statement
.sp
Basically, if there is an include statement in a formula, then the formulas
which are included will be run BEFORE the contents of the formula which
is including them. Also, the include statement is a list, so they will be
loaded in the order in which they are included.
.sp
In the following case:
.sp
\fBfoo.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- bar
\- baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBbar.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- quo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBbaz.sls\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- qux
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the above case if \fIstate.sls foo\fP were called then the formulas will be
loaded in the following order:
.INDENT 0.0
.IP 1. 3
quo
.IP 2. 3
bar
.IP 3. 3
qux
.IP 4. 3
baz
.IP 5. 3
foo
.UNINDENT
.SS The \fIorder\fP Flag
.sp
The \fIDefinition Order\fP happens transparently in the background, but the
ordering can be explicitly overridden using the \fIorder\fP flag in states:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
\- name: httpd
\- order: 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This order flag will over ride the definition order, this makes it very
simple to create states that are always executed first, last or in specific
stages, a great example is defining a number of package repositories that
need to be set up before anything else, or final checks that need to be
run at the end of a state run by using \fIorder: last\fP or \fIorder: \-1\fP\&.
.sp
When the order flag is explicitly set the \fIDefinition Order\fP system will omit
setting an order for that state and directly use the order flag defined.
.SS Lexicographical Fall\-back
.sp
Salt states were written to ALWAYS execute in the same order. Before the
introduction of \fIDefinition Order\fP in version 0.17.0 everything was ordered
lexicographically according to the name of the state, then function then id.
.sp
This is the way Salt has always ensured that states always run in the same
order regardless of where they are deployed, the addition of the
\fIDefinition Order\fP method mealy makes this finite ordering easier to follow.
.sp
The lexicographical ordering is still applied but it only has any effect when
two order statements collide. This means that if multiple states are assigned
the same order number that they will fall back to lexicographical ordering
to ensure that every execution still happens in a finite order.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If running with \fIstate_auto_order: False\fP the \fIorder\fP key is not
set automatically, since the Lexicographical order can be derived
from other keys.
.UNINDENT
.UNINDENT
.SS Requisite Ordering
.sp
Salt states are fully declarative, in that they are written to declare the
state in which a system should be. This means that components can require that
other components have been set up successfully. Unlike the other ordering
systems, the \fIRequisite\fP system in Salt is evaluated at runtime.
.sp
The requisite system is also built to ensure that the ordering of execution
never changes, but is always the same for a given set of states. This is
accomplished by using a runtime that processes states in a completely
predictable order instead of using an event loop based system like other
declarative configuration management systems.
.SS Runtime Requisite Evaluation
.sp
The requisite system is evaluated as the components are found, and the
requisites are always evaluated in the same order. This explanation will
be followed by an example, as the raw explanation may be a little dizzying
at first as it creates a linear dependency evaluation sequence.
.sp
The "Low Data" is an ordered list or dictionaries, the state runtime evaluates
each dictionary in the order in which they are arranged in the list. When
evaluating a single dictionary it is checked for requisites, requisites are
evaluated in order, \fIrequire\fP then \fIwatch\fP then \fIprereq\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If using requisite in statements like require_in and watch_in these will
be compiled down to require and watch statements before runtime evaluation.
.UNINDENT
.UNINDENT
.sp
Each requisite contains an ordered list of requisites, these requisites are
looked up in the list of dictionaries and then executed. Once all requisites
have been evaluated and executed then the requiring state can safely be run
(or not run if requisites have not been met).
.sp
This means that the requisites are always evaluated in the same order, again
ensuring one of the core design principals of Salt\(aqs State system to ensure
that execution is always finite is intact.
.SS Simple Runtime Evaluation Example
.sp
Given the above "Low Data" the states will be evaluated in the following order:
.INDENT 0.0
.IP 1. 3
The pkg.installed is executed ensuring that the apache package is
installed, it contains no requisites and is therefore the first defined
state to execute.
.IP 2. 3
The service.running state is evaluated but NOT executed, a watch requisite
is found, therefore they are read in order, the runtime first checks for
the file, sees that it has not been executed and calls for the file state
to be evaluated.
.IP 3. 3
The file state is evaluated AND executed, since it, like the pkg state does
not contain any requisites.
.IP 4. 3
The evaluation of the service state continues, it next checks the pkg
requisite and sees that it is met, with all requisites met the service
state is now executed.
.UNINDENT
.SS Best Practice
.sp
The best practice in Salt is to choose a method and stick with it, official
states are written using requisites for all associations since requisites
create clean, traceable dependency trails and make for the most portable
formulas. To accomplish something similar to how classical imperative
systems function all requisites can be omitted and the \fBfailhard\fP option
then set to \fITrue\fP in the master configuration, this will stop all state runs at
the first instance of a failure.
.sp
In the end, using requisites creates very tight and fine grained states,
not using requisites makes full sequence runs and while slightly easier
to write, and gives much less control over the executions.
.SS Extending External SLS Data
.sp
Sometimes a state defined in one SLS file will need to be modified from a
separate SLS file. A good example of this is when an argument needs to be
overwritten or when a service needs to watch an additional state.
.SS The Extend Declaration
.sp
The standard way to extend is via the extend declaration. The extend
declaration is a top level declaration like \fBinclude\fP and encapsulates ID
declaration data included from other SLS files. A standard extend looks like
this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- http
\- ssh
extend:
apache:
file:
\- name: /etc/httpd/conf/httpd.conf
\- source: salt://http/httpd2.conf
ssh\-server:
service:
\- watch:
\- file: /etc/ssh/banner
/etc/ssh/banner:
file.managed:
\- source: salt://ssh/banner
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A few critical things happened here, first off the SLS files that are going to
be extended are included, then the extend dec is defined. Under the extend dec
2 IDs are extended, the apache ID\(aqs file state is overwritten with a new name
and source. Than the ssh server is extended to watch the banner file in
addition to anything it is already watching.
.SS Extend is a Top Level Declaration
.sp
This means that \fBextend\fP can only be called once in an sls, if if is used
twice then only one of the extend blocks will be read. So this is WRONG:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- http
\- ssh
extend:
apache:
file:
\- name: /etc/httpd/conf/httpd.conf
\- source: salt://http/httpd2.conf
# Second extend will overwrite the first!! Only make one
extend:
ssh\-server:
service:
\- watch:
\- file: /etc/ssh/banner
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The Requisite "in" Statement
.sp
Since one of the most common things to do when extending another SLS is to add
states for a service to watch, or anything for a watcher to watch, the
requisite in statement was added to 0.9.8 to make extending the watch and
require lists easier. The ssh\-server extend statement above could be more
cleanly defined like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- ssh
/etc/ssh/banner:
file.managed:
\- source: salt://ssh/banner
\- watch_in:
\- service: ssh\-server
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Rules to Extend By
.sp
There are a few rules to remember when extending states:
.INDENT 0.0
.IP 1. 3
Always include the SLS being extended with an include declaration
.IP 2. 3
Requisites (watch and require) are appended to, everything else is
overwritten
.IP 3. 3
extend is a top level declaration, like an ID declaration, cannot be
declared twice in a single SLS
.IP 4. 3
Many IDs can be extended under the extend declaration
.UNINDENT
.SS 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:
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.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.
.SS Global State Arguments
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This documentation has been moved \fIhere\fP\&.
.UNINDENT
.UNINDENT
.SS Highstate data structure definitions
.SS The Salt State Tree
.sp
A state tree is a collection of \fBSLS\fP files that live under the directory
specified in \fBfile_roots\fP\&. A state tree can be organized into
\fBSLS modules\fP\&.
.SS Top file
.sp
The main state file that instructs minions what environment and modules to use
during state execution.
.sp
Configurable via \fBstate_top\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBA detailed description of the top file\fP
.UNINDENT
.UNINDENT
.SS Include declaration
.sp
Defines a list of \fI\%Module reference\fP strings to include in this \fBSLS\fP\&.
.sp
Occurs only in the top level of the highstate structure.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- edit.vim
\- http.server
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Module reference
.sp
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\&.
.SS ID declaration
.sp
Defines an individual highstate component. Always references a value of a
dictionary containing keys referencing \fI\%State declaration\fP and
\fI\%Requisite declaration\fP\&. Can be overridden by a \fI\%Name declaration\fP or
a \fI\%Names declaration\fP\&.
.sp
Occurs on the top level or under the \fI\%Extend declaration\fP\&.
.sp
Must be unique across entire state tree. If the same ID declaration is
used twice, only the first one matched will be used. All subsequent
ID declarations with the same name will be ignored.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Naming gotchas
.sp
In Salt versions earlier than 0.9.7, ID declarations containing dots would
result in unpredictable highstate output.
.UNINDENT
.UNINDENT
.SS Extend declaration
.sp
Extends a \fI\%Name declaration\fP from an included \fBSLS module\fP\&. The
keys of the extend declaration always define existing :ref\(gaID declaration\(ga
which have been defined in included
\fBSLS modules\fP\&.
.sp
Occurs only in the top level and defines a dictionary.
.sp
States cannot be extended more than once in a single state run.
.sp
Extend declarations are useful for adding\-to or overriding parts of a
\fI\%State declaration\fP that is defined in another \fBSLS\fP file. In the
following contrived example, the shown \fBmywebsite.sls\fP file is \fBinclude\fP
\-ing and \fBextend\fP \-ing the \fBapache.sls\fP module in order to add a \fBwatch\fP
declaration that will restart Apache whenever the Apache configuration file,
\fBmywebsite\fP changes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- apache
extend:
apache:
service:
\- watch:
\- file: mywebsite
mywebsite:
file.managed:
\- name: /var/www/mysite
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
watch_in and require_in
.sp
Sometimes it is more convenient to use the \fIwatch_in\fP or \fIrequire_in\fP syntax
instead of extending another \fBSLS\fP file.
.sp
\fBState Requisites\fP
.UNINDENT
.UNINDENT
.SS State declaration
.sp
A list which contains one string defining the \fI\%Function declaration\fP and
any number of \fI\%Function arg declaration\fP dictionaries.
.sp
Can, optionally, contain a number of additional components like the
name override components — \fI\%name\fP and
\fI\%names\fP\&. Can also contain \fI\%requisite
declarations\fP\&.
.sp
Occurs under an \fI\%ID declaration\fP\&.
.SS Requisite declaration
.sp
A list containing \fI\%requisite 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 \fI\%State declaration\fP or as a
key under an \fI\%ID declaration\fP\&.
.SS Requisite reference
.sp
A single key dictionary. The key is the name of the referenced
\fI\%State declaration\fP and the value is the ID of the referenced
\fI\%ID declaration\fP\&.
.sp
Occurs as a single index in a \fI\%Requisite declaration\fP list.
.SS Function declaration
.sp
The name of the function to call within the state. A state declaration
can contain only a single function declaration.
.sp
For example, the following state declaration calls the \fBinstalled\fP function in the \fBpkg\fP state module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed: []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The function can be declared inline with the state as a shortcut.
The actual data structure is compiled to this form:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg:
\- installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where the function is a string in the body of the state declaration.
Technically when the function is declared in dot notation the compiler
converts it to be a string in the state declaration list. Note that the
use of the first example more than once in an ID declaration is invalid
yaml.
.sp
INVALID:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed
service.running
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When passing a function without arguments and another state declaration
within a single ID declaration, then the long or "standard" format
needs to be used since otherwise it does not represent a valid data
structure.
.sp
VALID:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed: []
service.running: []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Occurs as the only index in the \fI\%State declaration\fP list.
.SS Function arg declaration
.sp
A single key dictionary referencing a Python type which is to be passed
to the named \fI\%Function declaration\fP as a parameter. The type must
be the data type expected by the function.
.sp
Occurs under a \fI\%Function declaration\fP\&.
.sp
For example in the following state declaration \fBuser\fP, \fBgroup\fP, and
\fBmode\fP are passed as arguments to the \fBmanaged\fP function in the \fBfile\fP state module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/http/conf/http.conf:
file.managed:
\- user: root
\- group: root
\- mode: 644
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Name declaration
.sp
Overrides the \fBname\fP argument of a \fI\%State declaration\fP\&. If
\fBname\fP is not specified the \fI\%ID declaration\fP satisfies the
\fBname\fP argument.
.sp
The name is always a single key dictionary referencing a string.
.sp
Overriding \fBname\fP is useful for a variety of scenarios.
.sp
For example, avoiding clashing ID declarations. The following two state
declarations cannot both have \fB/etc/motd\fP as the ID declaration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
motd_perms:
file.managed:
\- name: /etc/motd
\- mode: 644
motd_quote:
file.append:
\- name: /etc/motd
\- text: "Of all smells, bread; of all tastes, salt."
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Another common reason to override \fBname\fP is if the ID declaration is long and
needs to be referenced in multiple places. In the example below it is much
easier to specify \fBmywebsite\fP than to specify
\fB/etc/apache2/sites\-available/mywebsite.com\fP multiple times:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mywebsite:
file.managed:
\- name: /etc/apache2/sites\-available/mywebsite.com
\- source: salt://mywebsite.com
a2ensite mywebsite.com:
cmd.wait:
\- unless: test \-L /etc/apache2/sites\-enabled/mywebsite.com
\- watch:
\- file: mywebsite
apache2:
service.running:
\- watch:
\- file: mywebsite
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Names declaration
.sp
Expands the contents of the containing \fI\%State declaration\fP into
multiple state declarations, each with its own name.
.sp
For example, given the following state declaration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python\-pkgs:
pkg.installed:
\- names:
\- python\-django
\- python\-crypto
\- python\-yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once converted into the lowstate data structure the above state
declaration will be expanded into the following three state declarations:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python\-django:
pkg.installed
python\-crypto:
pkg.installed
python\-yaml:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Other values can be overridden during the expansion by providing an additional
dictionary level.
.sp
New in version 2014.7.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ius:
pkgrepo.managed:
\- humanname: IUS Community Packages for Enterprise Linux 6 \- $basearch
\- gpgcheck: 1
\- baseurl: http://mirror.rackspace.com/ius/stable/CentOS/6/$basearch
\- gpgkey: http://dl.iuscommunity.org/pub/ius/IUS\-COMMUNITY\-GPG\-KEY
\- names:
\- ius
\- ius\-devel:
\- baseurl: http://mirror.rackspace.com/ius/development/CentOS/6/$basearch
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Large example
.sp
Here is the layout in yaml using the names of the highdata structure
components.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<Include Declaration>:
\- <Module Reference>
\- <Module Reference>
<Extend Declaration>:
<ID Declaration>:
[<overrides>]
# standard declaration
<ID Declaration>:
<State Module>:
\- <Function>
\- <Function Arg>
\- <Function Arg>
\- <Function Arg>
\- <Name>: <name>
\- <Requisite Declaration>:
\- <Requisite Reference>
\- <Requisite Reference>
# inline function and names
<ID Declaration>:
<State Module>.<Function>:
\- <Function Arg>
\- <Function Arg>
\- <Function Arg>
\- <Names>:
\- <name>
\- <name>
\- <name>
\- <Requisite Declaration>:
\- <Requisite Reference>
\- <Requisite Reference>
# multiple states for single id
<ID Declaration>:
<State Module>:
\- <Function>
\- <Function Arg>
\- <Name>: <name>
\- <Requisite Declaration>:
\- <Requisite Reference>
<State Module>:
\- <Function>
\- <Function Arg>
\- <Names>:
\- <name>
\- <name>
\- <Requisite Declaration>:
\- <Requisite Reference>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Include and Exclude
.sp
Salt sls files can include other sls files and exclude sls files that have been
otherwise included. This allows for an sls file to easily extend or manipulate
other sls files.
.SS Include
.sp
When other sls files are included, everything defined in the included sls file
will be added to the state run. When including define a list of sls formulas
to include:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- http
\- libvirt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The include statement will include sls formulas from the same environment
that the including sls formula is in. But the environment can be explicitly
defined in the configuration to override the running environment, therefore
if an sls formula needs to be included from an external environment named "dev"
the following syntax is used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- dev: http
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Relative Include
.sp
In Salt 0.16.0 the capability to include sls formulas which are relative to
the running sls formula was added, simply precede the formula name with a
\fI\&.\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- .virt
\- .virt.hyper
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Exclude
.sp
The exclude statement, added in Salt 0.10.3 allows an sls to hard exclude
another sls file or a specific id. The component is excluded after the
high data has been compiled, so nothing should be able to override an
exclude.
.sp
Since the exclude can remove an id or an sls the type of component to
exclude needs to be defined. an exclude statement that verifies that the
running highstate does not contain the \fIhttp\fP sls and the \fI/etc/vimrc\fP id
would look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
exclude:
\- sls: http
\- id: /etc/vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS State System Layers
.sp
The Salt state system is comprised of multiple layers. While using Salt does
not require an understanding of the state layers, a deeper understanding of
how Salt compiles and manages states can be very beneficial.
.SS Function Call
.sp
The lowest layer of functionality in the state system is the direct state
function call. State executions are executions of single state functions at
the core. These individual functions are defined in state modules and can
be called directly via the \fBstate.single\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.single pkg.installed name=\(aqvim\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Low Chunk
.sp
The low chunk is the bottom of the Salt state compiler. This is a data
representation of a single function call. The low chunk is sent to the state
caller and used to execute a single state function.
.sp
A single low chunk can be executed manually via the \fBstate.low\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.low \(aq{name: vim, state: pkg, fun: installed}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The passed data reflects what the state execution system gets after compiling
the data down from sls formulas.
.SS Low State
.sp
The \fILow State\fP layer is the list of low chunks "evaluated" in order. To see
what the low state looks like for a highstate, run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_lowstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will display the raw lowstate in the order which each low chunk will be
evaluated. The order of evaluation is not necessarily the order of execution,
since requisites are evaluated at runtime. Requisite execution and evaluation
is finite; this means that the order of execution can be ascertained with 100%
certainty based on the order of the low state.
.SS High Data
.sp
High data is the data structure represented in YAML via SLS files. The High
data structure is created by merging the data components rendered inside sls
files (or other render systems). The High data can be easily viewed by
executing the \fBstate.show_highstate\fP or \fBstate.show_sls\fP functions. Since
this data is a somewhat complex data structure, it may be easier to read using
the json, yaml, or pprint outputters:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_highstate \-\-out yaml
salt \(aq*\(aq state.show_sls edit.vim \-\-out pprint
.ft P
.fi
.UNINDENT
.UNINDENT
.SS SLS
.sp
Above "High Data", the logical layers are no longer technically required to be
executed, or to be executed in a hierarchy. This means that how the High data
is generated is optional and very flexible. The SLS layer allows for many
mechanisms to be used to render sls data from files or to use the fileserver
backend to generate sls and file data from external systems.
.sp
The SLS layer can be called directly to execute individual sls formulas.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
SLS Formulas have historically been called "SLS files". This is because a
single SLS was only constituted in a single file. Now the term
"SLS Formula" better expresses how a compartmentalized SLS can be expressed
in a much more dynamic way by combining pillar and other sources, and the
SLS can be dynamically generated.
.UNINDENT
.UNINDENT
.sp
To call a single SLS formula named \fBedit.vim\fP, execute \fBstate.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.sls edit.vim
.ft P
.fi
.UNINDENT
.UNINDENT
.SS HighState
.sp
Calling SLS directly logically assigns what states should be executed from the
context of the calling minion. The Highstate layer is used to allow for full
contextual assignment of what is executed where to be tied to groups of, or
individual, minions entirely from the master. This means that the environment of
a minion, and all associated execution data pertinent to said minion, can be
assigned from the master without needing to execute or configure anything on
the target minion. This also means that the minion can independently retrieve
information about its complete configuration from the master.
.sp
To execute the High State call \fBstate.highstate\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.SS OverState
.sp
The overstate layer expresses the highest functional layer of Salt\(aqs automated
logic systems. The Overstate allows for stateful and functional orchestration
of routines from the master. The overstate defines in data execution stages
which minions should execute states, or functions, and in what order using
requisite logic.
.SS The Orchestrate Runner
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This documentation has been moved \fIhere\fP\&.
.UNINDENT
.UNINDENT
.SS Ordering States
.sp
The way in which configuration management systems are executed is a hotly
debated topic in the configuration management world. Two
major philosophies exist on the subject, to either execute in an imperative
fashion where things are executed in the order in which they are defined, or
in a declarative fashion where dependencies need to be mapped between objects.
.sp
Imperative ordering is finite and generally considered easier to write, but
declarative ordering is much more powerful and flexible but generally considered
more difficult to create.
.sp
Salt has been created to get the best of both worlds. States are evaluated in
a finite order, which guarantees that states are always executed in the same
order, and the states runtime is declarative, making Salt fully aware of
dependencies via the \fIrequisite\fP system.
.SS State Auto Ordering
.sp
Salt always executes states in a finite manner, meaning that they will always
execute in the same order regardless of the system that is executing them.
But in Salt 0.17.0, the \fBstate_auto_order\fP option was added. This option
makes states get evaluated in the order in which they are defined in sls
files.
.sp
The evaluation order makes it easy to know what order the states will be
executed in, but it is important to note that the requisite system will
override the ordering defined in the files, and the \fBorder\fP option described
below will also override the order in which states are defined in sls files.
.sp
If the classic ordering is preferred (lexicographic), then set
\fBstate_auto_order\fP to \fBFalse\fP in the master configuration file.
.SS Requisite Statements
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This document represents behavior exhibited by Salt requisites as of
version 0.9.7 of Salt.
.UNINDENT
.UNINDENT
.sp
Often when setting up states any single action will require or depend on
another action. Salt allows for the building of relationships between states
with requisite statements. A requisite statement ensures that the named state
is evaluated before the state requiring it. There are three types of requisite
statements in Salt, \fBrequire\fP, \fBwatch\fP and \fBprereq\fP\&.
.sp
These requisite statements are applied to a specific state declaration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed: []
file.managed:
\- name: /etc/httpd/conf/httpd.conf
\- source: salt://httpd/httpd.conf
\- require:
\- pkg: httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, the \fBrequire\fP requisite is used to declare that the file
/etc/httpd/conf/httpd.conf should only be set up if the pkg state executes
successfully.
.sp
The requisite system works by finding the states that are required and
executing them before the state that requires them. Then the required states
can be evaluated to see if they have executed correctly.
.sp
Require statements can refer to any state defined in Salt. The basic examples
are \fIpkg\fP, \fIservice\fP and \fIfile\fP, but any used state can be referenced.
.sp
In addition to state declarations such as pkg, file, etc., \fBsls\fP type requisites
are also recognized, and essentially allow \(aqchaining\(aq of states. This provides a
mechanism to ensure the proper sequence for complex state formulas, especially when
the discrete states are split or groups into separate sls files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- network
httpd:
pkg.installed: []
service.running:
\- require:
\- pkg: httpd
\- sls: network
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, the httpd service running state will not be applied
(i.e., the httpd service will not be started) unless both the https package is
installed AND the network state is satisfied.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Requisite matching
.sp
Requisites match on both the ID Declaration and the \fBname\fP parameter.
Therefore, if using the \fBpkgs\fP or \fBsources\fP argument to install
a list of packages in a pkg state, it\(aqs important to note that it is
impossible to match an individual package in the list, since all packages
are installed as a single state.
.UNINDENT
.UNINDENT
.SS Multiple Requisites
.sp
The requisite statement is passed as a list, allowing for the easy addition of
more requisites. Both requisite types can also be separately declared:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed: []
service.running:
\- enable: True
\- watch:
\- file: /etc/httpd/conf/httpd.conf
\- require:
\- pkg: httpd
\- user: httpd
\- group: httpd
file.managed:
\- name: /etc/httpd/conf/httpd.conf
\- source: salt://httpd/httpd.conf
\- require:
\- pkg: httpd
user.present: []
group.present: []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, the httpd service is only going to be started if the package,
user, group and file are executed successfully.
.SS Requisite Documentation
.sp
For detailed information on each of the individual requisites, \fIplease
look here.\fP
.SS The Order Option
.sp
Before using the \fIorder\fP option, remember that the majority of state ordering
should be done with a \fIrequisite\-declaration\fP, and that a requisite
declaration will override an \fIorder\fP option, so a state with order option
should not require or required by other states.
.sp
The order option is used by adding an order number to a state declaration
with the option \fIorder\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed:
\- order: 1
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
Certain circumstances will present a situation where it is desirable to send
a state to the end of the line. To do this, set the order to \fBlast\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed:
\- order: last
.ft P
.fi
.UNINDENT
.UNINDENT
.SS OverState System
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This documentation has been moved \fIhere\fP\&.
.UNINDENT
.UNINDENT
.SS State Providers
.sp
New in version 0.9.8.
.sp
Salt predetermines what modules should be mapped to what uses based on the
properties of a system. These determinations are generally made for modules
that provide things like package and service management.
.sp
Sometimes in states, it may be necessary to use an alternative module to
provide the needed functionality. For instance, an older Arch Linux system may
not be running systemd, so instead of using the systemd service module, you can
revert to the default service module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
service.running:
\- enable: True
\- provider: service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this instance, the basic \fBservice\fP module (which
manages \fBsysvinit\fP\-based services) will replace the
\fBsystemd\fP module which is used by default on Arch Linux.
.sp
However, if it is necessary to make this override for most or every service,
it is better to just override the provider in the minion config file, as
described in the section below.
.SS Setting a Provider in the Minion Config File
.sp
Sometimes, when running Salt on custom Linux spins, or distribution that are derived
from other distributions, Salt does not successfully detect providers. The providers
which are most likely to be affected by this are:
.INDENT 0.0
.IP \(bu 2
pkg
.IP \(bu 2
service
.IP \(bu 2
user
.IP \(bu 2
group
.UNINDENT
.sp
When something like this happens, rather than specifying the provider manually
in each state, it easier to use the \fBproviders\fP parameter in the
minion config file to set the provider.
.sp
If you end up needing to override a provider because it was not detected,
please let us know! File an issue on the \fI\%issue tracker\fP, and provide the
output from the \fBgrains.items\fP function,
taking care to sanitize any sensitive information.
.sp
Below are tables that should help with deciding which provider to use if one
needs to be overridden.
.SS Provider: \fBpkg\fP
.TS
center;
|l|l|.
_
T{
Execution Module
T} T{
Used for
T}
_
T{
apt
T} T{
Debian/Ubuntu\-based distros which use \fBapt\-get(8)\fP
for package management
T}
_
T{
brew
T} T{
Mac OS software management using \fI\%Homebrew\fP
T}
_
T{
ebuild
T} T{
Gentoo\-based systems (utilizes the \fBportage\fP python
module as well as \fBemerge(1)\fP)
T}
_
T{
freebsdpkg
T} T{
FreeBSD\-based OSes using \fBpkg_add(1)\fP
T}
_
T{
openbsdpkg
T} T{
OpenBSD\-based OSes using \fBpkg_add(1)\fP
T}
_
T{
pacman
T} T{
Arch Linux\-based distros using \fBpacman(8)\fP
T}
_
T{
pkgin
T} T{
NetBSD\-based OSes using \fBpkgin(1)\fP
T}
_
T{
pkgng
T} T{
FreeBSD\-based OSes using \fBpkg(8)\fP
T}
_
T{
pkgutil
T} T{
Solaris\-based OSes using \fI\%OpenCSW\fP\(aqs \fBpkgutil(1)\fP
T}
_
T{
solarispkg
T} T{
Solaris\-based OSes using \fBpkgadd(1M)\fP
T}
_
T{
win_pkg
T} T{
Windows
T}
_
T{
yumpkg
T} T{
RedHat\-based distros and derivatives (wraps \fByum(8)\fP)
T}
_
T{
zypper
T} T{
SUSE\-based distros using \fBzypper(8)\fP
T}
_
.TE
.SS Provider: \fBservice\fP
.TS
center;
|l|l|.
_
T{
Execution Module
T} T{
Used for
T}
_
T{
debian_service
T} T{
Debian (non\-systemd)
T}
_
T{
freebsdservice
T} T{
FreeBSD\-based OSes using \fBservice(8)\fP
T}
_
T{
gentoo_service
T} T{
Gentoo Linux using \fBsysvinit\fP and
\fBrc\-update(8)\fP
T}
_
T{
launchctl
T} T{
Mac OS hosts using \fBlaunchctl(1)\fP
T}
_
T{
netbsdservice
T} T{
NetBSD\-based OSes
T}
_
T{
openbsdservice
T} T{
OpenBSD\-based OSes
T}
_
T{
rh_service
T} T{
RedHat\-based distros and derivatives using
\fBservice(8)\fP and \fBchkconfig(8)\fP\&. Supports both
pure sysvinit and mixed sysvinit/upstart systems.
T}
_
T{
service
T} T{
Fallback which simply wraps sysvinit scripts
T}
_
T{
smf
T} T{
Solaris\-based OSes which use SMF
T}
_
T{
systemd
T} T{
Linux distros which use systemd
T}
_
T{
upstart
T} T{
Ubuntu\-based distros using upstart
T}
_
T{
win_service
T} T{
Windows
T}
_
.TE
.SS Provider: \fBuser\fP
.TS
center;
|l|l|.
_
T{
Execution Module
T} T{
Used for
T}
_
T{
useradd
T} T{
Linux, NetBSD, and OpenBSD systems using
\fBuseradd(8)\fP, \fBuserdel(8)\fP, and \fBusermod(8)\fP
T}
_
T{
pw_user
T} T{
FreeBSD\-based OSes using \fBpw(8)\fP
T}
_
T{
solaris_user
T} T{
Solaris\-based OSes using \fBuseradd(1M)\fP,
\fBuserdel(1M)\fP, and \fBusermod(1M)\fP
T}
_
T{
win_useradd
T} T{
Windows
T}
_
.TE
.SS Provider: \fBgroup\fP
.TS
center;
|l|l|.
_
T{
Execution Module
T} T{
Used for
T}
_
T{
groupadd
T} T{
Linux, NetBSD, and OpenBSD systems using
\fBgroupadd(8)\fP, \fBgroupdel(8)\fP, and \fBgroupmod(8)\fP
T}
_
T{
pw_group
T} T{
FreeBSD\-based OSes using \fBpw(8)\fP
T}
_
T{
solaris_group
T} T{
Solaris\-based OSes using \fBgroupadd(1M)\fP,
\fBgroupdel(1M)\fP, and \fBgroupmod(1M)\fP
T}
_
T{
win_groupadd
T} T{
Windows
T}
_
.TE
.SS Arbitrary Module Redirects
.sp
The provider statement can also be used for more powerful means, instead of
overwriting or extending the module used for the named service an arbitrary
module can be used to provide certain functionality.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
emacs:
pkg.installed:
\- provider:
\- cmd: customcmd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, the state is being instructed to use a custom module to invoke
commands.
.sp
Arbitrary module redirects can be used to dramatically change the behavior of a
given state.
.SS Requisites and Other Global State Arguments
.SS Requisites
.sp
The Salt requisite system is used to create relationships between states. The
core idea being that, when one state is dependent somehow on another, that
inter\-dependency can be easily defined.
.sp
Requisites come in two types: Direct requisites (such as \fBrequire\fP),
and requisite_ins (such as \fBrequire_in\fP). The relationships are
directional: a direct requisite requires something from another state.
However, a requisite_in inserts a requisite into the targeted state pointing to
the targeting state. The following example demonstrates a direct requisite:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed: []
/etc/vimrc:
file.managed:
\- source: salt://edit/vimrc
\- require:
\- pkg: vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the example above, the file \fB/etc/vimrc\fP depends on the vim package.
.sp
Requisite_in statements are the opposite. Instead of saying "I depend on
something", requisite_ins say "Someone depends on me":
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed:
\- require_in:
\- file: /etc/vimrc
/etc/vimrc:
file.managed:
\- source: salt://edit/vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
So here, with a requisite_in, the same thing is accomplished as in the first
example, but the other way around. The vim package is saying "/etc/vimrc depends
on me". This will result in a \fBrequire\fP being inserted into the
\fB/etc/vimrc\fP state which targets the \fBvim\fP state.
.sp
In the end, a single dependency map is created and everything is executed in a
finite and predictable order.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Requisite matching
.sp
Requisites match on both the ID Declaration and the \fBname\fP parameter.
This means that, in the example above, the \fBrequire_in\fP requisite would
also have been matched if the \fB/etc/vimrc\fP state was written as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vimrc:
file.managed:
\- name: /etc/vimrc
\- source: salt://edit/vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Direct Requisite and Requisite_in types
.sp
There are six direct requisite statements that can be used in Salt:
\fBrequire\fP, \fBwatch\fP, \fBprereq\fP, \fBuse\fP, \fBonchanges\fP, and \fBonfail\fP\&.
Each direct requisite also has a corresponding requisite_in: \fBrequire_in\fP,
\fBwatch_in\fP, \fBprereq_in\fP, \fBuse_in\fP, \fBonchanges_in\fP, and \fBonfail_in\fP\&.
All of the requisites define specific relationships and always work with the
dependency logic defined above.
.SS require
.sp
The use of \fBrequire\fP demands that the dependent state executes before the
depending state. The state containing the \fBrequire\fP requisite is defined as the
depending state. The state specified in the \fBrequire\fP statement is defined as the
dependent state. If the dependent state\(aqs execution succeeds, the depending state
will then execute. If the dependent state\(aqs execution fails, the depending state
will not execute. In the first example above, the file \fB/etc/vimrc\fP will only
execute after the vim package is installed successfully.
.SS Require an entire sls file
.sp
As of Salt 0.16.0, it is possible to require an entire sls file. Do this first by
including the sls file and then setting a state to \fBrequire\fP the included sls file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- foo
bar:
pkg.installed:
\- require:
\- sls: foo
.ft P
.fi
.UNINDENT
.UNINDENT
.SS watch
.sp
\fBwatch\fP statements are used to add additional behavior when there are changes
in other states.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If a state should only execute when another state has changes, and
otherwise do nothing, the new \fBonchanges\fP requisite should be used
instead of \fBwatch\fP\&. \fBwatch\fP is designed to add \fIadditional\fP behavior
when there are changes, but otherwise execute normally.
.UNINDENT
.UNINDENT
.sp
The state containing the \fBwatch\fP requisite is defined as the watching
state. The state specified in the \fBwatch\fP statement is defined as the watched
state. When the watched state executes, it will return a dictionary containing
a key named "changes". Here are two examples of state return dictionaries,
shown in json for clarity:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
"local": {
"file_|\-/tmp/foo_|\-/tmp/foo_|\-directory": {
"comment": "Directory /tmp/foo updated",
"__run_num__": 0,
"changes": {
"user": "bar"
},
"name": "/tmp/foo",
"result": true
}
}
"local": {
"pkgrepo_|\-salt\-minion_|\-salt\-minion_|\-managed": {
"comment": "Package repo \(aqsalt\-minion\(aq already configured",
"__run_num__": 0,
"changes": {},
"name": "salt\-minion",
"result": true
}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the "result" of the watched state is \fBTrue\fP, the watching state \fIwill
execute normally\fP\&. This part of \fBwatch\fP mirrors the functionality of the
\fBrequire\fP requisite. If the "result" of the watched state is \fBFalse\fP, the
watching state will never run, nor will the watching state\(aqs \fBmod_watch\fP
function execute.
.sp
However, if the "result" of the watched state is \fBTrue\fP, and the "changes"
key contains a populated dictionary (changes occurred in the watched state),
then the \fBwatch\fP requisite can add additional behavior. This additional
behavior is defined by the \fBmod_watch\fP function within the watching state
module. If the \fBmod_watch\fP function exists in the watching state module, it
will be called \fIin addition to\fP the normal watching state. The return data
from the \fBmod_watch\fP function is what will be returned to the master in this
case; the return data from the main watching function is discarded.
.sp
If the "changes" key contains an empty dictionary, the \fBwatch\fP requisite acts
exactly like the \fBrequire\fP requisite (the watching state will execute if
"result" is \fBTrue\fP, and fail if "result" is \fBFalse\fP in the watched state).
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Not all state modules contain \fBmod_watch\fP\&. If \fBmod_watch\fP is absent
from the watching state module, the \fBwatch\fP requisite behaves exactly
like a \fBrequire\fP requisite.
.UNINDENT
.UNINDENT
.sp
A good example of using \fBwatch\fP is with a \fBservice.running\fP state. When a service watches a state, then
the service is reloaded/restarted when the watched state changes, in addition
to Salt ensuring that the service is running.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ntpd:
service.running:
\- watch:
\- file: /etc/ntp.conf
file.managed:
\- name: /etc/ntp.conf
\- source: salt://ntp/files/ntp.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.SS prereq
.sp
New in version 0.16.0.
.sp
\fBprereq\fP allows for actions to be taken based on the expected results of
a state that has not yet been executed. The state containing the \fBprereq\fP
requisite is defined as the pre\-requiring state. The state specified in the
\fBprereq\fP statement is defined as the pre\-required state.
.sp
When a \fBprereq\fP requisite is evaluated, the pre\-required state reports if it
expects to have any changes. It does this by running the pre\-required single
state as a test\-run by enabling \fBtest=True\fP\&. This test\-run will return a
dictionary containing a key named "changes". (See the \fBwatch\fP section above
for examples of "changes" dictionaries.)
.sp
If the "changes" key contains a populated dictionary, it means that the
pre\-required state expects changes to occur when the state is actually
executed, as opposed to the test\-run. The pre\-requiring state will now
actually run. If the pre\-requiring state executes successfully, the
pre\-required state will then execute. If the pre\-requiring state fails, the
pre\-required state will not execute.
.sp
If the "changes" key contains an empty dictionary, this means that changes are
not expected by the pre\-required state. Neither the pre\-required state nor the
pre\-requiring state will run.
.sp
The best way to define how \fBprereq\fP operates is displayed in the following
practical example: When a service should be shut down because underlying code
is going to change, the service should be off\-line while the update occurs. In
this example, \fBgraceful\-down\fP is the pre\-requiring state and \fBsite\-code\fP
is the pre\-required state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
graceful\-down:
cmd.run:
\- name: service apache graceful
\- prereq:
\- file: site\-code
site\-code:
file.recurse:
\- name: /opt/site_code
\- source: salt://site/code
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this case the apache server will only be shutdown if the site\-code state
expects to deploy fresh code via the file.recurse call. The site\-code
deployment will only be executed if the graceful\-down run completes
successfully.
.SS onfail
.sp
New in version 2014.7.0.
.sp
The \fBonfail\fP requisite allows for reactions to happen strictly as a response
to the failure of another state. This can be used in a number of ways, such as
executing a second attempt to set up a service or begin to execute a separate
thread of states because of a failure.
.sp
The \fBonfail\fP requisite is applied in the same way as \fBrequire\fP as \fBwatch\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
primary_mount:
mount.mounted:
\- name: /mnt/share
\- device: 10.0.0.45:/share
\- fstype: nfs
backup_mount:
mount.mounted:
\- name: /mnt/share
\- device: 192.168.40.34:/share
\- fstype: nfs
\- onfail:
\- mount: primary_mount
.ft P
.fi
.UNINDENT
.UNINDENT
.SS onchanges
.sp
New in version 2014.7.0.
.sp
The \fBonchanges\fP requisite makes a state only apply if the required states
generate changes, and if the watched state\(aqs "result" is \fBTrue\fP\&. This can be
a useful way to execute a post hook after changing aspects of a system.
.SS use
.sp
The \fBuse\fP requisite is used to inherit the arguments passed in another
id declaration. This is useful when many files need to have the same defaults.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/foo.conf:
file.managed:
\- source: salt://foo.conf
\- template: jinja
\- mkdirs: True
\- user: apache
\- group: apache
\- mode: 755
/etc/bar.conf
file.managed:
\- source: salt://bar.conf
\- use:
\- file: /etc/foo.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBuse\fP statement was developed primarily for the networking states but
can be used on any states in Salt. This makes sense for the networking state
because it can define a long list of options that need to be applied to
multiple network interfaces.
.sp
The \fBuse\fP statement does not inherit the requisites arguments of the
targeted state. This means also a chain of \fBuse\fP requisites would not
inherit inherited options.
.SS The _in versions of requisites
.sp
All of the requisites also have corresponding requisite_in versions, which do
the reverse of their normal counterparts. The examples below all use
\fBrequire_in\fP as the example, but note that all of the \fB_in\fP requisites work
the same way: They result in a normal requisite in the targeted state, which
targets the state which has defines the requisite_in. Thus, a \fBrequire_in\fP
causes the target state to \fBrequire\fP the targeting state. Similarly, a
\fBwatch_in\fP causes the target state to \fBwatch\fP the targeting state. This
pattern continues for the rest of the requisites.
.sp
If a state declaration needs to be required by another state declaration then
\fBrequire_in\fP can accommodate it. Therefore, these two sls files would be the
same in the end:
.sp
Using \fBrequire\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed: []
service.running:
\- require:
\- pkg: httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using \fBrequire_in\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed:
\- require_in:
\- service: httpd
service.running: []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBrequire_in\fP statement is particularly useful when assigning a require
in a separate sls file. For instance it may be common for httpd to require
components used to set up PHP or mod_python, but the HTTP state does not need
to be aware of the additional components that require it when it is set up:
.sp
http.sls
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed: []
service.running:
\- require:
\- pkg: httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
php.sls
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- http
php:
pkg.installed:
\- require_in:
\- service: httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
mod_python.sls
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- http
mod_python:
pkg.installed:
\- require_in:
\- service: httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now the httpd server will only start if php or mod_python are first verified to
be installed. Thus allowing for a requisite to be defined "after the fact".
.SS Altering States
.sp
The state altering system is used to make sure that states are evaluated exactly
as the user expects. It can be used to double check that a state preformed
exactly how it was expected to, or to make 100% sure that a state only runs
under certain conditions. The use of unless or onlyif options help make states
even more stateful. The check_cmds option helps ensure that the result of a
state is evaluated correctly.
.SS Unless
.sp
New in version 2014.7.0.
.sp
The \fBunless\fP requisite specifies that a state should only run when any of
the specified commands return \fBFalse\fP\&. The \fBunless\fP requisite operates
as NOR and is useful in giving more granular control over when a state should
execute.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed:
\- unless:
\- rpm \-q vim\-enhanced
\- ls /usr/bin/vim
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the example above, the state will only run if either the vim\-enhanced
package is not installed (returns \fBFalse\fP) or if /usr/bin/vim does not
exist (returns \fBFalse\fP). The state will run if both commands return
\fBFalse\fP\&.
.sp
However, the state will not run if both commands return \fBTrue\fP\&.
.SS Onlyif
.sp
New in version 2014.7.0.
.sp
\fBonlyif\fP is the opposite of \fBunless\fP\&. If all of the commands in \fBonlyif\fP
return \fBTrue\fP, then the state is run. If any of the specified commands
return \fBFalse\fP, the state will not run.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stop\-volume:
module.run:
\- name: glusterfs.stop_volume
\- m_name: work
\- onlyif:
\- gluster volume status work
\- order: 1
remove\-volume:
module.run:
\- name: glusterfs.delete
\- m_name: work
\- onlyif:
\- gluster volume info work
\- watch:
\- cmd: stop\-volume
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above example ensures that the stop_volume and delete modules only run
if the gluster commands return a 0 ret value.
.SS check_cmd
.sp
New in version 2014.7.0.
.sp
Check Command is used for determining that a state did or did not run as
expected.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
comment\-repo:
file.replace:
\- path: /etc/yum.repos.d/fedora.repo
\- pattern: ^enabled=0
\- repl: enabled=1
\- check_cmd:
\- grep \(aqenabled=0\(aq /etc/yum.repos.d/fedora.repo && return 1 || return 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will attempt to do a replace on all enabled=0 in the .repo file, and
replace them with enabled=1. The check_cmd is just a bash command. It will do
a grep for enabled=0 in the file, and if it finds any, it will return a 0, which
will prompt the && portion of the command to return a 1, causing check_cmd to
set the state as failed. If it returns a 1, meaning it didn\(aqt find any
\(aqenabled=0\(aq it will hit the || portion of the command, returning a 0, and
declaring the function succeeded.
.SS Overriding Checks
.sp
There are two commands used for the above checks.
.sp
\fImod_run_check\fP is used to check for onlyif and unless. If the goal is to
override the global check for these to variables, include a mod_run_check in the
salt/states/ file.
.sp
\fImod_run_check_cmd\fP is used to check for the check_cmd options. To override
this one, include a mod_run_check_cmd in the states file for the state.
.SS Startup States
.sp
Sometimes it may be desired that the salt minion execute a state run when it is
started. This alleviates the need for the master to initiate a state run on a
new minion and can make provisioning much easier.
.sp
As of Salt 0.10.3 the minion config reads options that allow for states to be
executed at startup. The options are \fIstartup_states\fP, \fIsls_list\fP and
\fItop_file\fP\&.
.sp
The \fIstartup_states\fP option can be passed one of a number of arguments to
define how to execute states. The available options are:
.INDENT 0.0
.TP
.B highstate
Execute \fBstate.highstate\fP
.TP
.B sls
Read in the \fBsls_list\fP option and execute the named sls files
.TP
.B top
Read in the \fBtop_file\fP option and execute states based on that top file
on the Salt Master
.UNINDENT
.SS Examples:
.sp
Execute \fBstate.highstate\fP when starting the minion:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
startup_states: highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Execute the sls files \fIedit.vim\fP and \fIhyper\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
startup_states: sls
sls_list:
\- edit.vim
\- hyper
.ft P
.fi
.UNINDENT
.UNINDENT
.SS State Testing
.sp
Executing a Salt state run can potentially change many aspects of a system and
it may be desirable to first see what a state run is going to change before
applying the run.
.sp
Salt has a test interface to report on exactly what will be changed, this
interface can be invoked on any of the major state run functions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate test=True
salt \(aq*\(aq state.sls test=True
salt \(aq*\(aq state.single test=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The test run is mandated by adding the \fBtest=True\fP option to the states. The
return information will show states that will be applied in yellow and the
result is reported as \fBNone\fP\&.
.SS Default Test
.sp
If the value \fBtest\fP is set to \fBTrue\fP in the minion configuration file then
states will default to being executed in test mode. If this value is set then
states can still be run by calling test=False:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate test=False
salt \(aq*\(aq state.sls test=False
salt \(aq*\(aq state.single test=False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The Top File
.sp
The top file is used to map what SLS modules get loaded onto what minions via
the state system. The top file creates a few general abstractions. First it
maps what nodes should pull from which environments, next it defines which
matches systems should draw from.
.SS Environments
.sp
Environments allow conceptually organizing state tree directories. Environments
can be made to be self\-contained or state trees can be made to bleed through
environments.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Environments in Salt are very flexible, this section defines how the top
file can be used to define what states from what environments are to be
used for specific minions.
.sp
If the intent is to bind minions to specific environments, then the
\fIenvironment\fP option can be set in the minion configuration file.
.UNINDENT
.UNINDENT
.sp
The environments in the top file corresponds with the environments defined in
the \fBfile_roots\fP variable. In a simple, single environment setup
you only have the \fBbase\fP environment, and therefore only one state tree. Here
is a simple example of \fBfile_roots\fP in the master configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This means that the top file will only have one environment to pull from,
here is a simple, single environment top file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- core
\- edit
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This also means that \fB/srv/salt\fP has a state tree. But if you want to use
multiple environments, or partition the file server to serve more than
just the state tree, then the \fBfile_roots\fP option can be expanded:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
base:
\- /srv/salt/base
dev:
\- /srv/salt/dev
qa:
\- /srv/salt/qa
prod:
\- /srv/salt/prod
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then our top file could reference the environments:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dev:
\(aqwebserver*dev*\(aq:
\- webserver
\(aqdb*dev*\(aq:
\- db
qa:
\(aqwebserver*qa*\(aq:
\- webserver
\(aqdb*qa*\(aq:
\- db
prod:
\(aqwebserver*prod*\(aq:
\- webserver
\(aqdb*prod*\(aq:
\- db
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this setup we have state trees in three of the four environments, and no
state tree in the \fBbase\fP environment. Notice that the targets for the minions
specify environment data. In Salt the master determines who is in what
environment, and many environments can be crossed together. For instance, a
separate global state tree could be added to the \fBbase\fP environment if it
suits your deployment:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- global
dev:
\(aqwebserver*dev*\(aq:
\- webserver
\(aqdb*dev*\(aq:
\- db
qa:
\(aqwebserver*qa*\(aq:
\- webserver
\(aqdb*qa*\(aq:
\- db
prod:
\(aqwebserver*prod*\(aq:
\- webserver
\(aqdb*prod*\(aq:
\- db
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this setup all systems will pull the global SLS from the base environment,
as well as pull from their respective environments. If you assign only one SLS
to a system, as in this example, a shorthand is also available:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq: global
dev:
\(aqwebserver*dev*\(aq: webserver
\(aqdb*dev*\(aq: db
qa:
\(aqwebserver*qa*\(aq: webserver
\(aqdb*qa*\(aq: db
prod:
\(aqwebserver*prod*\(aq: webserver
\(aqdb*prod*\(aq: db
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The top files from all defined environments will be compiled into a single
top file for all states. Top files are environment agnostic.
.UNINDENT
.UNINDENT
.sp
Remember, that since everything is a file in Salt, the environments are
primarily file server environments, this means that environments that have
nothing to do with states can be defined and used to distribute other files.
.sp
A clean and recommended setup for multiple environments would look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Master file_roots configuration:
file_roots:
base:
\- /srv/salt/base
dev:
\- /srv/salt/dev
qa:
\- /srv/salt/qa
prod:
\- /srv/salt/prod
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then only place state trees in the dev, qa and prod environments, leaving
the base environment open for generic file transfers. Then the top.sls file
would look something like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dev:
\(aqwebserver*dev*\(aq:
\- webserver
\(aqdb*dev*\(aq:
\- db
qa:
\(aqwebserver*qa*\(aq:
\- webserver
\(aqdb*qa*\(aq:
\- db
prod:
\(aqwebserver*prod*\(aq:
\- webserver
\(aqdb*prod*\(aq:
\- db
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Other Ways of Targeting Minions
.sp
In addition to globs, minions can be specified in top files a few other
ways. Some common ones are \fBcompound matches\fP
and \fBnode groups\fP\&.
.sp
Here is a slightly more complex top file example, showing the different types
of matches you can perform:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- ldap\-client
\- networking
\- salt.minion
\(aqsalt\-master*\(aq:
\- salt.master
\(aq^(memcache|web).(qa|prod).loc$\(aq:
\- match: pcre
\- nagios.mon.web
\- apache.server
\(aqos:Ubuntu\(aq:
\- match: grain
\- repos.ubuntu
\(aqos:(RedHat|CentOS)\(aq:
\- match: grain_pcre
\- repos.epel
\(aqfoo,bar,baz\(aq:
\- match: list
\- database
\(aqsomekey:abc\(aq:
\- match: pillar
\- xyz
\(aqnag1* or G@role:monitoring\(aq:
\- match: compound
\- nagios.server
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example \fBtop.sls\fP, all minions get the ldap\-client, networking and
salt.minion states. Any minion with an id matching the \fBsalt\-master*\fP glob
will get the salt.master state. Any minion with ids matching the regular
expression \fB^(memcache|web).(qa|prod).loc$\fP will get the nagios.mon.web and
apache.server states. All Ubuntu minions will receive the repos.ubuntu state,
while all RHEL and CentOS minions will receive the repos.epel state. The
minions \fBfoo\fP, \fBbar\fP, and \fBbaz\fP will receive the database state. Any
minion with a pillar named \fBsomekey\fP, having a value of \fBabc\fP will receive
the xyz state. Finally, minions with ids matching the nag1* glob or with a
grain named \fBrole\fP equal to \fBmonitoring\fP will receive the nagios.server
state.
.SS How Top Files Are Compiled
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
There is currently a known issue with the topfile compilation. The below
may not be completely valid until
\fI\%https://github.com/saltstack/salt/issues/12483#issuecomment\-64181598\fP
is closed.
.UNINDENT
.UNINDENT
.sp
As mentioned earlier, the top files in the different environments are compiled
into a single set of data. The way in which this is done follows a few rules,
which are important to understand when arranging top files in different
environments. The examples below all assume that the \fBfile_roots\fP
are set as in the \fI\%above multi\-environment example\fP\&.
.INDENT 0.0
.IP 1. 3
The \fBbase\fP environment\(aqs top file is processed first. Any environment which
is defined in the \fBbase\fP top.sls as well as another environment\(aqs top file,
will use the instance of the environment configured in \fBbase\fP and ignore
all other instances. In other words, the \fBbase\fP top file is
authoritative when defining environments. Therefore, in the example below,
the \fBdev\fP section in \fB/srv/salt/dev/top.sls\fP would be completely
ignored.
.UNINDENT
.sp
\fB/srv/salt/base/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- common
dev:
\(aqwebserver*dev*\(aq:
\- webserver
\(aqdb*dev*\(aq:
\- db
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/dev/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dev:
\(aq10.10.100.0/24\(aq:
\- match: ipcidr
\- deployments.dev.site1
\(aq10.10.101.0/24\(aq:
\- match: ipcidr
\- deployments.dev.site2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The rules below assume that the environments being discussed were not
defined in the \fBbase\fP top file.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 2. 3
If, for some reason, the \fBbase\fP environment is not configured in the
\fBbase\fP environment\(aqs top file, then the other environments will be checked
in alphabetical order. The first top file found to contain a section for the
\fBbase\fP environment wins, and the other top files\(aq \fBbase\fP sections are
ignored. So, provided there is no \fBbase\fP section in the \fBbase\fP top file,
with the below two top files the \fBdev\fP environment would win out, and the
\fBcommon.centos\fP SLS would not be applied to CentOS hosts.
.UNINDENT
.sp
\fB/srv/salt/dev/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqos:Ubuntu\(aq:
\- common.ubuntu
dev:
\(aqwebserver*dev*\(aq:
\- webserver
\(aqdb*dev*\(aq:
\- db
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/qa/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqos:Ubuntu\(aq:
\- common.ubuntu
\(aqos:CentOS\(aq:
\- common.centos
qa:
\(aqwebserver*qa*\(aq:
\- webserver
\(aqdb*qa*\(aq:
\- db
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 3. 3
For environments other than \fBbase\fP, the top file in a given environment
will be checked for a section matching the environment\(aqs name. If one is
found, then it is used. Otherwise, the remaining (non\-\fBbase\fP) environments
will be checked in alphabetical order. In the below example, the \fBqa\fP
section in \fB/srv/salt/dev/top.sls\fP will be ignored, but if
\fB/srv/salt/qa/top.sls\fP were cleared or removed, then the states configured
for the \fBqa\fP environment in \fB/srv/salt/dev/top.sls\fP will be applied.
.UNINDENT
.sp
\fB/srv/salt/dev/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dev:
\(aqwebserver*dev*\(aq:
\- webserver
\(aqdb*dev*\(aq:
\- db
qa:
\(aq10.10.200.0/24\(aq:
\- match: ipcidr
\- deployments.qa.site1
\(aq10.10.201.0/24\(aq:
\- match: ipcidr
\- deployments.qa.site2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/qa/top.sls:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
qa:
\(aqwebserver*qa*\(aq:
\- webserver
\(aqdb*qa*\(aq:
\- db
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When in doubt, the simplest way to configure your states is with a single
top.sls in the \fBbase\fP environment.
.UNINDENT
.UNINDENT
.SS SLS Template Variable Reference
.sp
The template engines available to sls files and file templates come loaded
with a number of context variables. These variables contain information and
functions to assist in the generation of templates. See each variable below
for its availability \-\- not all variables are available in all templating
contexts.
.SS Salt
.sp
The \fIsalt\fP variable is available to abstract the salt library functions. This
variable is a python dictionary containing all of the functions available to
the running salt minion. It is available in all salt templates.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% for file in salt[\(aqcmd.run\(aq](\(aqls \-1 /opt/to_remove\(aq).splitlines() %}
/opt/to_remove/{{ file }}:
file.absent
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Opts
.sp
The \fIopts\fP variable abstracts the contents of the minion\(aqs configuration file
directly to the template. The \fIopts\fP variable is a dictionary. It is available
in all templates.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ opts[\(aqcachedir\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBconfig.get\fP function also searches for values in the \fIopts\fP dictionary.
.SS Pillar
.sp
The \fIpillar\fP dictionary can be referenced directly, and is available in all
templates:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ pillar[\(aqkey\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using the \fBpillar.get\fP function via the \fIsalt\fP variable is generally
recommended since a default can be safely set in the event that the value
is not available in pillar and dictionaries can be traversed directly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ salt[\(aqpillar.get\(aq](\(aqkey\(aq, \(aqfailover_value\(aq) }}
{{ salt[\(aqpillar.get\(aq](\(aqstuff:more:deeper\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Grains
.sp
The \fIgrains\fP dictionary makes the minion\(aqs grains directly available, and is
available in all templates:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ grains[\(aqos\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBgrains.get\fP function can be used to traverse deeper grains and set
defaults:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ salt[\(aqgrains.get\(aq](\(aqos\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS env
.sp
The \fIenv\fP variable is available in only in sls files when gathering the sls
from an environment.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ env }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS sls
.sp
The \fIsls\fP variable contains the sls reference value, and is only available in
the actual SLS file (not in any files referenced in that SLS). The sls
reference value is the value used to include the sls in top files or via the
include option.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ sls }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS 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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/master: # maps to "name"
file: # maps to State module filename e.g. https://github.com/saltstack/salt/tree/develop/salt/states/file.py
\- managed # maps to the managed function in the file State module
\- user: root # one of many options passed to the manage function
\- group: root
\- mode: 644
\- source: salt://salt/master
.ft P
.fi
.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.
.INDENT 0.0
.INDENT 3.5
.IP "Keyword Arguments"
.sp
Salt passes a number of keyword arguments to states when rendering them,
including the environment, a unique identifier for the state, and more.
Additionally, keep in mind that the requisites for a state are part of the
keyword arguments. Therefore, if you need to iterate through the keyword
arguments in a state, these must be considered and handled appropriately.
One such example is in the \fBpkgrepo.managed\fP state, which needs to be able to handle
arbitrary keyword arguments and pass them to module execution functions.
An example of how these keyword arguments can be handled can be found
\fI\%here\fP\&.
.UNINDENT
.UNINDENT
.SS Using Custom State Modules
.sp
Place your custom state modules inside a \fB_states\fP directory within the
\fBfile_roots\fP specified by the master config file. These custom
state modules can then be distributed in a number of ways. Custom state modules
are distributed when \fBstate.highstate\fP is
run, or by executing the \fBsaltutil.sync_states\fP or \fBsaltutil.sync_all\fP functions.
.sp
Any custom states which have been synced to a minion, that are named the
same as one of Salt\(aqs default set of states, will take the place of the default
state with the same name. Note that a state\(aqs default name is its filename
(i.e. \fBfoo.py\fP becomes state \fBfoo\fP), but that its name can be overridden
by using a \fI__virtual__ function\fP\&.
.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.
.SS Return Data
.sp
A State Module must return a dict containing the following keys/values:
.INDENT 0.0
.IP \(bu 2
\fBname:\fP The same value passed to the state as "name".
.IP \(bu 2
\fBchanges:\fP A dict describing the changes made. Each thing changed should
be a key, with its value being another dict with keys called "old" and "new"
containing the old/new values. For example, the pkg state\(aqs \fBchanges\fP dict
has one key for each package changed, with the "old" and "new" keys in its
sub\-dict containing the old and new versions of the package.
.IP \(bu 2
\fBresult:\fP A boolean value. \fITrue\fP if the action was successful, otherwise
\fIFalse\fP\&.
.IP \(bu 2
\fBcomment:\fP A string containing a summary of the result.
.UNINDENT
.SS Test State
.sp
All states should check for and support \fBtest\fP being passed in the options.
This will return data about what changes would occur if the state were actually
run. An example of such a check could look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Return comment of changes if test.
if __opts__[\(aqtest\(aq]:
ret[\(aqresult\(aq] = None
ret[\(aqcomment\(aq] = \(aqState Foo will execute with param {0}\(aq.format(bar)
return ret
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Make sure to test and return before performing any real actions on the minion.
.SS Watcher Function
.sp
If the state being written should support the watch requisite then a watcher
function needs to be declared. The watcher function is called whenever the
watch requisite is invoked and should be generic to the behavior of the state
itself.
.sp
The watcher function should accept all of the options that the normal state
functions accept (as they will be passed into the watcher function).
.sp
A watcher function typically is used to execute state specific reactive
behavior, for instance, the watcher for the service module restarts the
named service and makes it useful for the watcher to make the service
react to changes in the environment.
.sp
The watcher function also needs to return the same data that a normal state
function returns.
.SS Mod_init Interface
.sp
Some states need to execute something only once to ensure that an environment
has been set up, or certain conditions global to the state behavior can be
predefined. This is the realm of the mod_init interface.
.sp
A state module can have a function called \fBmod_init\fP which executes when the
first state of this type is called. This interface was created primarily to
improve the pkg state. When packages are installed the package metadata needs
to be refreshed, but refreshing the package metadata every time a package is
installed is wasteful. The mod_init function for the pkg state sets a flag down
so that the first, and only the first, package installation attempt will refresh
the package database (the package database can of course be manually called to
refresh via the \fBrefresh\fP option in the pkg state).
.sp
The mod_init function must accept the \fBLow State Data\fP for the given
executing state as an argument. The low state data is a dict and can be seen by
executing the state.show_lowstate function. Then the mod_init function must
return a bool. If the return value is True, then the mod_init function will not
be executed again, meaning that the needed behavior has been set up. Otherwise,
if the mod_init function returns False, then the function will be called the
next time.
.sp
A good example of the mod_init function is found in the pkg state module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def mod_init(low):
\(aq\(aq\(aq
Refresh the package database here so that it only needs to happen once
\(aq\(aq\(aq
if low[\(aqfun\(aq] == \(aqinstalled\(aq or low[\(aqfun\(aq] == \(aqlatest\(aq:
rtag = __gen_rtag()
if not os.path.exists(rtag):
open(rtag, \(aqw+\(aq).write(\(aq\(aq)
return True
else:
return False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The mod_init function in the pkg state accepts the low state data as \fBlow\fP
and then checks to see if the function being called is going to install
packages, if the function is not going to install packages then there is no
need to refresh the package database. Therefore if the package database is
prepared to refresh, then return True and the mod_init will not be called
the next time a pkg state is evaluated, otherwise return False and the mod_init
will be called next time a pkg state is evaluated.
.SS Full State Module Example
.sp
The following is a simplistic example of a full state module and function.
Remember to call out to execution modules to perform all the real work. The
state module should only perform "before" and "after" checks.
.INDENT 0.0
.IP 1. 3
Make a custom state module by putting the code into a file at the following
path: \fB/srv/salt/_states/my_custom_state.py\fP\&.
.IP 2. 3
Distribute the custom state module to the minions:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.sync_states
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Write a new state to use the custom state by making a new state file, for
instance \fB/srv/salt/my_custom_state.sls\fP\&.
.IP 4. 3
Add the following SLS configuration to the file created in Step 3:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
human_friendly_state_id: # An arbitrary state ID declaration.
my_custom_state: # The custom state module name.
\- enforce_custom_thing # The function in the custom state module.
\- name: a_value # Maps to the \(ga\(ganame\(ga\(ga parameter in the custom function.
\- foo: Foo # Specify the required \(ga\(gafoo\(ga\(ga parameter.
\- bar: False # Override the default value for the \(ga\(gabar\(ga\(ga parameter.
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Example state module
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.exceptions
def enforce_custom_thing(name, foo, baz=True):
\(aq\(aq\(aq
Enforce the state of a custom thing
This state module does a custom thing. It calls out to the execution module
\(ga\(gamy_custom_module\(ga\(ga in order to check the current system and perform any
needed changes.
name
The thing to do something to
foo
A required argument
bar : True
An argument with a default value
\(aq\(aq\(aq
ret = {\(aqname\(aq: name, \(aqchanges\(aq: {}, \(aqresult\(aq: False, \(aqcomment\(aq: \(aq\(aq}
# Start with basic error\-checking. Do all the passed parameters make sense
# and agree with each\-other?
if baz == True and foo.startswith(\(aqFoo\(aq):
raise salt.exceptions.SaltInvocationError(
\(aqArgument "foo" cannot start with "Foo" if argument "baz" is True.\(aq)
# Check the current state of the system. Does anything need to change?
current_state = __salt__[\(aqmy_custom_module.current_state\(aq](name)
if current_state == foo:
ret[\(aqresult\(aq] = True
ret[\(aqcomment\(aq] = \(aqSystem already in the correct state\(aq
return ret
# The state of the system does need to be changed. Check if we\(aqre running
# in \(ga\(gatest=true\(ga\(ga mode.
if __opts__[\(aqtest\(aq] == True:
ret[\(aqcomment\(aq] = \(aqThe state of "{0}" will be changed.\(aq.format(name)
ret[\(aqchanges\(aq] = {
\(aqold\(aq: current_state,
\(aqnew\(aq: \(aqDescription, diff, whatever of the new state\(aq,
}
# Return \(ga\(gaNone\(ga\(ga when running with \(ga\(gatest=true\(ga\(ga.
ret[\(aqresult\(aq] = None
return ret
# Finally, make the actual change and return the result.
new_state = __salt__[\(aqmy_custom_module.change_state\(aq](name, foo)
ret[\(aqcomment\(aq] = \(aqThe state of "{0}" was changed!\(aq.format(name)
ret[\(aqchanges\(aq] = {
\(aqold\(aq: current_state,
\(aqnew\(aq: new_state,
}
ret[\(aqresult\(aq] = True
return ret
.ft P
.fi
.UNINDENT
.UNINDENT
.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 one to easily and reliably
configure and manage a few servers or a few thousand servers. It allows
configurations to be kept 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 and how to write the states is needed as well.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
States are compiled and executed only on minions that have been targeted.
To execute functions directly on masters, see \fBrunners\fP\&.
.UNINDENT
.UNINDENT
.SS Salt SLS System
.sp
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.
.SS SLS File Layout
.sp
SLS files are laid out in the Salt file server.
.sp
A simple layout can look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
top.sls
ssh.sls
sshd_config
users/init.sls
users/admin.sls
salt/master.sls
web/init.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBtop.sls\fP file is a key component. The \fBtop.sls\fP files
is used to determine which SLS files should be applied to which minions.
.sp
The rest of the files with the \fB\&.sls\fP extension in the above example are
state files.
.sp
Files without a \fB\&.sls\fP extensions are seen by the Salt master as
files that can be downloaded to a Salt minion.
.sp
States are translated into dot notation. For example, the \fBssh.sls\fP file is
seen as the ssh state and the \fBusers/admin.sls\fP file is seen as the
users.admin state.
.sp
Files named \fBinit.sls\fP are translated to be the state name of the parent
directory, so the \fBweb/init.sls\fP file translates to the \fBweb\fP state.
.sp
In Salt, everything is a file; there is no "magic translation" of files and file
types. This means that a state file can be distributed to minions just like a
plain text or binary file.
.SS SLS Files
.sp
The Salt state files are simple sets of data. Since SLS files are just data
they can be represented in a number of different ways.
.sp
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.
.sp
State files can then be complicated Jinja templates that translate down to YAML, or just
plain and simple YAML files.
.sp
The State files are simply common data structures such as dictionaries and lists, constructed
using a templating language such as YAML.
.sp
Here is an example of a Salt State:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed: []
salt:
pkg.latest:
\- name: salt
service.running:
\- names:
\- salt\-master
\- salt\-minion
\- require:
\- pkg: salt
\- 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
.UNINDENT
.UNINDENT
.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 controls the mapping between minions and the states which should be
applied to them.
.sp
The top file specifies which minions should have which SLS files applied and which
environments they should draw those SLS files from.
.sp
The top file works by specifying environments on the top\-level.
.sp
Each environment contains globs to match minions. Finally, each glob contains a list of
lists of Salt states to apply to matching minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- salt
\- users
\- users.admin
\(aqsaltmaster.*\(aq:
\- match: pcre
\- salt.master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This above example uses the base environment which is built into the default
Salt setup.
.sp
The base environment has two globs. First, the \(aq*\(aq glob contains a list of
SLS files to apply to all minions.
.sp
The second glob contains a regular expression that will match all minions with
an ID matching saltmaster.* and specifies that for those minions, the salt.master
state should be applied.
.SS Reloading Modules
.sp
Some Salt states require that specific packages be installed in order for the
module to load. As an example the \fBpip\fP state
module requires the \fI\%pip\fP package for proper name and version parsing.
.sp
In most of the common cases, Salt is clever enough to transparently reload the
modules. For example, if you install a package, Salt reloads modules because
some other module or state might require just that package which was installed.
.sp
On some edge\-cases salt might need to be told to reload the modules. Consider
the following state file which we\(aqll call \fBpep8.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python\-pip:
cmd.run:
\- name: |
easy_install \-\-script\-dir=/usr/bin \-U pip
\- cwd: /
pep8:
pip.installed:
\- require:
\- cmd: python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above example installs \fI\%pip\fP using \fBeasy_install\fP from \fI\%setuptools\fP and
installs \fI\%pep8\fP using \fBpip\fP, which, as told
earlier, requires \fI\%pip\fP to be installed system\-wide. Let\(aqs execute this state:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call state.sls pep8
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The execution output would be something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-\-\-\-\-
State: \- pip
Name: pep8
Function: installed
Result: False
Comment: State pip.installed found in sls pep8 is unavailable
Changes:
Summary
\-\-\-\-\-\-\-\-\-\-\-\-
Succeeded: 1
Failed: 1
\-\-\-\-\-\-\-\-\-\-\-\-
Total: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If we executed the state again the output would be:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-\-\-\-\-
State: \- pip
Name: pep8
Function: installed
Result: True
Comment: Package was successfully installed
Changes: pep8==1.4.6: Installed
Summary
\-\-\-\-\-\-\-\-\-\-\-\-
Succeeded: 2
Failed: 0
\-\-\-\-\-\-\-\-\-\-\-\-
Total: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since we installed \fI\%pip\fP using \fBcmd\fP, Salt has no way
to know that a system\-wide package was installed.
.sp
On the second execution, since the required \fI\%pip\fP package was installed, the
state executed correctly.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Salt does not reload modules on every state run because doing so would greatly
slow down state execution.
.UNINDENT
.UNINDENT
.sp
So how do we solve this \fIedge\-case\fP? \fBreload_modules\fP!
.sp
\fBreload_modules\fP is a boolean option recognized by salt on \fBall\fP available
states which forces salt to reload its modules once a given state finishes.
.sp
The modified state file would now be:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python\-pip:
cmd.run:
\- name: |
easy_install \-\-script\-dir=/usr/bin \-U pip
\- cwd: /
\- reload_modules: true
pep8:
pip.installed:
\- require:
\- cmd: python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Let\(aqs run it, once:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call state.sls pep8
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The output is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-\-\-\-\-\-
State: \- pip
Name: pep8
Function: installed
Result: True
Comment: Package was successfully installed
Changes: pep8==1.4.6: Installed
Summary
\-\-\-\-\-\-\-\-\-\-\-\-
Succeeded: 2
Failed: 0
\-\-\-\-\-\-\-\-\-\-\-\-
Total: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Full list of builtin state modules
.TS
center;
|l|l|.
_
T{
\fBalias\fP
T} T{
Configuration of email aliases
T}
_
T{
\fBalternatives\fP
T} T{
Configuration of the alternatives system
T}
_
T{
\fBapache\fP
T} T{
Apache state
T}
_
T{
\fBapache_module\fP
T} T{
Manage Apache Modules
T}
_
T{
\fBapt\fP
T} T{
Package management operations specific to APT\- and DEB\-based systems
T}
_
T{
\fBarchive\fP
T} T{
Extract an archive
T}
_
T{
\fBat\fP
T} T{
Configuration disposable regularly scheduled tasks for at.
T}
_
T{
\fBaugeas\fP
T} T{
Configuration management using Augeas
T}
_
T{
\fBaws_sqs\fP
T} T{
Manage SQS Queues
T}
_
T{
\fBblockdev\fP
T} T{
Management of Block Devices
T}
_
T{
\fBboto_asg\fP
T} T{
Manage Autoscale Groups
T}
_
T{
\fBboto_cloudwatch_alarm\fP
T} T{
Manage Cloudwatch alarms
T}
_
T{
\fBboto_elasticache\fP
T} T{
Manage Elasticache
T}
_
T{
\fBboto_elb\fP
T} T{
Manage ELBs
T}
_
T{
\fBboto_iam_role\fP
T} T{
Manage IAM roles.
T}
_
T{
\fBboto_lc\fP
T} T{
Manage Launch Configurations
T}
_
T{
\fBboto_route53\fP
T} T{
Manage Route53 records
T}
_
T{
\fBboto_secgroup\fP
T} T{
Manage Security Groups
T}
_
T{
\fBboto_sqs\fP
T} T{
Manage SQS Queues
T}
_
T{
\fBcloud\fP
T} T{
Using states instead of maps to deploy clouds
T}
_
T{
\fBcmd\fP
T} T{
Execution of arbitrary commands
T}
_
T{
\fBcomposer\fP
T} T{
Installation of Composer Packages
T}
_
T{
\fBcron\fP
T} T{
Management of cron, the Unix command scheduler
T}
_
T{
\fBddns\fP
T} T{
Dynamic DNS updates
T}
_
T{
\fBdebconfmod\fP
T} T{
Management of debconf selections
T}
_
T{
\fBdisk\fP
T} T{
Disk monitoring state
T}
_
T{
\fBdockerio\fP
T} T{
Manage Docker containers
T}
_
T{
\fBenviron\fP
T} T{
Support for getting and setting the environment variables of the current salt process.
T}
_
T{
\fBeselect\fP
T} T{
Management of Gentoo configuration using eselect
T}
_
T{
\fBevent\fP
T} T{
Send events through Salt\(aqs event system during state runs
T}
_
T{
\fBfile\fP
T} T{
Operations on regular files, special files, directories, and symlinks
T}
_
T{
\fBgem\fP
T} T{
Installation of Ruby modules packaged as gems
T}
_
T{
\fBgit\fP
T} T{
Interaction with Git repositories
T}
_
T{
\fBglusterfs\fP
T} T{
Manage glusterfs pool.
T}
_
T{
\fBgnomedesktop\fP
T} T{
Configuration of the GNOME desktop
T}
_
T{
\fBgrains\fP
T} T{
Manage grains on the minion
T}
_
T{
\fBgroup\fP
T} T{
Management of user groups
T}
_
T{
\fBhg\fP
T} T{
Interaction with Mercurial repositories
T}
_
T{
\fBhost\fP
T} T{
Management of addresses and names in hosts file
T}
_
T{
\fBhtpasswd\fP
T} T{
Support for htpasswd module
T}
_
T{
\fBincron\fP
T} T{
Management of incron, the inotify cron
T}
_
T{
\fBinfluxdb_database\fP
T} T{
Management of InfluxDB databases
T}
_
T{
\fBinfluxdb_user\fP
T} T{
Management of InfluxDB users
T}
_
T{
\fBini_manage\fP
T} T{
Manage ini files
T}
_
T{
\fBipset\fP
T} T{
Management of ipsets
T}
_
T{
\fBiptables\fP
T} T{
Management of iptables
T}
_
T{
\fBkeyboard\fP
T} T{
Management of keyboard layouts
T}
_
T{
\fBkeystone\fP
T} T{
Management of Keystone users
T}
_
T{
\fBkmod\fP
T} T{
Loading and unloading of kernel modules
T}
_
T{
\fBlayman\fP
T} T{
Management of Gentoo Overlays using layman
T}
_
T{
\fBlibvirt\fP
T} T{
Manage libvirt certificates
T}
_
T{
\fBlocale\fP
T} T{
Management of languages/locales
T}
_
T{
\fBlvm\fP
T} T{
Management of Linux logical volumes
T}
_
T{
\fBlvs_server\fP
T} T{
Management of LVS (Linux Virtual Server) Real Server
T}
_
T{
\fBlvs_service\fP
T} T{
Management of LVS (Linux Virtual Server) Service
T}
_
T{
\fBlxc\fP
T} T{
lxc / Spin up and control LXC containers
T}
_
T{
\fBmakeconf\fP
T} T{
Management of Gentoo make.conf
T}
_
T{
\fBmdadm\fP
T} T{
Managing software RAID with mdadm
T}
_
T{
\fBmemcached\fP
T} T{
States for Management of Memcached Keys
T}
_
T{
\fBmodjk\fP
T} T{
State to control Apache modjk
T}
_
T{
\fBmodjk_worker\fP
T} T{
Manage modjk workers
T}
_
T{
\fBmodule\fP
T} T{
Execution of Salt modules from within states
T}
_
T{
\fBmongodb_database\fP
T} T{
Management of Mongodb databases
T}
_
T{
\fBmongodb_user\fP
T} T{
Management of Mongodb users
T}
_
T{
\fBmount\fP
T} T{
Mounting of filesystems
T}
_
T{
\fBmysql_database\fP
T} T{
Management of MySQL databases (schemas)
T}
_
T{
\fBmysql_grants\fP
T} T{
Management of MySQL grants (user permissions)
T}
_
T{
\fBmysql_query\fP
T} T{
Execution of MySQL queries
T}
_
T{
\fBmysql_user\fP
T} T{
Management of MySQL users
T}
_
T{
\fBnetwork\fP
T} T{
Configuration of network interfaces
T}
_
T{
\fBnftables\fP
T} T{
Management of nftables
T}
_
T{
\fBnpm\fP
T} T{
Installation of NPM Packages
T}
_
T{
\fBntp\fP
T} T{
Management of NTP servers
T}
_
T{
\fBopenstack_config\fP
T} T{
Manage OpenStack configuration file settings.
T}
_
T{
\fBpagerduty\fP
T} T{
Create an Event in PagerDuty
T}
_
T{
\fBpecl\fP
T} T{
Installation of PHP Extensions Using pecl
T}
_
T{
\fBpip_state\fP
T} T{
Installation of Python Packages Using pip
T}
_
T{
\fBpkg\fP
T} T{
Installation of packages using OS package managers such as yum or apt\-get
T}
_
T{
\fBpkgng\fP
T} T{
Manage package remote repo using FreeBSD pkgng
T}
_
T{
\fBpkgrepo\fP
T} T{
Management of APT/YUM package repos
T}
_
T{
\fBportage_config\fP
T} T{
Management of Portage package configuration on Gentoo
T}
_
T{
\fBports\fP
T} T{
Manage software from FreeBSD ports
T}
_
T{
\fBpostgres_database\fP
T} T{
Management of PostgreSQL databases
T}
_
T{
\fBpostgres_extension\fP
T} T{
Management of PostgreSQL extensions (e.g.: postgis)
T}
_
T{
\fBpostgres_group\fP
T} T{
Management of PostgreSQL groups (roles)
T}
_
T{
\fBpostgres_user\fP
T} T{
Management of PostgreSQL users (roles)
T}
_
T{
\fBpowerpath\fP
T} T{
Powerpath configuration support
T}
_
T{
\fBprocess\fP
T} T{
Process Management
T}
_
T{
\fBpyenv\fP
T} T{
Managing python installations with pyenv
T}
_
T{
\fBquota\fP
T} T{
Management of POSIX Quotas
T}
_
T{
\fBrabbitmq_cluster\fP
T} T{
Manage RabbitMQ Clusters
T}
_
T{
\fBrabbitmq_plugin\fP
T} T{
Manage RabbitMQ Plugins
T}
_
T{
\fBrabbitmq_policy\fP
T} T{
Manage RabbitMQ Policies
T}
_
T{
\fBrabbitmq_user\fP
T} T{
Manage RabbitMQ Users
T}
_
T{
\fBrabbitmq_vhost\fP
T} T{
Manage RabbitMQ Virtual Hosts
T}
_
T{
\fBrbenv\fP
T} T{
Managing Ruby installations with rbenv
T}
_
T{
\fBrdp\fP
T} T{
Manage RDP Service on Windows servers
T}
_
T{
\fBredismod\fP
T} T{
Management of Redis server
T}
_
T{
\fBreg\fP
T} T{
Manage the registry on Windows
T}
_
T{
\fBrvm\fP
T} T{
Managing Ruby installations and gemsets with Ruby Version Manager (RVM)
T}
_
T{
\fBsaltmod\fP
T} T{
Control the Salt command interface
T}
_
T{
\fBschedule\fP
T} T{
Management of the Salt scheduler
T}
_
T{
\fBselinux\fP
T} T{
Management of SELinux rules
T}
_
T{
\fBserverdensity_device\fP
T} T{
Monitor Server with Server Density
T}
_
T{
\fBservice\fP
T} T{
Starting or restarting of services and daemons
T}
_
T{
\fBsmtp\fP
T} T{
Sending Messages via SMTP
T}
_
T{
\fBssh_auth\fP
T} T{
Control of entries in SSH authorized_key files
T}
_
T{
\fBssh_known_hosts\fP
T} T{
Control of SSH known_hosts entries
T}
_
T{
\fBstateconf\fP
T} T{
Stateconf System
T}
_
T{
\fBstatus\fP
T} T{
Minion status monitoring
T}
_
T{
\fBsupervisord\fP
T} T{
Interaction with the Supervisor daemon
T}
_
T{
\fBsvn\fP
T} T{
Manage SVN repositories
T}
_
T{
\fBsysctl\fP
T} T{
Configuration of the Linux kernel using sysctl
T}
_
T{
\fBtest\fP
T} T{
Test States
T}
_
T{
\fBtimezone\fP
T} T{
Management of timezones
T}
_
T{
\fBtomcat\fP
T} T{
This state uses the manager webapp to manage Apache tomcat webapps
T}
_
T{
\fBuser\fP
T} T{
Management of user accounts
T}
_
T{
\fBvirtualenv_mod\fP
T} T{
Setup of Python virtualenv sandboxes
T}
_
T{
\fBwin_dns_client\fP
T} T{
Module for configuring DNS Client on Windows systems
T}
_
T{
\fBwin_firewall\fP
T} T{
State for configuring Windows Firewall
T}
_
T{
\fBwin_network\fP
T} T{
Configuration of network interfaces on Windows hosts
T}
_
T{
\fBwin_path\fP
T} T{
Manage the Windows System PATH
T}
_
T{
\fBwin_servermanager\fP
T} T{
Manage Windows features via the ServerManager powershell module
T}
_
T{
\fBwin_system\fP
T} T{
Management of Windows system information
T}
_
T{
\fBwin_update\fP
T} T{
Management of the windows update agent
T}
_
T{
\fBwinrepo\fP
T} T{
Manage Windows Package Repository
T}
_
T{
\fBxmpp\fP
T} T{
Sending Messages over XMPP
T}
_
T{
\fBzcbuildout\fP
T} T{
Management of zc.buildout
T}
_
T{
\fBzk_concurrency\fP
T} T{
Control concurrency of steps within state execution using zookeeper
T}
_
.TE
.SS salt.states.alias
.SS Configuration of email aliases
.sp
The mail aliases file can be managed to contain definitions for specific email
aliases:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
username:
alias.present:
\- target: user@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.alias.absent(name)
Ensure that the named alias is absent
.INDENT 7.0
.TP
.B name
The alias to remove
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.alias.present(name, target)
Ensures that the named alias is present with the given target or list of
targets. If the alias exists but the target differs from the previous
entry, the target(s) will be overwritten. If the alias does not exist, the
alias will be created.
.INDENT 7.0
.TP
.B name
The local user/address to assign an alias to
.TP
.B target
The forwarding address
.UNINDENT
.UNINDENT
.SS salt.states.alternatives
.SS Configuration of the alternatives system
.sp
Control the alternatives system
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set my_hadoop_conf = \(aq/opt/hadoop/conf\(aq %}
{{ my_hadoop_conf }}:
file.directory
hadoop\-0.20\-conf:
alternatives.install:
\- name: hadoop\-0.20\-conf
\- link: /etc/hadoop\-0.20/conf
\- path: {{ my_hadoop_conf }}
\- priority: 30
\- require:
\- file: {{ my_hadoop_conf }}
hadoop\-0.20\-conf:
alternatives.remove:
\- name: hadoop\-0.20\-conf
\- path: {{ my_hadoop_conf }}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.alternatives.auto(name)
New in version 0.17.0.
.sp
Instruct alternatives to use the highest priority
path for <name>
.INDENT 7.0
.TP
.B name
is the master name for this link group
(e.g. pager)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.alternatives.install(name, link, path, priority)
Install new alternative for defined <name>
.INDENT 7.0
.TP
.B name
is the master name for this link group
(e.g. pager)
.TP
.B link
is the symlink pointing to /etc/alternatives/<name>.
(e.g. /usr/bin/pager)
.TP
.B path
is the location of the new alternative target.
NB: This file / directory must already exist.
(e.g. /usr/bin/less)
.TP
.B priority
is an integer; options with higher numbers have higher priority in
automatic mode.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.alternatives.remove(name, path)
Removes installed alternative for defined <name> and <path>
or fallback to default alternative, if some defined before.
.INDENT 7.0
.TP
.B name
is the master name for this link group
(e.g. pager)
.TP
.B path
is the location of one of the alternative target files.
(e.g. /usr/bin/less)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.alternatives.set_(name, path)
New in version 0.17.0.
.sp
Sets alternative for <name> to <path>, if <path> is defined
as an alternative for <name>.
.INDENT 7.0
.TP
.B name
is the master name for this link group
(e.g. pager)
.TP
.B path
is the location of one of the alternative target files.
(e.g. /usr/bin/less)
.UNINDENT
.UNINDENT
.SS salt.states.apache
.sp
Apache state
.sp
New in version 2014.7.0.
.sp
Allows for inputting a yaml dictionary into a file for apache configuration
files.
.sp
The variable \fBthis\fP is special and signifies what should be included with
the above word between angle brackets (<>).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/httpd/conf.d/website.com.conf:
apache.configfile:
\- config:
\- VirtualHost:
this: \(aq*:80\(aq
ServerName:
\- website.com
ServerAlias:
\- www.website.com
\- dev.website.com
ErrorLog: logs/website.com\-error_log
CustomLog: logs/website.com\-access_log combined
DocumentRoot: /var/www/vhosts/website.com
Directory:
this: /var/www/vhosts/website.com
Order: Deny,Allow
Deny from: all
Allow from:
\- 127.0.0.1
\- 192.168.100.0/24
Options:
\- +Indexes
\- FollowSymlinks
AllowOverride: All
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.apache.configfile(name, config)
.UNINDENT
.SS salt.states.apache_module
.SS Manage Apache Modules
.sp
New in version 2014.7.0.
.sp
Enable and disable apache modules.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Enable cgi module:
apache_module.enable:
\- name: cgi
Disable cgi module:
apache_module.disable:
\- name: cgi
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.apache_module.disable(name)
Ensure an Apache module is disabled.
.INDENT 7.0
.TP
.B name
Name of the Apache module
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.apache_module.enable(name)
Ensure an Apache module is enabled.
.INDENT 7.0
.TP
.B name
Name of the Apache module
.UNINDENT
.UNINDENT
.SS salt.states.apt
.SS Package management operations specific to APT\- and DEB\-based systems
.INDENT 0.0
.TP
.B salt.states.apt.held(name)
Set package in \(aqhold\(aq state, meaning it will not be upgraded.
.INDENT 7.0
.TP
.B name
The name of the package, e.g., \(aqtmux\(aq
.UNINDENT
.UNINDENT
.SS salt.states.archive
.sp
Extract an archive
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B salt.states.archive.extracted(name, source, archive_format, tar_options=None, source_hash=None, if_missing=None, keep=False)
New in version 2014.1.0.
.sp
State that make sure an archive is extracted in a directory.
The downloaded archive is erased if successfully extracted.
The archive is downloaded only if necessary.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If \fBif_missing\fP is not defined, this state will check for \fBname\fP
instead. If \fBname\fP exists, it will assume the archive was previously
extracted successfully and will not extract it again.
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
graylog2\-server:
archive.extracted:
\- name: /opt/
\- source: https://github.com/downloads/Graylog2/graylog2\-server/graylog2\-server\-0.9.6p1.tar.lzma
\- source_hash: md5=499ae16dcae71eeb7c3a30c75ea7a1a6
\- tar_options: J
\- archive_format: tar
\- if_missing: /opt/graylog2\-server\-0.9.6p1/
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
graylog2\-server:
archive.extracted:
\- name: /opt/
\- source: https://github.com/downloads/Graylog2/graylog2\-server/graylog2\-server\-0.9.6p1.tar.gz
\- source_hash: md5=499ae16dcae71eeb7c3a30c75ea7a1a6
\- archive_format: tar
\- if_missing: /opt/graylog2\-server\-0.9.6p1/
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Directory name where to extract the archive
.TP
.B source
Archive source, same syntax as file.managed source argument.
.TP
.B source_hash
Hash of source file, or file with list of hash\-to\-file mappings.
It uses the same syntax as the file.managed source_hash argument.
.TP
.B archive_format
tar, zip or rar
.TP
.B if_missing
Some archives, such as tar, extract themselves in a subfolder.
This directive can be used to validate if the archive had been
previously extracted.
.TP
.B tar_options
Required if used with \fBarchive_format: tar\fP, otherwise optional.
It needs to be the tar argument specific to the archive being extracted,
such as \(aqJ\(aq for LZMA or \(aqv\(aq to verbosely list files processed.
Using this option means that the tar executable on the target will
be used, which is less platform independent.
Main operators like \-x, \-\-extract, \-\-get, \-c, etc. and \-f/\-\-file are
\fBshoult not be used\fP here.
If this option is not set, then the Python tarfile module is used.
The tarfile module supports gzip and bz2 in Python 2.
.TP
.B keep
Keep the archive in the minion\(aqs cache
.UNINDENT
.UNINDENT
.SS salt.states.at
.SS Configuration disposable regularly scheduled tasks for at.
.sp
The at state can be add disposable regularly scheduled tasks for your system.
.INDENT 0.0
.TP
.B salt.states.at.absent(name, jobid=None, **kwargs)
Remove a job from queue
The \(aqkwargs\(aq can include hour. minute. day. month. year
.INDENT 7.0
.TP
.B limit
Target range
.TP
.B tag
Job\(aqs tag
.TP
.B runas
Runs user\-specified jobs
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
example1:
at.absent:
\- limit: all
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
example2:
at.absent:
\- limit: all
\- year: 13
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
example3:
at.absent:
\- limit: all
\- tag: rose
\- runas: jim
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
example4:
at.absent:
\- limit: all
\- tag: rose
\- day: 13
\- hour: 16
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.at.present(name, timespec, tag=None, runas=None, user=None, job=None)
Add a job to queue.
.INDENT 7.0
.TP
.B job
Command to run.
.TP
.B timespec
The \(aqtimespec\(aq follows the format documented in the at(1) manpage.
.TP
.B tag
Make a tag for the job.
.TP
.B runas
Users run the job.
.sp
Deprecated since version 2014.1.4.
.TP
.B user
The user to run the at job
.sp
New in version 2014.1.4.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
rose:
at.present:
\- job: \(aqecho "I love saltstack" > love\(aq
\- timespec: \(aq9:09 11/09/13\(aq
\- tag: love
\- user: jam
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.augeas
.SS Configuration management using Augeas
.sp
New in version 0.17.0.
.sp
This state requires the \fBaugeas\fP Python module.
.sp
\fI\%Augeas\fP can be used to manage configuration files.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Minimal installations of Debian and Ubuntu have been seen to have packaging
bugs with python\-augeas, causing the augeas module to fail to import. If
the minion has the augeas module installed, and the state fails with a
comment saying that the state is unavailable, first restart the salt\-minion
service. If the problem persists past that, the following command can be
run from the master to determine what is causing the import to fail:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt minion\-id cmd.run \(aqpython \-c "from augeas import Augeas"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For affected Debian/Ubuntu hosts, installing \fBlibpython2.7\fP has been
known to resolve the issue.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.augeas.change(name, context=None, changes=None, lens=None, **kwargs)
New in version 2014.7.0.
.sp
This state replaces \fI\%setvalue()\fP\&.
.sp
Issue changes to Augeas, optionally for a specific context, with a
specific lens.
.INDENT 7.0
.TP
.B name
State name
.TP
.B context
The context to use. Set this to a file path, prefixed by \fB/files\fP, to
avoid redundancy, e.g.:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
redis\-conf:
augeas.change:
\- context: /files/etc/redis/redis.conf
\- changes:
\- set bind 0.0.0.0
\- set maxmemory 1G
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B changes
List of changes that are issued to Augeas. Available commands are
\fBset\fP, \fBmv\fP/\fBmove\fP, \fBins\fP/\fBinsert\fP, and \fBrm\fP/\fBremove\fP\&.
.TP
.B lens
The lens to use, needs to be suffixed with \fI\&.lns\fP, e.g.: \fINginx.lns\fP\&. See
the \fI\%list of stock lenses\fP
shipped with Augeas.
.UNINDENT
.sp
Usage examples:
.sp
Set the \fBbind\fP parameter in \fB/etc/redis/redis.conf\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
redis\-conf:
augeas.change:
\- changes:
\- set /files/etc/redis/redis.conf/bind 0.0.0.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Use the \fBcontext\fP parameter to specify the file you want to
manipulate. This way you don\(aqt have to include this in the changes
every time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
redis\-conf:
augeas.change:
\- context: /files/etc/redis/redis.conf
\- changes:
\- set bind 0.0.0.0
\- set databases 4
\- set maxmemory 1G
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Augeas is aware of a lot of common configuration files and their syntax.
It knows the difference between for example ini and yaml files, but also
files with very specific syntax, like the hosts file. This is done with
\fIlenses\fP, which provide mappings between the Augeas tree and the file.
.sp
There are many \fI\%preconfigured lenses\fP that come with Augeas by default,
and they specify the common locations for configuration files. So most
of the time Augeas will know how to manipulate a file. In the event that
you need to manipulate a file that Augeas doesn\(aqt know about, you can
specify the lens to use like this:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
redis\-conf:
augeas.change:
\- lens: redis
\- context: /files/etc/redis/redis.conf
\- changes:
\- set bind 0.0.0.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Even though Augeas knows that \fB/etc/redis/redis.conf\fP is a Redis
configuration file and knows how to parse it, it is recommended to
specify the lens anyway. This is because by default, Augeas loads all
known lenses and their associated file paths. All these files are
parsed when Augeas is loaded, which can take some time. When specifying
a lens, Augeas is loaded with only that lens, which speeds things up
quite a bit.
.UNINDENT
.UNINDENT
.sp
A more complex example, this adds an entry to the services file for Zabbix,
and removes an obsolete service:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
zabbix\-service:
augeas.change:
\- lens: services
\- context: /files/etc/services
\- changes:
\- ins service\-name after service\-name[last()]
\- set service\-name[last()] zabbix\-agent
\- set service\-name[. = \(aqzabbix\-agent\(aq]/#comment "Zabbix Agent service"
\- set service\-name[. = \(aqzabbix\-agent\(aq]/port 10050
\- set service\-name[. = \(aqzabbix\-agent\(aq]/protocol tcp
\- rm service\-name[. = \(aqim\-obsolete\(aq]
\- unless: grep "zabbix\-agent" /etc/services
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Don\(aqt forget the \fBunless\fP here, otherwise a new entry will be added
every time this state is run.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.augeas.setvalue(name, prefix=None, changes=None, **kwargs)
Deprecated since version 2014.7.0: Use \fI\%change()\fP instead.
.sp
Set a value for a specific augeas path
.UNINDENT
.SS salt.states.aws_sqs
.SS Manage SQS Queues
.sp
Create and destroy SQS queues. Be aware that this interacts with Amazon\(aqs
services, and so may incur charges.
.sp
This module uses the awscli tool provided by Amazon. This can be downloaded
from pip. Also check the documentation for awscli for configuration
information.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myqueue:
aws_sqs.exists:
\- region: eu\-west\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.aws_sqs.absent(name, region, user=None, opts=False)
Remove the named SQS queue if it exists.
.INDENT 7.0
.TP
.B name
Name of the SQS queue.
.TP
.B region
Region to remove the queue from
.TP
.B user
Name of the user performing the SQS operations
.TP
.B opts
Include additional arguments and options to the aws command line
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.aws_sqs.exists(name, region, user=None, opts=False)
Ensure the SQS queue exists.
.INDENT 7.0
.TP
.B name
Name of the SQS queue.
.TP
.B region
Region to create the queue
.TP
.B user
Name of the user performing the SQS operations
.TP
.B opts
Include additional arguments and options to the aws command line
.UNINDENT
.UNINDENT
.SS salt.states.blockdev
.SS Management of Block Devices
.sp
A state module to manage blockdevices
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/dev/sda:
blockdev.tuned:
\- read\-only: True
master\-data:
blockdev.tuned::
\- name : /dev/vg/master\-data
\- read\-only: True
\- read\-ahead: 1024
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.blockdev.formatted(name, fs_type=\(aqext4\(aq, **kwargs)
Manage filesystems of partitions.
.INDENT 7.0
.TP
.B name
The name of the block device
.TP
.B fs_type
The filesystem it should be formatted as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.blockdev.tuned(name, **kwargs)
Manage options of block device
.INDENT 7.0
.TP
.B name
The name of the block device
.TP
.B opts:
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B read\-ahead
Read\-ahead buffer size
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B filesystem\-read\-ahead
Filesystem Read\-ahead buffer size
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B read\-only
Set Read\-Only
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B read\-write
Set Read\-Write
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.boto_asg
.SS Manage Autoscale Groups
.sp
New in version 2014.7.0.
.sp
Create and destroy autoscale groups. Be aware that this interacts with Amazon\(aqs
services, and so may incur charges.
.sp
This module uses boto, which can be installed via package, or pip.
.sp
This module accepts explicit autoscale credentials but can also utilize
IAM roles assigned to the instance trough Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More Information available at:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
asg.keyid: GKTADJGHEIQSXMKKRBJ08H
asg.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Ensure myasg exists:
boto_asg.present:
\- name: myasg
\- launch_config_name: mylc
\- availability_zones:
\- us\-east\-1a
\- us\-east\-1b
\- min_size: 1
\- max_size: 1
\- desired_capacity: 1
\- load_balancers:
\- myelb
\- suspended_processes:
\- AddToLoadBalancer
\- AlarmNotification
\- scaling_policies
\-\-\-\-\-\-\-\-\-\-
\- adjustment_type: ChangeInCapacity
\- as_name: api\-production\-iad
\- cooldown: 1800
\- min_adjustment_step: None
\- name: ScaleDown
\- scaling_adjustment: \-1
\- region: us\-east\-1
\- keyid: GKTADJGHEIQSXMKKRBJ08H
\- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# Using a profile from pillars.
Ensure myasg exists:
boto_asg.present:
\- name: myasg
\- launch_config_name: mylc
\- availability_zones:
\- us\-east\-1a
\- us\-east\-1b
\- min_size: 1
\- max_size: 1
\- desired_capacity: 1
\- load_balancers:
\- myelb
\- profile: myprofile
# Passing in a profile.
Ensure myasg exists:
boto_asg.present:
\- name: myasg
\- launch_config_name: mylc
\- availability_zones:
\- us\-east\-1a
\- us\-east\-1b
\- min_size: 1
\- max_size: 1
\- desired_capacity: 1
\- load_balancers:
\- myelb
\- profile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
# Deleting an autoscale group with running instances.
Ensure myasg is deleted:
boto_asg.absent:
\- name: myasg
# If instances exist, we must force the deletion of the asg.
\- force: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_asg.absent(name, force=False, region=None, key=None, keyid=None, profile=None)
Ensure the named autoscale group is deleted.
.INDENT 7.0
.TP
.B name
Name of the autoscale group.
.TP
.B force
Force deletion of autoscale group.
.TP
.B region
The region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_asg.present(name, launch_config_name, availability_zones, min_size, max_size, launch_config=None, desired_capacity=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, tags=None, termination_policies=None, suspended_processes=None, scaling_policies=None, region=None, key=None, keyid=None, profile=None)
Ensure the autoscale group exists.
.INDENT 7.0
.TP
.B name
Name of the autoscale group.
.UNINDENT
.sp
launch_config_name
Name of the launch config to use for the group. Or, if
launch_config is specified, this will be the launch config
name\(aqs prefix. (see below)
.sp
launch_config
A dictionary of launch config attributes. If specified, a
launch config will be used or created, matching this set
of attributes, and the autoscale group will be set to use
that launch config. The launch config name will be the
launch_config_name followed by a hyphen followed by a hash
of the launch_config dict contents.
.INDENT 7.0
.TP
.B availability_zones
List of availability zones for the group.
.TP
.B min_size
Minimum size of the group.
.TP
.B max_size
Maximum size of the group.
.TP
.B desired_capacity
The desired capacity of the group.
.TP
.B load_balancers
List of load balancers for the group. Once set this can not be
updated (Amazon restriction).
.TP
.B default_cooldown
Number of seconds after a Scaling Activity completes before any further
scaling activities can start.
.TP
.B health_check_type
The service you want the health status from, Amazon EC2 or Elastic Load
Balancer (EC2 or ELB).
.TP
.B health_check_period
Length of time in seconds after a new EC2 instance comes into service
that Auto Scaling starts checking its health.
.TP
.B placement_group
Physical location of your cluster placement group created in Amazon
EC2. Once set this can not be updated (Amazon restriction).
.TP
.B vpc_zone_identifier
A list of the subnet identifiers of the Virtual Private Cloud.
.TP
.B tags
.INDENT 7.0
.TP
.B A list of tags. Example:
.INDENT 7.0
.IP \(bu 2
key: \(aqkey\(aq
value: \(aqvalue\(aq
propagate_at_launch: true
.UNINDENT
.UNINDENT
.TP
.B termination_policies
A list of termination policies. Valid values are: “OldestInstance”,
“NewestInstance”, “OldestLaunchConfiguration”,
“ClosestToNextInstanceHour”, “Default”. If no value is specified, the
“Default” value is used.
.TP
.B suspended_processes
List of processes to be suspended. see
\fI\%http://docs.aws.amazon.com/AutoScaling/latest/DeveloperGuide/US_SuspendResume.html\fP
.TP
.B scaling_policies
List of scaling policies. Each policy is a dict of key\-values described by
\fI\%http://boto.readthedocs.org/en/latest/ref/autoscale.html#boto.ec2.autoscale.policy.ScalingPolicy\fP
.TP
.B region
The region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_cloudwatch_alarm
.SS Manage Cloudwatch alarms
.sp
New in version 2014.7.0.
.sp
Create and destroy cloudwatch alarms. Be aware that this interacts with
Amazon\(aqs services, and so may incur charges.
.sp
This module uses boto, which can be installed via package, or pip.
.sp
This module accepts explicit credentials but can also utilize
IAM roles assigned to the instance trough Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More Information available at:
.sp
\fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html\fP
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cloudwatch.keyid: GKTADJGHEIQSXMKKRBJ08H
cloudwatch.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my test alarm:
boto_cloudwatch_alarm.present:
\- name: my test alarm
\- attributes:
metric: ApproximateNumberOfMessagesVisible
namespace: AWS/SQS
statistic: Average
comparison: ">="
threshold: 20000.0
period: 60
evaluation_periods: 1
description: test alarm via salt
dimensions:
QueueName:
\- the\-sqs\-queue\-name
alarm_actions:
\- arn:aws:sns:us\-east\-1:1111111:myalerting\-action
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_cloudwatch_alarm.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the named cloudwatch alarm is deleted.
.INDENT 7.0
.TP
.B name
Name of the alarm.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_cloudwatch_alarm.present(name, attributes, region=None, key=None, keyid=None, profile=None)
Ensure the cloudwatch alarm exists.
.INDENT 7.0
.TP
.B name
Name of the alarm
.TP
.B attributes
A dict of key/value cloudwatch alarm attributes.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_elasticache
.SS Manage Elasticache
.sp
New in version 2014.7.0.
.sp
Create, destroy and update Elasticache clusters. Be aware that this interacts
with Amazon\(aqs services, and so may incur charges.
.sp
Note: This module currently only supports creation and deletion of
elasticache resources and will not modify clusters when their configuration
changes in your state files.
.sp
This module uses \fBboto\fP, which can be installed via package, or pip.
.sp
This module accepts explicit elasticache credentials but can also utilize
IAM roles assigned to the instance through Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More information available \fI\%here\fP\&.
.sp
If IAM roles are not used you need to specify them either in a pillar file or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
elasticache.keyid: GKTADJGHEIQSXMKKRBJ08H
elasticache.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either
passed in as a dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Ensure myelasticache exists:
boto_elasticache.present:
\- name: myelasticache
\- engine: redis
\- cache_node_type: cache.t1.micro
\- num_cache_nodes: 1
\- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
\- region: us\-east\-1
\- keyid: GKTADJGHEIQSXMKKRBJ08H
\- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# Using a profile from pillars
Ensure myelasticache exists:
boto_elasticache.present:
\- name: myelasticache
\- engine: redis
\- cache_node_type: cache.t1.micro
\- num_cache_nodes: 1
\- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
\- region: us\-east\-1
\- profile: myprofile
# Passing in a profile
Ensure myelasticache exists:
boto_elasticache.present:
\- name: myelasticache
\- engine: redis
\- cache_node_type: cache.t1.micro
\- num_cache_nodes: 1
\- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
\- region: us\-east\-1
\- profile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_elasticache.absent(name, wait=True, region=None, key=None, keyid=None, profile=None)
Ensure the named elasticache cluster is deleted.
.INDENT 7.0
.TP
.B name
Name of the cache cluster.
.TP
.B wait
Boolean. Wait for confirmation from boto that the cluster is in the
deleting state.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_elasticache.present(name, engine, cache_node_type, num_cache_nodes=1, preferred_availability_zone=None, port=None, cache_parameter_group_name=None, cache_security_group_names=None, replication_group_id=None, auto_minor_version_upgrade=True, security_group_ids=None, cache_subnet_group_name=None, engine_version=None, notification_topic_arn=None, preferred_maintenance_window=None, wait=True, region=None, key=None, keyid=None, profile=None)
Ensure the cache cluster exists.
.INDENT 7.0
.TP
.B name
Name of the cache cluster (cache cluster id).
.TP
.B engine
The name of the cache engine to be used for this cache cluster. Valid
values are memcached or redis.
.TP
.B cache_node_type
The compute and memory capacity of the nodes in the cache cluster.
cache.t1.micro, cache.m1.small, etc. See: \fI\%http://boto.readthedocs.org/en/latest/ref/elasticache.html#boto.elasticache.layer1.ElastiCacheConnection.create_cache_cluster\fP
.TP
.B num_cache_nodes
The number of cache nodes that the cache cluster will have.
.TP
.B preferred_availability_zone
The EC2 Availability Zone in which the cache cluster will be created.
All cache nodes belonging to a cache cluster are placed in the
preferred availability zone.
.TP
.B port
The port number on which each of the cache nodes will accept
connections.
.TP
.B cache_parameter_group_name
The name of the cache parameter group to associate with this cache
cluster. If this argument is omitted, the default cache parameter group
for the specified engine will be used.
.TP
.B cache_security_group_names
A list of cache security group names to associate with this cache
cluster. Use this parameter only when you are creating a cluster
outside of a VPC.
.TP
.B replication_group_id
The replication group to which this cache cluster should belong. If
this parameter is specified, the cache cluster will be added to the
specified replication group as a read replica; otherwise, the cache
cluster will be a standalone primary that is not part of any
replication group.
.TP
.B auto_minor_version_upgrade
Determines whether minor engine upgrades will be applied automatically
to the cache cluster during the maintenance window. A value of True
allows these upgrades to occur; False disables automatic upgrades.
.TP
.B security_group_ids
One or more VPC security groups associated with the cache cluster. Use
this parameter only when you are creating a cluster in a VPC.
.TP
.B cache_subnet_group_name
The name of the cache subnet group to be used for the cache cluster.
Use this parameter only when you are creating a cluster in a VPC.
.TP
.B engine_version
The version number of the cache engine to be used for this cluster.
.TP
.B notification_topic_arn
The Amazon Resource Name (ARN) of the Amazon Simple Notification
Service (SNS) topic to which notifications will be sent. The Amazon SNS
topic owner must be the same as the cache cluster owner.
.TP
.B preferred_maintenance_window
The weekly time range (in UTC) during which system maintenance can
occur. Example: sun:05:00\-sun:09:00
.TP
.B wait
Boolean. Wait for confirmation from boto that the cluster is in the
creating state.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_elb
.SS Manage ELBs
.sp
New in version 2014.7.0.
.sp
Create and destroy ELBs. Be aware that this interacts with Amazon\(aqs
services, and so may incur charges.
.sp
This module uses \fBboto\fP, which can be installed via package, or pip.
.sp
This module accepts explicit elb credentials but can also utilize
IAM roles assigned to the instance through Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More information available \fI\%here\fP\&.
.sp
If IAM roles are not used you need to specify them either in a pillar file or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
elb.keyid: GKTADJGHEIQSXMKKRBJ08H
elb.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either
passed in as a dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Ensure myelb ELB exists:
boto_elb.present:
\- name: myelb
\- region: us\-east\-1
\- keyid: GKTADJGHEIQSXMKKRBJ08H
\- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
\- listeners:
\- elb_port: 443
instance_port: 80
elb_protocol: HTTPS
instance_protocol: HTTP
certificate: \(aqarn:aws:iam::1111111:server\-certificate/mycert\(aq
\- elb_port: 8210
instance_port: 8210
elb_protocol: TCP
\- health_check:
target: \(aqHTTP:80/\(aq
\- attributes:
cross_zone_load_balancing:
enabled: true
access_log:
enabled: true
s3_bucket_name: \(aqmybucket\(aq
s3_bucket_prefix: \(aqmy\-logs\(aq
emit_interval: 5
\- cnames:
\- name: mycname.example.com.
zone: example.com.
ttl: 60
\- name: myothercname.example.com.
zone: example.com.
# Using a profile from pillars
Ensure myelb ELB exists:
boto_elb.present:
\- name: myelb
\- region: us\-east\-1
\- profile: myelbprofile
# Passing in a profile
Ensure myelb ELB exists:
boto_elb.present:
\- name: myelb
\- region: us\-east\-1
\- profile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_elb.absent(name, region=None, key=None, keyid=None, profile=None)
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_elb.present(name, listeners, availability_zones=None, subnets=None, security_groups=None, scheme=\(aqinternet\-facing\(aq, health_check=None, attributes=None, cnames=None, region=None, key=None, keyid=None, profile=None)
Ensure the IAM role exists.
.INDENT 7.0
.TP
.B name
Name of the IAM role.
.TP
.B availability_zones
A list of availability zones for this ELB.
.TP
.B listeners
A list of listener lists; example: [[\(aq443\(aq, \(aqHTTPS\(aq, \(aqarn:aws:iam::1111111:server\-certificate/mycert\(aq], [\(aq8443\(aq, \(aq80\(aq, \(aqHTTPS\(aq, \(aqHTTP\(aq, \(aqarn:aws:iam::1111111:server\-certificate/mycert\(aq]]
.TP
.B subnets
A list of subnet IDs in your VPC to attach to your LoadBalancer.
.TP
.B security_groups
The security groups assigned to your LoadBalancer within your VPC.
.TP
.B scheme
The type of a LoadBalancer. internet\-facing or internal. Once set, can not be modified.
.TP
.B health_check
A dict defining the health check for this ELB.
.TP
.B attributes
A dict defining the attributes to set on this ELB.
.TP
.B cnames
A list of cname dicts with attributes: name, zone, ttl, and identifier.
See the boto_route53 state for information about these attributes.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_iam_role
.SS Manage IAM roles.
.sp
New in version 2014.7.0.
.sp
This module uses \fBboto\fP, which can be installed via package, or pip.
.sp
This module accepts explicit IAM credentials but can also utilize
IAM roles assigned to the instance through Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More information available \fI\%here\fP\&.
.sp
If IAM roles are not used you need to specify them either in a pillar file or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
iam.keyid: GKTADJGHEIQSXMKKRBJ08H
iam.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either
passed in as a dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Creating a role will automatically create an instance profile and associate it
with the role. This is the default behavior of the AWS console.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myrole:
boto_iam_role.present:
\- region: us\-east\-1
\- key: GKTADJGHEIQSXMKKRBJ08H
\- keyid: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
\- policies:
MySQSPolicy:
Statement:
\- Action:
\- sqs:*
Effect: Allow
Resource:
\- arn:aws:sqs:*:*:*
Sid: MyPolicySQS1
MyS3Policy:
Statement:
\- Action:
\- s3:GetObject
Effect: Allow
Resource:
\- arn:aws:s3:*:*:mybucket/*
# Using a credentials profile from pillars
myrole:
boto_iam_role.present:
\- region: us\-east\-1
\- profile: myiamprofile
# Passing in a credentials profile
myrole:
boto_iam_role.present:
\- region: us\-east\-1
\- profile:
key: GKTADJGHEIQSXMKKRBJ08H
keyid: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_iam_role.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the IAM role is deleted.
.INDENT 7.0
.TP
.B name
Name of the IAM role.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_iam_role.present(name, policy_document=None, path=None, policies=None, region=None, key=None, keyid=None, profile=None)
Ensure the IAM role exists.
.INDENT 7.0
.TP
.B name
Name of the IAM role.
.TP
.B policy_document
The policy that grants an entity permission to assume the role. (See \fI\%http://boto.readthedocs.org/en/latest/ref/iam.html#boto.iam.connection.IAMConnection.create_role\fP)
.TP
.B path
The path to the instance profile. (See \fI\%http://boto.readthedocs.org/en/latest/ref/iam.html#boto.iam.connection.IAMConnection.create_role\fP)
.TP
.B policies
A dict of IAM role policies.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_lc
.SS Manage Launch Configurations
.sp
New in version 2014.7.0.
.sp
Create and destroy Launch Configurations. Be aware that this interacts with
Amazon\(aqs services, and so may incur charges.
.sp
A limitation of this module is that you can not modify launch configurations
once they have been created. If a launch configuration with the specified name
exists, this module will always report success, even if the specified
configuration doesn\(aqt match. This is due to a limitation in Amazon\(aqs launch
configuration API, as it only allows launch configurations to be created and
deleted.
.sp
Also note that a launch configuration that\(aqs in use by an autoscale group can
not be deleted until the autoscale group is no longer using it. This may affect
the way in which you want to order your states.
.sp
This module uses \fBboto\fP, which can be installed via package, or pip.
.sp
This module accepts explicit autoscale credentials but can also utilize
IAM roles assigned to the instance through Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More information available \fI\%here\fP\&.
.sp
If IAM roles are not used you need to specify them either in a pillar file or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
asg.keyid: GKTADJGHEIQSXMKKRBJ08H
asg.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either
passed in as a dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Credential information is shared with autoscale groups as launch configurations
and autoscale groups are completely dependent on each other.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Ensure mylc exists:
boto_lc.present:
\- name: mylc
\- image_id: ami\-0b9c9f62
\- key_name: mykey
\- security_groups:
\- mygroup
\- instance_type: m1.small
\- instance_monitoring: true
\- block_device_mappings:
\- \(aq/dev/sda1\(aq:
size: 20
\- cloud_init:
scripts:
\(aqrun_salt.sh\(aq: |
#!/bin/bash
add\-apt\-repository \-y ppa:saltstack/salt
apt\-get update
apt\-get install \-y salt\-minion
salt\-call state.highstate
\- region: us\-east\-1
\- keyid: GKTADJGHEIQSXMKKRBJ08H
\- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# Using a profile from pillars.
Ensure mylc exists:
boto_lc.present:
\- name: mylc
\- image_id: ami\-0b9c9f62
\- profile: myprofile
# Passing in a profile.
Ensure mylc exists:
boto_lc.present:
\- name: mylc
\- image_id: ami\-0b9c9f62
\- profile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_lc.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the named launch configuration is deleted.
.INDENT 7.0
.TP
.B name
Name of the launch configuration.
.TP
.B region
The region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_lc.present(name, image_id, key_name=None, security_groups=None, user_data=None, cloud_init=None, instance_type=\(aqm1.small\(aq, kernel_id=None, ramdisk_id=None, block_device_mappings=None, instance_monitoring=False, spot_price=None, instance_profile_name=None, ebs_optimized=False, associate_public_ip_address=None, volume_type=None, delete_on_termination=True, iops=None, use_block_device_types=False, region=None, key=None, keyid=None, profile=None)
Ensure the launch configuration exists.
.INDENT 7.0
.TP
.B name
Name of the launch configuration.
.TP
.B image_id
AMI to use for instances. AMI must exist or creation of the launch
configuration will fail.
.TP
.B key_name
Name of the EC2 key pair to use for instances. Key must exist or
creation of the launch configuration will fail.
.TP
.B security_groups
List of Names or security group id’s of the security groups with which
to associate the EC2 instances or VPC instances, respectively. Security
groups must exist, or creation of the launch configuration will fail.
.TP
.B user_data
The user data available to launched EC2 instances.
.TP
.B cloud_init
A dict of cloud_init configuration. Currently supported values:
scripts, cloud\-config. Mutually exlusive with user_data.
.TP
.B instance_type
The instance type. ex: m1.small.
.TP
.B kernel_id
The kernel id for the instance.
.TP
.B ramdisk_id
The RAM disk ID for the instance.
.TP
.B block_device_mappings
A dict of block device mappings.
.TP
.B instance_monitoring
Whether instances in group are launched with detailed monitoring.
.TP
.B spot_price
The spot price you are bidding. Only applies if you are building an
autoscaling group with spot instances.
.TP
.B instance_profile_name
The name or the Amazon Resource Name (ARN) of the instance profile
associated with the IAM role for the instance. Instance profile must
exist or the creation of the launch configuration will fail.
.TP
.B ebs_optimized
Specifies whether the instance is optimized for EBS I/O (true) or not
(false).
.TP
.B associate_public_ip_address
Used for Auto Scaling groups that launch instances into an Amazon
Virtual Private Cloud. Specifies whether to assign a public IP address
to each instance launched in a Amazon VPC.
.TP
.B volume_type
Undocumented in boto.
.TP
.B delete_on_termination
Undocumented in boto.
.TP
.B iops
Undocumented in boto.
.TP
.B use_block_device_types
Undocumented in boto.
.TP
.B region
The region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_route53
.SS Manage Route53 records
.sp
New in version 2014.7.0.
.sp
Create and delete Route53 records. Be aware that this interacts with Amazon\(aqs
services, and so may incur charges.
.sp
This module uses \fBboto\fP, which can be installed via package, or pip.
.sp
This module accepts explicit route53 credentials but can also utilize
IAM roles assigned to the instance through Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More information available \fI\%here\fP\&.
.sp
If IAM roles are not used you need to specify them either in a pillar file or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
route53.keyid: GKTADJGHEIQSXMKKRBJ08H
route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either
passed in as a dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mycnamerecord:
boto_route53.present:
\- name: test.example.com.
\- value: my\-elb.us\-east\-1.elb.amazonaws.com.
\- zone: example.com.
\- ttl: 60
\- record_type: CNAME
\- region: us\-east\-1
\- keyid: GKTADJGHEIQSXMKKRBJ08H
\- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# Using a profile from pillars
myarecord:
boto_route53.present:
\- name: test.example.com.
\- value: 1.1.1.1
\- zone: example.com.
\- ttl: 60
\- record_type: A
\- region: us\-east\-1
\- profile: myprofile
# Passing in a profile
myarecord:
boto_route53.present:
\- name: test.example.com.
\- value: 1.1.1.1
\- zone: example.com.
\- ttl: 60
\- record_type: A
\- region: us\-east\-1
\- profile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_route53.absent(name, zone, record_type, identifier=None, region=None, key=None, keyid=None, profile=None)
Ensure the Route53 record is deleted.
.INDENT 7.0
.TP
.B name
Name of the record.
.TP
.B zone
The zone to delete the record from.
.TP
.B identifier
An identifier to match for deletion.
.TP
.B region
The region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_route53.present(name, value, zone, record_type, ttl=None, identifier=None, region=None, key=None, keyid=None, profile=None)
Ensure the Route53 record is present.
.INDENT 7.0
.TP
.B name
Name of the record.
.TP
.B value
Value of the record.
.TP
.B zone
The zone to create the record in.
.TP
.B record_type
The record type. Currently supported values: A, CNAME, MX
.TP
.B ttl
The time to live for the record.
.TP
.B identifier
The unique identifier to use for this record.
.TP
.B region
The region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_secgroup
.SS Manage Security Groups
.sp
New in version 2014.7.0.
.sp
Create and destroy Security Groups. Be aware that this interacts with Amazon\(aqs
services, and so may incur charges.
.sp
This module uses \fBboto\fP, which can be installed via package, or pip.
.sp
This module accepts explicit EC2 credentials but can also utilize
IAM roles assigned to the instance through Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More information available \fI\%here\fP\&.
.sp
If IAM roles are not used you need to specify them either in a pillar file or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
secgroup.keyid: GKTADJGHEIQSXMKKRBJ08H
secgroup.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either
passed in as a dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Ensure mysecgroup exists:
boto_secgroup.present:
\- name: mysecgroup
\- description: My security group
\- rules:
\- ip_protocol: tcp
from_port: 80
to_port: 80
cidr_ip:
\- 10.0.0.0/0
\- 192.168.0.0/0
\- region: us\-east\-1
\- keyid: GKTADJGHEIQSXMKKRBJ08H
\- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
# Using a profile from pillars
Ensure mysecgroup exists:
boto_secgroup.present:
\- name: mysecgroup
\- description: My security group
\- region: us\-east\-1
\- profile: myprofile
# Passing in a profile
Ensure mysecgroup exists:
boto_secgroup.present:
\- name: mysecgroup
\- description: My security group
\- region: us\-east\-1
\- profile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_secgroup.absent(name, vpc_id=None, region=None, key=None, keyid=None, profile=None)
Ensure a security group with the specified name does not exist.
.INDENT 7.0
.TP
.B name
Name of the security group.
.TP
.B vpc_id
The ID of the VPC to create the security group in, if any.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_secgroup.present(name, description, vpc_id=None, rules=None, region=None, key=None, keyid=None, profile=None)
Ensure the security group exists with the specified rules.
.INDENT 7.0
.TP
.B name
Name of the security group.
.TP
.B description
A description of this security group.
.TP
.B vpc_id
The ID of the VPC to create the security group in, if any.
.TP
.B rules
A list of ingress rule dicts.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.boto_sqs
.SS Manage SQS Queues
.sp
New in version 2014.7.0.
.sp
Create and destroy SQS queues. Be aware that this interacts with Amazon\(aqs
services, and so may incur charges.
.sp
This module uses \fBboto\fP, which can be installed via package, or pip.
.sp
This module accepts explicit SQS credentials but can also utilize
IAM roles assigned to the instance through Instance Profiles. Dynamic
credentials are then automatically obtained from AWS API and no further
configuration is necessary. More information available \fI\%here\fP\&.
.sp
If IAM roles are not used you need to specify them either in a pillar file or
in the minion\(aqs config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sqs.keyid: GKTADJGHEIQSXMKKRBJ08H
sqs.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It\(aqs also possible to specify \fBkey\fP, \fBkeyid\fP and \fBregion\fP via a profile, either
passed in as a dict, or as a string to pull from pillars or minion config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
region: us\-east\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
myqueue:
boto_sqs.present:
\- region: us\-east\-1
\- keyid: GKTADJGHEIQSXMKKRBJ08H
\- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
\- attributes:
ReceiveMessageWaitTimeSeconds: 20
# Using a profile from pillars
myqueue:
boto_sqs.present:
\- region: us\-east\-1
\- profile: mysqsprofile
# Passing in a profile
myqueue:
boto_sqs.present:
\- region: us\-east\-1
\- profile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_sqs.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the named sqs queue is deleted.
.INDENT 7.0
.TP
.B name
Name of the SQS queue.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.boto_sqs.present(name, attributes=None, region=None, key=None, keyid=None, profile=None)
Ensure the SQS queue exists.
.INDENT 7.0
.TP
.B name
Name of the SQS queue.
.TP
.B attributes
A dict of key/value SQS attributes.
.TP
.B region
Region to connect to.
.TP
.B key
Secret key to be used.
.TP
.B keyid
Access key to be used.
.TP
.B profile
A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.SS salt.states.cloud
.SS Using states instead of maps to deploy clouds
.sp
New in version 2014.1.0.
.sp
Use this minion to spin up a cloud instance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my\-ec2\-instance:
cloud.profile:
my\-ec2\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cloud.absent(name, onlyif=None, unless=None)
Ensure that no instances with the specified names exist.
.sp
CAUTION: This is a destructive state, which will search all
configured cloud providers for the named instance,
and destroy it.
.INDENT 7.0
.TP
.B name
The name of the instance to destroy
.TP
.B onlyif
Do run the state only if is unless succeed
.TP
.B unless
Do not run the state at least unless succeed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cloud.present(name, cloud_provider, onlyif=None, unless=None, **kwargs)
Spin up a single instance on a cloud provider, using salt\-cloud. This state
does not take a profile argument; rather, it takes the arguments that would
normally be configured as part of the state.
.sp
Note that while this function does take any configuration argument that
would normally be used to create an instance, it will not verify the state
of any of those arguments on an existing instance. Stateful properties of
an instance should be configured using their own individual state (i.e.,
cloud.tagged, cloud.untagged, etc).
.INDENT 7.0
.TP
.B name
The name of the instance to create
.TP
.B cloud_provider
The name of the cloud provider to use
.TP
.B onlyif
Do run the state only if is unless succeed
.TP
.B unless
Do not run the state at least unless succeed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cloud.profile(name, profile, onlyif=None, unless=None, **kwargs)
Create a single instance on a cloud provider, using a salt\-cloud profile.
.sp
Note that while profiles used this function do take any configuration
argument that would normally be used to create an instance using a profile,
this state will not verify the state of any of those arguments on an
existing instance. Stateful properties of an instance should be configured
using their own individual state (i.e., cloud.tagged, cloud.untagged, etc).
.INDENT 7.0
.TP
.B name
The name of the instance to create
.TP
.B profile
The name of the cloud profile to use
.TP
.B onlyif
Do run the state only if is unless succeed
.TP
.B unless
Do not run the state at least unless succeed
.TP
.B kwargs
Any profile override or addition
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cloud.volume_absent(name, provider=None, **kwargs)
Check that a block volume exists.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cloud.volume_attached(name, server_name, provider=None, **kwargs)
Check if a block volume is attached.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cloud.volume_detached(name, server_name=None, provider=None, **kwargs)
Check if a block volume is attached.
.sp
Returns True if server or Volume do not exist.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cloud.volume_present(name, provider=None, **kwargs)
Check that a block volume exists.
.UNINDENT
.SS salt.states.cmd
.SS Execution of arbitrary commands
.sp
The cmd state module manages the enforcement of executed commands, this
state can tell a command to run under certain circumstances.
.sp
A simple example to execute a command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
date > /tmp/salt\-run:
cmd.run
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Only run if another execution failed, in this case truncate syslog if there is
no disk space:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
> /var/log/messages:
cmd.run:
\- unless: echo \(aqfoo\(aq > /tmp/.test
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Only run if the file specified by \fBcreates\fP does not exist, in this case
touch /tmp/foo if it does not exist.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
touch /tmp/foo:
cmd.run:
\- creates: /tmp/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBcreates\fP option was added to version 2014.7.0
.UNINDENT
.UNINDENT
.sp
Salt determines whether the \fBcmd\fP state is successfully enforced based on the exit
code returned by the command. If the command returns a zero exit code, then salt
determines that the state was successfully enforced. If the script returns a non\-zero
exit code, then salt determines that it failed to successfully enforce the state.
If a command returns a non\-zero exit code but you wish to treat this as a success,
then you must place the command in a script and explicitly set the exit code of
the script to zero.
.sp
Please note that the success or failure of the state is not affected by whether a state
change occurred nor the stateful argument.
.sp
When executing a command or script, the state (i.e., changed or not)
of the command is unknown to Salt\(aqs state system. Therefore, by default, the
\fBcmd\fP state assumes that any command execution results in a changed state.
.sp
This means that if a \fBcmd\fP state is watched by another state then the
state that\(aqs watching will always be executed due to the \fIchanged\fP state in
the \fBcmd\fP state.
.sp
Many state functions in this module now also accept a \fBstateful\fP argument.
If \fBstateful\fP is specified to be true then it is assumed that the command
or script will determine its own state and communicate it back by following
a simple protocol described below:
.INDENT 0.0
.IP 1. 3
\fBIf there\(aqs nothing in the stdout of the command, then assume no
changes.\fP Otherwise, the stdout must be either in JSON or its \fIlast\fP
non\-empty line must be a string of key=value pairs delimited by spaces (no
spaces on either side of \fB=\fP).
.IP 2. 3
\fBIf it\(aqs JSON then it must be a JSON object (e.g., {}).\fP If it\(aqs
key=value pairs then quoting may be used to include spaces. (Python\(aqs shlex
module is used to parse the key=value string)
.sp
Two special keys or attributes are recognized in the output:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
changed: bool (i.e., \(aqyes\(aq, \(aqno\(aq, \(aqtrue\(aq, \(aqfalse\(aq, case\-insensitive)
comment: str (i.e., any string)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
So, only if \fBchanged\fP is \fBTrue\fP then assume the command execution has
changed the state, and any other key values or attributes in the output will
be set as part of the changes.
.IP 3. 3
\fBIf there\(aqs a comment then it will be used as the comment of the
state.\fP
.sp
Here\(aqs an example of how one might write a shell script for use with a
stateful command:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/bash
#
echo "Working hard..."
# writing the state line
echo # an empty line here so the next line will be the last.
echo "changed=yes comment=\(aqsomething has changed\(aq whatever=123"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And an example SLS file using this module:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
Run myscript:
cmd.run:
\- name: /path/to/myscript
\- cwd: /
\- stateful: True
Run only if myscript changed something:
cmd.wait:
\- name: echo hello
\- cwd: /
\- watch:
\- cmd: Run myscript
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that if the \fBcmd.wait\fP state also specifies \fBstateful: True\fP it can
then be watched by some other states as well.
.UNINDENT
.sp
\fBcmd.wait\fP is not restricted to watching only cmd states. For example
it can also watch a git state for changes
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Watch for changes to a git repo and rebuild the project on updates
my\-project:
git.latest:
\- name: git@github.com/repo/foo
\- target: /opt/foo
\- rev: master
cmd.wait:
\- name: make install
\- cwd: /opt/foo
\- watch:
\- git: my\-project
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Should I use \fI\%cmd.run\fP or \fI\%cmd.wait\fP?
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.sp
These two states are often confused. The important thing to remember about them
is that \fI\%cmd.run\fP states are run each time the SLS
file that contains them is applied. If it is more desirable to have a command
that only runs after some other state changes, then \fI\%cmd.wait\fP does just that. \fI\%cmd.wait\fP
is designed to \fBwatch\fP other states, and is
executed when the state it is watching changes. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/usr/local/bin/postinstall.sh:
cmd.wait:
\- watch:
\- pkg: mycustompkg
file.managed:
\- source: salt://utils/scripts/postinstall.sh
mycustompkg:
pkg.installed:
\- require:
\- file: /usr/local/bin/postinstall.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.SS How do I create an environment from a pillar map?
.sp
The map that comes from a pillar cannot be directly consumed by the env option.
To use it one must convert it to a list. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
printenv:
cmd.run:
\- env:
{% for key, value in pillar[\(aqkeys\(aq].iteritems() %}
\- \(aq{{ key }}\(aq: \(aq{{ value }}\(aq
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.call(name, func, args=(), kws=None, onlyif=None, unless=None, creates=None, output_loglevel=\(aqdebug\(aq, use_vt=False, **kwargs)
Invoke a pre\-defined Python function with arguments specified in the state
declaration. This function is mainly used by the
\fBsalt.renderers.pydsl\fP renderer.
.sp
The interpretation of \fBonlyif\fP and \fBunless\fP arguments are identical to
those of \fI\%cmd.run\fP, and all other
arguments(\fBcwd\fP, \fBrunas\fP, ...) allowed by \fI\%cmd.run\fP are allowed here, except that their effects apply
only to the commands specified in \fIonlyif\fP and \fIunless\fP rather than to the
function to be invoked.
.sp
In addition, the \fBstateful\fP argument has no effects here.
.sp
The return value of the invoked function will be interpreted as follows.
.sp
If it\(aqs a dictionary then it will be passed through to the state system,
which expects it to have the usual structure returned by any salt state
function.
.sp
Otherwise, the return value (denoted as \fBresult\fP in the code below) is
expected to be a JSON serializable object, and this dictionary is returned:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{
\(aqname\(aq: name
\(aqchanges\(aq: {\(aqretval\(aq: result},
\(aqresult\(aq: True if result is None else bool(result),
\(aqcomment\(aq: result if isinstance(result, string_types) else \(aq\(aq
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.mod_run_check(cmd_kwargs, onlyif, unless, group, creates)
Execute the onlyif and unless logic.
Return a result dict if:
* group is not available
* onlyif failed (onlyif != 0)
* unless succeeded (unless == 0)
else return True
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.mod_watch(name, **kwargs)
Execute a cmd function based on a watch call
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.run(name, onlyif=None, unless=None, creates=None, cwd=None, user=None, group=None, shell=None, env=None, stateful=False, umask=None, output_loglevel=\(aqdebug\(aq, quiet=False, timeout=None, use_vt=False, **kwargs)
Run a command if certain circumstances are met. Use \fBcmd.wait\fP if you
want to use the \fBwatch\fP requisite.
.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
.TP
.B shell
The shell to use for execution, defaults to the shell grain
.TP
.B env
A list of environment variables to be set prior to execution.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt://scripts/foo.sh:
cmd.script:
\- env:
\- BATCH: \(aqyes\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
The above illustrates a common PyYAML pitfall, that \fByes\fP,
\fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as
boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in
quotes to be used as strings. More info on this (and other) PyYAML
idiosyncrasies can be found \fBhere\fP\&.
.UNINDENT
.UNINDENT
.TP
.B stateful
The command being executed is expected to return data about executing
a state
.TP
.B umask
The umask (in octal) to use when running the command.
.TP
.B output_loglevel
Control the loglevel at which the output from the command is logged.
Note that the command being run will still be logged (loglevel: DEBUG)
regardless, unless \fBquiet\fP is used for this value.
.TP
.B quiet
The command will be executed quietly, meaning no log entries of the
actual command or its return data. This is deprecated as of the
\fB2014.1.0\fP release, and is being replaced with
\fBoutput_loglevel: quiet\fP\&.
.TP
.B timeout
If the command has not terminated after timeout seconds, send the
subprocess sigterm, and if sigterm is ignored, follow up with sigkill
.TP
.B creates
Only run if the file specified by \fBcreates\fP does not exist.
.sp
New in version 2014.7.0.
.TP
.B use_vt
Use VT utils (saltstack) to stream the command output more
interactively to the console and the logs.
This is experimental.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
cmd.run supports the usage of \fBreload_modules\fP\&. This functionality
allows you to force Salt to reload all modules. You should only use
\fBreload_modules\fP if your cmd.run does some sort of installation
(such as \fBpip\fP), if you do not reload the modules future items in
your state which rely on the software being installed will fail.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
getpip:
cmd.run:
\- name: /usr/bin/python /usr/local/sbin/get\-pip.py
\- unless: which pip
\- require:
\- pkg: python
\- file: /usr/local/sbin/get\-pip.py
\- reload_modules: True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.script(name, source=None, template=None, onlyif=None, unless=None, creates=None, cwd=None, user=None, group=None, shell=None, env=None, stateful=False, umask=None, timeout=None, use_vt=False, output_loglevel=\(aqdebug\(aq, **kwargs)
Download a script and execute it with specified arguments.
.INDENT 7.0
.TP
.B source
The location of the script to download. If the file is located on the
master in the directory named spam, and is called eggs, the source
string is salt://spam/eggs
.TP
.B template
If this setting is applied then the named templating engine will be
used to render the downloaded file. Currently jinja, mako, and wempy
are supported
.TP
.B name
Either "cmd arg1 arg2 arg3..." (cmd is not used) or a source
"salt://...".
.TP
.B onlyif
Run the named command only if the command passed to the \fBonlyif\fP
option returns true
.TP
.B unless
Run the named command only 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 name of the user to run the command as
.TP
.B group
The group context to run the command as
.TP
.B shell
The shell to use for execution. The default is set in grains[\(aqshell\(aq]
.TP
.B env
A list of environment variables to be set prior to execution.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt://scripts/foo.sh:
cmd.script:
\- env:
\- BATCH: \(aqyes\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
The above illustrates a common PyYAML pitfall, that \fByes\fP,
\fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as
boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in
quotes to be used as strings. More info on this (and other) PyYAML
idiosyncrasies can be found \fBhere\fP\&.
.UNINDENT
.UNINDENT
.TP
.B umask
The umask (in octal) to use when running the command.
.TP
.B stateful
The command being executed is expected to return data about executing
a state
.TP
.B timeout
If the command has not terminated after timeout seconds, send the
subprocess sigterm, and if sigterm is ignored, follow up with sigkill
.TP
.B args
String of command line args to pass to the script. Only used if no
args are specified as part of the \fIname\fP argument. To pass a string
containing spaces in YAML, you will need to doubly\-quote it: "arg1
\(aqarg two\(aq arg3"
.TP
.B creates
Only run if the file specified by \fBcreates\fP does not exist.
.sp
New in version 2014.7.0.
.TP
.B use_vt
Use VT utils (saltstack) to stream the command output more
interactively to the console and the logs.
This is experimental.
.TP
.B output_loglevel
Control the loglevel at which the output from the command is logged.
Note that the command being run will still be logged (loglevel: DEBUG)
regardless, unless \fBquiet\fP is used for this value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.wait(name, onlyif=None, unless=None, creates=None, cwd=None, user=None, group=None, shell=None, env=(), stateful=False, umask=None, output_loglevel=\(aqdebug\(aq, use_vt=False, **kwargs)
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
.TP
.B shell
The shell to use for execution, defaults to /bin/sh
.TP
.B env
A list of environment variables to be set prior to execution.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt://scripts/foo.sh:
cmd.script:
\- env:
\- BATCH: \(aqyes\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
The above illustrates a common PyYAML pitfall, that \fByes\fP,
\fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as
boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in
quotes to be used as strings. More info on this (and other) PyYAML
idiosyncrasies can be found \fBhere\fP\&.
.UNINDENT
.UNINDENT
.TP
.B umask
The umask (in octal) to use when running the command.
.TP
.B stateful
The command being executed is expected to return data about executing
a state
.TP
.B creates
Only run if the file specified by \fBcreates\fP does not exist.
.sp
New in version 2014.7.0.
.TP
.B output_loglevel
Control the loglevel at which the output from the command is logged.
Note that the command being run will still be logged (loglevel: DEBUG)
regardless, unless \fBquiet\fP is used for this value.
.TP
.B use_vt
Use VT utils (saltstack) to stream the command output more
interactively to the console and the logs.
This is experimental.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.wait_call(name, func, args=(), kws=None, onlyif=None, unless=None, creates=None, stateful=False, use_vt=False, output_loglevel=\(aqdebug\(aq, **kwargs)
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cmd.wait_script(name, source=None, template=None, onlyif=None, unless=None, cwd=None, user=None, group=None, shell=None, env=None, stateful=False, umask=None, use_vt=False, output_loglevel=\(aqdebug\(aq, **kwargs)
Download a script from a remote source and execute it only if a watch
statement calls it.
.INDENT 7.0
.TP
.B source
The source script being downloaded to the minion, this source script is
hosted on the salt master server. If the file is located on the master
in the directory named spam, and is called eggs, the source string is
salt://spam/eggs
.TP
.B template
If this setting is applied then the named templating engine will be
used to render the downloaded file, currently jinja, mako, and wempy
are supported
.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
.TP
.B shell
The shell to use for execution, defaults to the shell grain
.TP
.B env
A list of environment variables to be set prior to execution.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt://scripts/foo.sh:
cmd.script:
\- env:
\- BATCH: \(aqyes\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
The above illustrates a common PyYAML pitfall, that \fByes\fP,
\fBno\fP, \fBon\fP, \fBoff\fP, \fBtrue\fP, and \fBfalse\fP are all loaded as
boolean \fBTrue\fP and \fBFalse\fP values, and must be enclosed in
quotes to be used as strings. More info on this (and other) PyYAML
idiosyncrasies can be found \fBhere\fP\&.
.UNINDENT
.UNINDENT
.TP
.B umask
The umask (in octal) to use when running the command.
.TP
.B stateful
The command being executed is expected to return data about executing
a state
.TP
.B use_vt
.INDENT 7.0
.INDENT 3.5
Use VT utils (saltstack) to stream the command output more
interactively to the console and the logs.
This is experimental.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B output_loglevel
Control the loglevel at which the output from the command is logged.
Note that the command being run will still be logged (loglevel: DEBUG)
regardless, unless \fBquiet\fP is used for this value.
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.composer
.SS Installation of Composer Packages
.sp
These states manage the installed packages for composer for PHP. Note that
either composer is installed and accessible via a bin directory or you can pass
the location of composer in the state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
get\-composer:
cmd.run:
\- name: \(aqCURL=\(gawhich curl\(ga; $CURL \-sS https://getcomposer.org/installer | php\(aq
\- unless: test \-f /usr/local/bin/composer
\- cwd: /root/
install\-composer:
cmd.wait:
\- name: mv /root/composer.phar /usr/local/bin/composer
\- cwd: /root/
\- watch:
\- cmd: get\-composer
/path/to/project:
composer.installed:
\- no_dev: true
\- require:
\- cmd: install\-composer
# Without composer installed in your PATH
# Note: composer.phar must be executable for state to work properly
/path/to/project:
composer.installed:
\- composer: /path/to/composer.phar
\- php: /usr/local/bin/php
\- no_dev: true
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.composer.installed(name, composer=None, php=None, runas=None, user=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, composer_home=\(aq/root\(aq)
Verify that composer has installed the latest packages give a
\fBcomposer.json\fP and \fBcomposer.lock\fP file in a directory.
.INDENT 7.0
.TP
.B dir
Directory location of the composer.json file.
.TP
.B composer
Location of the composer.phar file. If not set composer will
just execute "composer" as if it is installed globally.
(i.e. /path/to/composer.phar)
.TP
.B php
Location of the php executable to use with composer.
(i.e. /usr/bin/php)
.TP
.B runas
Which system user to run composer as.
.sp
Deprecated since version 2014.1.4.
.TP
.B user
Which system user to run composer as.
.sp
New in version 2014.1.4.
.TP
.B prefer_source
\-\-prefer\-source option of composer.
.TP
.B prefer_dist
\-\-prefer\-dist option of composer.
.TP
.B no_scripts
\-\-no\-scripts option of composer.
.TP
.B no_plugins
\-\-no\-plugins option of composer.
.TP
.B optimize
\-\-optimize\-autoloader option of composer. Recommended for production.
.TP
.B no_dev
\-\-no\-dev option for composer. Recommended for production.
.TP
.B quiet
\-\-quiet option for composer. Whether or not to return output from composer.
.TP
.B composer_home
$COMPOSER_HOME environment variable
.UNINDENT
.UNINDENT
.SS salt.states.cron
.SS Management of cron, the Unix command scheduler
.sp
Cron declarations require a number of parameters. The following are the
parameters used by Salt to define the various timing values for a cron job:
.INDENT 0.0
.IP \(bu 2
\fBminute\fP
.IP \(bu 2
\fBhour\fP
.IP \(bu 2
\fBdaymonth\fP
.IP \(bu 2
\fBmonth\fP
.IP \(bu 2
\fBdayweek\fP (0 to 6 are Sunday through Saturday, 7 can also be used for
Sunday)
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Any timing arguments not specified take a value of \fB*\fP\&. This means that
setting \fBhour\fP to \fB5\fP, while not defining the \fBminute\fP param, will
result in Salt adding a job that will execute every minute between 5 and 6
A.M.!
.sp
Additionally, the default user for these states is \fBroot\fP\&. Therefore, if
the cron job is for another user, it is necessary to specify that user with
the \fBuser\fP parameter.
.UNINDENT
.UNINDENT
.sp
A long time ago (before 2014.2), when making changes to an existing cron job,
the name declaration is the parameter used to uniquely identify the job,
so if an existing cron that looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
date > /tmp/crontest:
cron.present:
\- user: root
\- minute: 5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Is changed to this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
date > /tmp/crontest:
cron.present:
\- user: root
\- minute: 7
\- hour: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.sp
The current behavior is still relying on that mechanism, but you can also
specify an identifier to identify your crontabs:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
date > /tmp/crontest:
cron.present:
\- identifier: SUPERCRON
\- user: root
\- minute: 7
\- hour: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 2014.1.2.
.sp
And, some months later, you modify it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
superscript > /tmp/crontest:
cron.present:
\- identifier: SUPERCRON
\- user: root
\- minute: 3
\- hour: 4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 2014.1.2.
.sp
The old \fBdate > /tmp/crontest\fP will be replaced by
\fBsuperscript > /tmp/crontest\fP\&.
.sp
Additionally, Salt also supports running a cron every \fBx minutes\fP very similarly to the Unix
convention of using \fB*/5\fP to have a job run every five minutes. In Salt, this
looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
date > /tmp/crontest:
cron.present:
\- user: root
\- minute: \(aq*/5\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The job will now run every 5 minutes.
.sp
Additionally, the temporal parameters (minute, hour, etc.) can be randomized by
using \fBrandom\fP instead of using a specific value. For example, by using the
\fBrandom\fP keyword in the \fBminute\fP parameter of a cron state, the same cron
job can be pushed to hundreds or thousands of hosts, and they would each use a
randomly\-generated minute. This can be helpful when the cron job accesses a
network resource, and it is not desirable for all hosts to run the job
concurrently.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/path/to/cron/script:
cron.present:
\- user: root
\- minute: random
\- hour: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 0.16.0.
.sp
Since Salt assumes a value of \fB*\fP for unspecified temporal parameters, adding
a parameter to the state and setting it to \fBrandom\fP will change that value
from \fB*\fP to a randomized numeric value. However, if that field in the cron
entry on the minion already contains a numeric value, then using the \fBrandom\fP
keyword will not modify it.
.INDENT 0.0
.TP
.B salt.states.cron.absent(name, user=\(aqroot\(aq, identifier=None, **kwargs)
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 whose crontab needs to be modified, defaults to
the root user
.TP
.B identifier
Custom\-defined identifier for tracking the cron line for future crontab
edits. This defaults to the state id
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cron.env_absent(name, user=\(aqroot\(aq)
Verifies that the specified environment variable is absent from the crontab
for the specified user
.INDENT 7.0
.TP
.B name
The name of the environment variable to remove from the user crontab
.TP
.B user
The name of the user whose crontab needs to be modified, defaults to
the root user
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cron.env_present(name, value=None, user=\(aqroot\(aq)
Verifies that the specified environment variable is present in the crontab
for the specified user.
.INDENT 7.0
.TP
.B name
The name of the environment variable to set in the user crontab
.TP
.B user
The name of the user whose crontab needs to be modified, defaults to
the root user
.TP
.B value
The value to set for the given environment variable
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.cron.file(name, source_hash=\(aq\(aq, user=\(aqroot\(aq, template=None, context=None, replace=True, defaults=None, env=None, backup=\(aq\(aq, **kwargs)
Provides file.managed\-like functionality (templating, etc.) for a pre\-made
crontab file, to be assigned to a given user.
.INDENT 7.0
.TP
.B name
The source file to be used as the crontab. This source file can be
hosted on either the salt master server, or on an HTTP or FTP server.
For files hosted on the salt file server, if the file is located on
the master in the directory named spam, and is called eggs, the source
string is \fBsalt://spam/eggs\fP
.sp
If the file is hosted on a HTTP or FTP server then the source_hash
argument is also required
.TP
.B source_hash
This can be either a file which contains a source hash string for
the source, or a source hash string. The source hash string is the
hash algorithm followed by the hash of the file:
\fBmd5=e138491e9d5b97023cea823fe17bac22\fP
.TP
.B user
The user to whom the crontab should be assigned. This defaults to
root.
.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 context
Overrides default context variables passed to the template.
.TP
.B replace
If the crontab should be replaced, if False then this command will
be ignored if a crontab exists for the specified user. Default is True.
.TP
.B defaults
Default context passed to the template.
.TP
.B backup
Overrides the default backup mode for the user\(aqs crontab.
.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, comment=None, identifier=None)
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 whose 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 week section. Default is \fB*\fP
.TP
.B comment
User comment to be added on line previous the cron job
.TP
.B identifier
Custom\-defined identifier for tracking the cron line for future crontab
edits. This defaults to the state id
.UNINDENT
.UNINDENT
.SS salt.states.ddns
.SS Dynamic DNS updates
.sp
Ensure a DNS record is present or absent utilizing RFC 2136
type dynamic updates. Requires dnspython module.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
webserver:
ddns.present:
\- zone: example.com
\- ttl: 60
\- data: 111.222.333.444
\- nameserver: 123.234.345.456
\- keyfile: /srv/salt/tsig_key.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ddns.absent(name, zone, data=None, rdtype=None, **kwargs)
Ensures that the named DNS record is absent.
.INDENT 7.0
.TP
.B name
The host portion of the DNS record, e.g., \(aqwebserver\(aq
.TP
.B zone
The zone to check
.TP
.B data
Data for the DNS record. E.g., the IP address for an A record. If omitted,
all records matching name (and rdtype, if provided) will be purged.
.TP
.B rdtype
DNS resource type. If omitted, all types will be purged.
.TP
.B \fB**kwargs\fP
Additional arguments the ddns.delete function may need (e.g. nameserver, keyfile, keyname).
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ddns.present(name, zone, ttl, data, rdtype=\(aqA\(aq, **kwargs)
Ensures that the named DNS record is present with the given ttl.
.INDENT 7.0
.TP
.B name
The host portion of the DNS record, e.g., \(aqwebserver\(aq
.TP
.B zone
The zone to check/update
.TP
.B ttl
TTL for the record
.TP
.B data
Data for the DNS record. E.g., the IP address for an A record.
.TP
.B rdtype
DNS resource type. Default \(aqA\(aq.
.TP
.B \fB**kwargs\fP
Additional arguments the ddns.update function may need (e.g. nameserver, keyfile, keyname).
.UNINDENT
.UNINDENT
.SS salt.states.debconfmod
.SS Management of debconf selections
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
debconf\-utils package
.UNINDENT
.UNINDENT
.sp
The debconfmod state module manages the enforcement of debconf selections,
this state can set those selections prior to package installation.
.SS Available Functions
.sp
The debconfmod state has two functions, the \fBset\fP and \fBset_file\fP functions
.INDENT 0.0
.TP
.B set
Set debconf selections from the state itself
.TP
.B set_file
Set debconf selections from a file
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nullmailer\-debconf:
debconf.set:
\- name: nullmailer
\- data:
\(aqshared/mailname\(aq: {\(aqtype\(aq: \(aqstring\(aq, \(aqvalue\(aq: \(aqserver.domain.tld\(aq}
\(aqnullmailer/relayhost\(aq: {\(aqtype\(aq: \(aqstring\(aq, \(aqvalue\(aq: \(aqmail.domain.tld\(aq}
ferm\-debconf:
debconf.set:
\- name: ferm
\- data:
\(aqferm/enable\(aq: {\(aqtype\(aq: \(aqboolean\(aq, \(aqvalue\(aq: True}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Due to how PyYAML imports nested dicts (see \fBhere\fP), the values in the \fBdata\fP
dict must be indented four spaces instead of two.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.debconfmod.set(name, data)
Set debconf selections
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
<state_id>:
debconf.set:
\- name: <name>
\- data:
<question>: {\(aqtype\(aq: <type>, \(aqvalue\(aq: <value>}
<question>: {\(aqtype\(aq: <type>, \(aqvalue\(aq: <value>}
<state_id>:
debconf.set:
\- name: <name>
\- data:
<question>: {\(aqtype\(aq: <type>, \(aqvalue\(aq: <value>}
<question>: {\(aqtype\(aq: <type>, \(aqvalue\(aq: <value>}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name:
The package name to set answers for.
.TP
.B data:
A set of questions/answers for debconf. Note that everything under
this must be indented twice.
.TP
.B question:
The question the is being pre\-answered
.TP
.B type:
The type of question that is being asked (string, boolean, select, etc.)
.TP
.B value:
The answer to the question
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.debconfmod.set_file(name, source, **kwargs)
Set debconf selections from a file
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
<state_id>:
debconf.set_file:
\- source: salt://pathto/pkg.selections
<state_id>:
debconf.set_file:
\- source: salt://pathto/pkg.selections?saltenv=myenvironment
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B source:
The location of the file containing the package selections
.UNINDENT
.UNINDENT
.SS salt.states.disk
.sp
Disk monitoring state
.sp
Monitor the state of disk resources
.INDENT 0.0
.TP
.B salt.states.disk.status(name, maximum=None, minimum=None)
Return the current disk usage stats for the named mount point
.UNINDENT
.SS salt.states.dockerio
.SS Manage Docker containers
.sp
\fI\%Docker\fP
is a lightweight, portable, self\-sufficient software container
wrapper. The base supported wrapper type is
\fI\%LXC\fP,
\fI\%cgroups\fP, and the
\fI\%Linux Kernel\fP\&.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This state module is beta. The API is subject to change. No promise
as to performance or functionality is yet present.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This state module requires
\fI\%docker\-py\fP
which supports \fI\%Docker Remote API version 1.6\fP\&.
.UNINDENT
.UNINDENT
.SS Available Functions
.INDENT 0.0
.IP \(bu 2
built
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
corp/mysuperdocker_img:
docker.built:
\- path: /path/to/dir/container
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
pulled
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
ubuntu:
docker.pulled:
\- tag: latest
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
pushed
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
corp/mysuperdocker_img:
docker.pushed
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
installed
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
mysuperdocker\-container:
docker.installed:
\- name: mysuperdocker
\- hostname: superdocker
\- image: corp/mysuperdocker_img
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
running
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
my_service:
docker.running:
\- container: mysuperdocker
\- port_bindings:
"5000/tcp":
HostIp: ""
HostPort: "5000"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 2.0
.INDENT 3.5
The \fBport_bindings\fP argument above is a dictionary. Note the
double\-indentation, this is required for PyYAML to load the data
structure properly as a dictionary. More information can be found
\fIhere\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
absent
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
mys_old_uperdocker:
docker.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
run
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
/finish\-install.sh:
docker.run:
\- container: mysuperdocker
\- unless: grep \-q something /var/log/foo
\- docker_unless: grep \-q done /install_log
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The docker modules are named \fBdockerio\fP because
the name \(aqdocker\(aq would conflict with the underlying docker\-py library.
.sp
We should add magic to all methods to also match containers by name
now that the \(aqnaming link\(aq stuff has been merged in docker.
This applies for example to:
.INDENT 0.0
.IP \(bu 2
running
.IP \(bu 2
absent
.IP \(bu 2
run
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.absent(name)
Ensure that the container is absent; if not, it will
will be killed and destroyed. (\fIdocker inspect\fP)
.INDENT 7.0
.TP
.B name:
Either the container name or id
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.built(name, path=None, quiet=False, nocache=False, rm=True, force=False, timeout=None, *args, **kwargs)
Build a docker image from a path or URL to a dockerfile. (\fIdocker build\fP)
.INDENT 7.0
.TP
.B name
Name of the image
.TP
.B path
URL (e.g. \fIurl/branch/docker_dir/dockerfile\fP)
or filesystem path to the dockerfile
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.installed(name, image, command=None, hostname=None, user=None, detach=True, stdin_open=False, tty=False, mem_limit=0, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, *args, **kwargs)
Ensure that a container with the given name exists;
if not, build a new container from the specified image.
(\fIdocker run\fP)
.INDENT 7.0
.TP
.B name
Name for the container
.TP
.B image
Image from which to build this container
.TP
.B environment
.INDENT 7.0
.TP
.B Environment variables for the container, either
.INDENT 7.0
.IP \(bu 2
a mapping of key, values
.IP \(bu 2
a list of mappings of key, values
.UNINDENT
.UNINDENT
.TP
.B ports
.INDENT 7.0
.TP
.B List of ports definitions, either:
.INDENT 7.0
.IP \(bu 2
a port to map
.IP \(bu 2
a mapping of mapping portInHost : PortInContainer
.UNINDENT
.UNINDENT
.TP
.B volumes
List of volumes
.UNINDENT
.sp
For other parameters, see absolutely first the salt.modules.dockerio
execution module and the docker\-py python bindings for docker
documentation
<\fI\%https://github.com/dotcloud/docker\-py#api\fP>\(ga_ for
\fIdocker.create_container\fP\&.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This command does not verify that the named container
is running the specified image.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.mod_watch(name, sfun=None, *args, **kw)
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.present(name)
If a container with the given name is not present, this state will fail.
(\fIdocker inspect\fP)
.INDENT 7.0
.TP
.B name:
container id
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.pulled(name, tag=\(aqlatest\(aq, force=False, *args, **kwargs)
Pull an image from a docker registry. (\fIdocker pull\fP)
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
See first the documentation for \fIdocker login\fP, \fIdocker pull\fP,
\fIdocker push\fP,
and \fI\%docker.import_image\fP
(\fI\%docker import\fP).
NOTE that we added in SaltStack a way to authenticate yourself with the
Docker Hub Registry by supplying your credentials (username, email & password)
using pillars. For more information, see salt.modules.dockerio execution
module.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the image
.TP
.B tag
Tag of the image
.TP
.B force
Pull even if the image is already pulled
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.pushed(name, tag=\(aqlatest\(aq)
Push an image from a docker registry. (\fIdocker push\fP)
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
See first the documentation for \fIdocker login\fP, \fIdocker pull\fP,
\fIdocker push\fP,
and \fI\%docker.import_image\fP
(\fI\%docker import\fP).
NOTE that we added in SaltStack a way to authenticate yourself with the
Docker Hub Registry by supplying your credentials (username, email & password)
using pillars. For more information, see salt.modules.dockerio execution
module.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
Name of the image
.TP
.B tag
Tag of the image [Optional]
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.run(name, cid=None, hostname=None, onlyif=None, unless=None, docked_onlyif=None, docked_unless=None, *args, **kwargs)
Run a command in a specific container
.sp
You can match by either name or hostname
.INDENT 7.0
.TP
.B name
command to run in the container
.TP
.B cid
Container id
.TP
.B state_id
state_id
.TP
.B onlyif
Only execute cmd if statement on the host returns 0
.TP
.B unless
Do not execute cmd if statement on the host returns 0
.TP
.B docked_onlyif
Only execute cmd if statement in the container returns 0
.TP
.B docked_unless
Do not execute cmd if statement in the container returns 0
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.running(name, container=None, port_bindings=None, binds=None, publish_all_ports=False, links=None, lxc_conf=None, privileged=False, dns=None, volumes_from=None, network_mode=None, restart_policy=None, cap_add=None, cap_drop=None, check_is_running=True)
Ensure that a container is running. (\fIdocker inspect\fP)
.INDENT 7.0
.TP
.B name
name of the service
.TP
.B container
name of the container to start
.UNINDENT
.sp
publish_all_ports
.INDENT 7.0
.TP
.B links
Link several container together
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- links:
name_other_container: alias_for_other_container
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B port_bindings
.INDENT 7.0
.TP
.B List of ports to expose on host system
.INDENT 7.0
.IP \(bu 2
a mapping port\(aqs guest, hostname\(aqs host and port\(aqs host.
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- port_bindings:
"5000/tcp":
HostIp: ""
HostPort: "5000"
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B binds
List of volumes to mount (like \fB\-v\fP of \fBdocker run\fP command),
mapping host directory to container directory.
.sp
For read\-write mounting, use the short form:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- binds:
/var/log/service: /var/log/service
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or, to specify read\-only mounting, use the extended form:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- binds:
/home/user1:
bind: /mnt/vol2
ro: true
/var/www:
bind: /mnt/vol1
ro: false
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B dns
List of DNS servers.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- dns:
\- 127.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B volumes_from
List of container names to get volumes definition from
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- volumes_from:
\- name_other_container
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B network_mode
.INDENT 7.0
.IP \(bu 2
\(aqbridge\(aq: creates a new network stack for the container on the docker bridge
.IP \(bu 2
\(aqnone\(aq: no networking for this container
.IP \(bu 2
\(aqcontainer:[name|id]\(aq: reuses another container network stack)
.IP \(bu 2
\(aqhost\(aq: use the host network stack inside the container
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- network_mode: host
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B restart_policy
Restart policy to apply when a container exits (no, on\-failure[:max\-retry], always)
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- restart_policy:
MaximumRetryCount: 5
Name: on\-failure
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B cap_add
List of capabilities to add in a container.
.TP
.B cap_drop
List of capabilities to drop in a container.
.TP
.B check_is_running
Enable checking if a container should run or not.
Useful for data\-only containers that must be linked to another one.
e.g. nginx <\- static\-files
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.dockerio.script(*args, **kw)
Placeholder function for a cmd.script alike.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Not yet implemented.
Its implementation might be very similar from
\fI\%salt.states.dockerio.run\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.environ
.sp
Support for getting and setting the environment variables
of the current salt process.
.INDENT 0.0
.TP
.B salt.states.environ.setenv(name, value, false_unsets=False, clear_all=False, update_minion=False)
Set the salt process environment variables.
.INDENT 7.0
.TP
.B name
The environment key to set. Must be a string.
.TP
.B value
Either a string or dict. When string, it will be the value
set for the environment key of \(aqname\(aq above.
When a dict, each key/value pair represents an environment
variable to set.
.TP
.B false_unsets
If a key\(aqs value is False and false_unsets is True, then the
key will be removed from the salt processes environment dict
entirely. If a key\(aqs value is False and false_unsets is not
True, then the key\(aqs value will be set to an empty string.
Default: False
.TP
.B clear_all
USE WITH CAUTION! This option can unset environment variables
needed for salt to function properly.
If clear_all is True, then any environment variables not
defined in the environ dict will be deleted.
Default: False
.TP
.B update_minion
If True, apply these environ changes to the main salt\-minion
process. If False, the environ changes will only affect the
current salt subprocess.
Default: False
.UNINDENT
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
a_string_env:
environ.set:
\- name: foo
\- value: bar
\- update_minion: True
a_dict_env:
environ.set:
\- name: does_not_matter
\- value:
foo: bar
baz: quux
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.eselect
.SS Management of Gentoo configuration using eselect
.sp
A state module to manage Gentoo configuration via eselect
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
profile:
eselect.set:
target: hardened/linux/amd64
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.eselect.set_(name, target, parameter=None, module_parameter=None, action_parameter=None)
Verify that the given module is set to the given target
.INDENT 7.0
.TP
.B name
The name of the module
.TP
.B target
The target to be set for this module
.TP
.B module_parameter
additional params passed to the defined module
.TP
.B action_parameter
additional params passed to the defined action
.TP
.B parameter
additional params passed to the defined action
.sp
Deprecated since version Lithium.
.UNINDENT
.UNINDENT
.SS salt.states.event
.sp
Send events through Salt\(aqs event system during state runs
.INDENT 0.0
.TP
.B salt.states.event.send(name, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, **kwargs)
Send an event to the Salt Master
.sp
New in version 2014.7.0.
.sp
Accepts the same arguments as the \fBevent.send\fP execution module of the same name.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# ...snip bunch of states above
mycompany/mystaterun/status/update:
event.send:
\- data:
status: "Half\-way through the state run!"
# ...snip bunch of states below
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.event.wait(name, sfun=None)
Fire an event on the Salt master event bus if called from a watch statement
.sp
New in version 2014.7.0.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Stand up a new web server.
apache:
pkg:
\- installed
\- name: httpd
service:
\- running
\- enable: True
\- name: httpd
# Notify the load balancer to update the pool once Apache is running.
refresh_pool:
event:
\- wait
\- name: mycompany/loadbalancer/pool/update
\- data:
new_web_server_ip: {{ grains[\(aqipv4\(aq] | first() }}
\- watch:
\- pkg: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.file
.SS Operations on regular files, special files, directories, and symlinks
.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 \fI\%file.managed\fP state. This state downloads files from the salt
master and places them on the target system. Managed files can be rendered as a
jinja, mako, or wempy template, adding a dynamic component to file management.
An example of \fI\%file.managed\fP which makes use of
the jinja templating system would look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/http/conf/http.conf:
file.managed:
\- source: salt://apache/http.conf
\- user: root
\- group: root
\- mode: 644
\- template: jinja
\- defaults:
custom_var: "default value"
other_var: 123
{% if grains[\(aqos\(aq] == \(aqUbuntu\(aq %}
\- context:
custom_var: "override"
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is also possible to use the \fBpy renderer\fP as a
templating option. The template would be a python script which would need to
contain a function called \fBrun()\fP, which returns a string. The returned
string will be the contents of the managed file. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def run():
lines = (\(aqfoo\(aq, \(aqbar\(aq, \(aqbaz\(aq)
return \(aq\en\en\(aq.join(lines)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When using both the \fBdefaults\fP and \fBcontext\fP arguments, note the extra
indentation (four spaces instead of the normal two). This is due to an
idiosyncrasy of how PyYAML loads nested dictionaries, and is explained in
greater detail \fIhere\fP\&.
.UNINDENT
.UNINDENT
.sp
If using a template, any user\-defined template variables in the file defined in
\fBsource\fP must be passed in using the \fBdefaults\fP and/or \fBcontext\fP
arguments. The general best practice is to place default values in
\fBdefaults\fP, with conditional overrides going into \fBcontext\fP, as seen above.
.sp
The template will receive a variable \fBcustom_var\fP, which would be accessed in
the template using \fB{{ custom_var }}\fP\&. If the operating system is Ubuntu, the
value of the variable \fBcustom_var\fP would be \fIoverride\fP, otherwise it is the
default \fIdefault value\fP
.sp
The \fBsource\fP parameter can be specified as a list. If this is done, then the
first file to be matched will be the one that is used. This allows you to have
a default file on which to fall back if the desired file does not exist on the
salt fileserver. Here\(aqs an example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/foo.conf:
file.managed:
\- source:
\- salt://foo.conf.{{ grains[\(aqfqdn\(aq] }}
\- salt://foo.conf.fallback
\- user: foo
\- group: users
\- mode: 644
\- backup: minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Salt supports backing up managed files via the backup option. For more
details on this functionality please review the
\fBbackup_mode documentation\fP\&.
.UNINDENT
.UNINDENT
.sp
The \fBsource\fP parameter can also specify a file in another Salt environment.
In this example \fBfoo.conf\fP in the \fBdev\fP environment will be used instead.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/foo.conf:
file.managed:
\- source:
\- salt://foo.conf?saltenv=dev
\- user: foo
\- group: users
\- mode: \(aq0644\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
When using a mode that includes a leading zero you must wrap the
value in single quotes. If the value is not wrapped in quotes it
will be read by YAML as an integer and evaluated as an octal.
.UNINDENT
.UNINDENT
.sp
Special files can be managed via the \fBmknod\fP function. This function will
create and enforce the permissions on a special file. The function supports the
creation of character devices, block devices, and fifo pipes. The function will
create the directory structure up to the special file if it is needed on the
minion. The function will not overwrite or operate on (change major/minor
numbers) existing special files with the exception of user, group, and
permissions. In most cases the creation of some special files require root
permisisons on the minion. This would require that the minion to be run as the
root user. Here is an example of a character device:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/var/named/chroot/dev/random:
file.mknod:
\- ntype: c
\- major: 1
\- minor: 8
\- user: named
\- group: named
\- mode: 660
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here is an example of a block device:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/var/named/chroot/dev/loop0:
file.mknod:
\- ntype: b
\- major: 7
\- minor: 0
\- user: named
\- group: named
\- mode: 660
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here is an example of a fifo pipe:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/var/named/chroot/var/log/logfifo:
file.mknod:
\- ntype: p
\- user: named
\- group: named
\- mode: 660
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/srv/stuff/substuf:
file.directory:
\- user: fred
\- group: users
\- mode: 755
\- makedirs: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you need to enforce user and/or group ownership or permissions recursively
on the directory\(aqs contents, you can do so by adding a \fBrecurse\fP directive:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/srv/stuff/substuf:
file.directory:
\- user: fred
\- group: users
\- mode: 755
\- makedirs: True
\- recurse:
\- user
\- group
\- mode
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As a default, \fBmode\fP will resolve to \fBdir_mode\fP and \fBfile_mode\fP, to
specify both directory and file permissions, use this form:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/srv/stuff/substuf:
file.directory:
\- user: fred
\- group: users
\- file_mode: 744
\- dir_mode: 755
\- makedirs: True
\- recurse:
\- user
\- group
\- mode
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Symlinks can be easily created; the symlink function is very simple and only
takes a few arguments:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/grub.conf:
file.symlink:
\- target: /boot/grub/grub.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.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 state using \fBrecurse\fP
would look something like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/opt/code/flask:
file.recurse:
\- source: salt://code/flask
\- include_empty: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A more complex \fBrecurse\fP example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set site_user = \(aqtestuser\(aq %}
{% set site_name = \(aqtest_site\(aq %}
{% set project_name = \(aqtest_proj\(aq %}
{% set sites_dir = \(aqtest_dir\(aq %}
django\-project:
file.recurse:
\- name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}
\- user: {{ site_user }}
\- dir_mode: 2775
\- file_mode: \(aq0644\(aq
\- template: jinja
\- source: salt://project/templates_dir
\- include_empty: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.absent(name)
Make sure that the named file or directory is absent. If it exists, it will
be deleted. 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.accumulated(name, filename, text, **kwargs)
Prepare accumulator which can be used in template in file.managed state.
Accumulator dictionary becomes available in template. It can also be used
in file.blockreplace.
.INDENT 7.0
.TP
.B name
Accumulator name
.TP
.B filename
Filename which would receive this accumulator (see file.managed state
documentation about \fBname\fP)
.TP
.B text
String or list for adding in accumulator
.TP
.B require_in / watch_in
One of them required for sure we fill up accumulator before we manage
the file. Probably the same as filename
.UNINDENT
.sp
Example:
.sp
Given the following:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
animals_doing_things:
file.accumulated:
\- filename: /tmp/animal_file.txt
\- text: \(aq jumps over the lazy dog.\(aq
\- require_in:
\- file: animal_file
animal_file:
file.managed:
\- name: /tmp/animal_file.txt
\- source: salt://animal_file.txt
\- template: jinja
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
One might write a template for \fBanimal_file.txt\fP like the following:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
The quick brown fox{% for animal in accumulator[\(aqanimals_doing_things\(aq] %}{{ animal }}{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Collectively, the above states and template file will produce:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
The quick brown fox jumps over the lazy dog.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple accumulators can be "chained" together.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \(aqaccumulator\(aq data structure is a Python dictionary.
Do not expect any loop over the keys in a deterministic order!
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.append(name, text=None, makedirs=False, source=None, source_hash=None, template=\(aqjinja\(aq, sources=None, source_hashes=None, defaults=None, context=None)
Ensure that some text appears at the end of a file.
.sp
The text will not be appended if it already exists in the file.
A single string of text or a list of strings may be appended.
.INDENT 7.0
.TP
.B name
The location of the file to append to.
.TP
.B text
The text to be appended, which can be a single string or a list
of strings.
.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. Defaults to False.
.TP
.B source
A single source file to append. This source file can be hosted on either
the salt master server, or on an HTTP or FTP server. Both HTTPS and
HTTP are supported as well as downloading directly from Amazon S3
compatible URLs with both pre\-configured and automatic IAM credentials
(see s3.get state documentation). File retrieval from Openstack Swift
object storage is supported via swift://container/object_path URLs
(see swift.get documentation).
.sp
For files hosted on the salt file server, if the file is located on
the master in the directory named spam, and is called eggs, the source
string is salt://spam/eggs.
.sp
If the file is hosted on an HTTP or FTP server, the source_hash argument
is also required.
.TP
.B source_hash
.INDENT 7.0
.TP
.B This can be one of the following:
.INDENT 7.0
.IP 1. 3
a source hash string
.IP 2. 3
the URI of a file that contains source hash strings
.UNINDENT
.UNINDENT
.sp
The function accepts the first encountered long unbroken alphanumeric
string of correct length as a valid hash, in order from most secure to
least secure:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
Type Length
====== ======
sha512 128
sha384 96
sha256 64
sha224 56
sha1 40
md5 32
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The file can contain several checksums for several files. Each line
must contain both the file name and the hash. If no file name is
matched, the first hash encountered will be used, otherwise the most
secure hash with the correct source file name will be used.
.sp
Debian file type \fB*.dsc\fP is supported.
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27
sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf
ead48423703509d37c4a90e6a0d53e143b6fc268
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Known issues:
If the remote server URL has the hash file as an apparent
sub\-directory of the source file, the module will discover that it
has already cached a directory where a file should be cached. For
example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
tomdroid\-src\-0.7.3.tar.gz:
file.managed:
\- name: /tmp/tomdroid\-src\-0.7.3.tar.gz
\- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz
\- source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz/+md5
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B template
\fBjinja\fP
The named templating engine will be used to render the appended\-to
file. Defaults to jinja.
.TP
.B sources
A list of source files to append. If the files are hosted on an HTTP or
FTP server, the source_hashes argument is also required.
.TP
.B source_hashes
A list of source_hashes corresponding to the sources list specified in
the sources argument.
.TP
.B defaults
Default context passed to the template.
.TP
.B context
Overrides default context variables passed to the template.
.UNINDENT
.sp
Multi\-line example:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
Multiple lines of text:
.INDENT 7.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
Gather text from multiple template files:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/motd:
file:
\- append
\- template: jinja
\- sources:
\- salt://motd/devops\-messages.tmpl
\- salt://motd/hr\-messages.tmpl
\- salt://motd/general\-messages.tmpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.blockreplace(name, marker_start=\(aq#\-\- start managed zone \-\-\(aq, marker_end=\(aq#\-\- end managed zone \-\-\(aq, content=\(aq\(aq, append_if_not_found=False, prepend_if_not_found=False, backup=\(aq.bak\(aq, show_changes=True)
Maintain an edit in a file in a zone delimited by two line markers
.sp
New in version 2014.1.0.
.sp
A block of content delimited by comments can help you manage several lines
entries without worrying about old entries removal. This can help you
maintaining an un\-managed file containing manual edits.
Note: this function will store two copies of the file in\-memory
(the original version and the edited version) in order to detect changes
and only edit the targeted file if necessary.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- Filesystem path to the file to be edited
.IP \(bu 2
\fBmarker_start\fP \-\- The line content identifying a line as the start of
the content block. Note that the whole line containing this marker will
be considered, so whitespace or extra content before or after the
marker is included in final output
.IP \(bu 2
\fBmarker_end\fP \-\- The line content identifying a line as the end of
the content block. Note that the whole line containing this marker will
be considered, so whitespace or extra content before or after the
marker is included in final output.
Note: you can use file.accumulated and target this state. All
accumulated data dictionaries content will be added as new lines in the
content.
.IP \(bu 2
\fBcontent\fP \-\- The content to be used between the two lines identified by
marker_start and marker_stop.
.IP \(bu 2
\fBappend_if_not_found\fP \-\- False by default, if markers are not found and
set to True then the markers and content will be appended to the file
.IP \(bu 2
\fBprepend_if_not_found\fP \-\- False by default, if markers are not found and
set to True then the markers and content will be prepended to the file
.IP \(bu 2
\fBbackup\fP \-\- The file extension to use for a backup of the file if any
edit is made. Set to \fBFalse\fP to skip making a backup.
.IP \(bu 2
\fBdry_run\fP \-\- Don\(aqt make any edits to the file
.IP \(bu 2
\fBshow_changes\fP \-\- Output a unified diff of the old file and the new
file. If \fBFalse\fP return a boolean if any changes were made.
.UNINDENT
.TP
.B Return type
bool or str
.UNINDENT
.sp
Example of usage with an accumulator and with a variable:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{% set myvar = 42 %}
hosts\-config\-block\-{{ myvar }}:
file.blockreplace:
\- name: /etc/hosts
\- marker_start: "# START managed zone {{ myvar }} \-DO\-NOT\-EDIT\-"
\- marker_end: "# END managed zone {{ myvar }} \-\-"
\- content: \(aqFirst line of content\(aq
\- append_if_not_found: True
\- backup: \(aq.bak\(aq
\- show_changes: True
hosts\-config\-block\-{{ myvar }}\-accumulated1:
file.accumulated:
\- filename: /etc/hosts
\- name: my\-accumulator\-{{ myvar }}
\- text: "text 2"
\- require_in:
\- file: hosts\-config\-block\-{{ myvar }}
hosts\-config\-block\-{{ myvar }}\-accumulated2:
file.accumulated:
\- filename: /etc/hosts
\- name: my\-accumulator\-{{ myvar }}
\- text: |
text 3
text 4
\- require_in:
\- file: hosts\-config\-block\-{{ myvar }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will generate and maintain a block of content in \fB/etc/hosts\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# START managed zone 42 \-DO\-NOT\-EDIT\-
First line of content
text 2
text 3
text 4
# END managed zone 42 \-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.comment(name, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq)
Comment out specified lines in a file.
.INDENT 7.0
.TP
.B name
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)
Note that you _need_ the leading ^, otherwise each time you run
highstate, another comment char will be inserted.
.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
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/fstab:
file.comment:
\- regex: ^bind 127.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.copy(name, source, force=False, makedirs=False)
If the source file exists on the system, copy it to the named file. The
named file will not be overwritten if it already exists unless the force
option is set to True.
.INDENT 7.0
.TP
.B name
The location of the file to copy to
.TP
.B source
The location of the file to copy to the location specified with name
.TP
.B force
If the target location is present then the file will not be moved,
specify "force: True" to overwrite the target file
.TP
.B makedirs
If the target subdirectories don\(aqt exist create them
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.directory(name, user=None, group=None, recurse=None, dir_mode=None, file_mode=None, makedirs=False, clean=False, require=None, exclude_pat=None, follow_symlinks=False, force=False, backupname=None, **kwargs)
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. On Windows, this is ignored
.TP
.B recurse
Enforce user/group ownership and mode of directory recursively. Accepts
a list of strings representing what you would like to recurse. If
\(aqmode\(aq is defined, will recurse on both \(aqfile_mode\(aq and \(aqdir_mode\(aq if
they are defined.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/var/log/httpd:
file.directory:
\- user: root
\- group: root
\- dir_mode: 755
\- file_mode: 644
\- recurse:
\- user
\- group
\- mode
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B dir_mode / mode
The permissions mode to set any directories created. Not supported on
Windows
.TP
.B file_mode
The permissions mode to set any files created if \(aqmode\(aq is run in
\(aqrecurse\(aq. This defaults to dir_mode. Not supported on Windows
.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.
.TP
.B require
Require other resources such as packages or files
.TP
.B exclude_pat
When \(aqclean\(aq is set to True, exclude this pattern from removal list
and preserve in the destination.
.TP
.B follow_symlinks
False
If the desired path is a symlink (or \fBrecurse\fP is defined and a
symlink is encountered while recursing), follow it and check the
permissions of the directory/file to which the symlink points.
.sp
New in version 2014.1.4.
.TP
.B force
If the name of the directory exists and is not a directory and
force is set to False, the state will fail. If force is set to
True, the file in the way of the directory will be deleted to
make room for the directory, unless backupname is set,
then it will be renamed.
.sp
New in version 2014.7.0.
.TP
.B backupname
If the name of the directory exists and is not a directory, it will be
renamed to the backupname. If the backupname already
exists and force is False, the state will fail. Otherwise, the
backupname will be removed first.
.sp
New in version 2014.7.0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.exists(name)
Verify that the named file or directory is present or exists.
Ensures pre\-requisites outside of Salt\(aqs purview
(e.g., keytabs, private keys, etc.) have been previously satisfied before
deployment.
.INDENT 7.0
.TP
.B name
Absolute path which must exist
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.managed(name, source=None, source_hash=\(aq\(aq, user=None, group=None, mode=None, template=None, makedirs=False, dir_mode=None, context=None, replace=True, defaults=None, env=None, backup=\(aq\(aq, show_diff=True, create=True, contents=None, contents_pillar=None, contents_grains=None, contents_newline=True, follow_symlinks=True, check_cmd=None, **kwargs)
Manage a given file, this function allows for a file to be downloaded from
the salt master and potentially run through a templating system.
.INDENT 7.0
.TP
.B name
The location of the file to manage
.TP
.B source
The source file to download to the minion, this source file can be
hosted on either the salt master server, or on an HTTP or FTP server.
Both HTTPS and HTTP are supported as well as downloading directly
from Amazon S3 compatible URLs with both pre\-configured and automatic
IAM credentials. (see s3.get state documentation)
File retrieval from Openstack Swift object storage is supported via
swift://container/object_path URLs, see swift.get documentation.
For files hosted on the salt file server, if the file is located on
the master in the directory named spam, and is called eggs, the source
string is salt://spam/eggs. If source is left blank or None
(use ~ in YAML), the file will be created as an empty file and
the content will not be managed
.sp
If the file is hosted on a HTTP or FTP server then the source_hash
argument is also required
.sp
A list of sources can also be passed in to provide a default source and
a set of fallbacks. The first source in the list that is found to exist
will be used and subsequent entries in the list will be ignored.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
file_override_example:
file.managed:
\- source:
\- salt://file_that_does_not_exist
\- salt://file_that_exists
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B source_hash
.INDENT 7.0
.TP
.B This can be one of the following:
.INDENT 7.0
.IP 1. 3
a source hash string
.IP 2. 3
the URI of a file that contains source hash strings
.UNINDENT
.UNINDENT
.sp
The function accepts the first encountered long unbroken alphanumeric
string of correct length as a valid hash, in order from most secure to
least secure:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
Type Length
====== ======
sha512 128
sha384 96
sha256 64
sha224 56
sha1 40
md5 32
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The file can contain several checksums for several files. Each line
must contain both the file name and the hash. If no file name is
matched, the first hash encountered will be used, otherwise the most
secure hash with the correct source file name will be used.
.sp
Debian file type \fB*.dsc\fP is supported.
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27
sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf
ead48423703509d37c4a90e6a0d53e143b6fc268
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Known issues:
If the remote server URL has the hash file as an apparent
sub\-directory of the source file, the module will discover that it
has already cached a directory where a file should be cached. For
example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
tomdroid\-src\-0.7.3.tar.gz:
file.managed:
\- name: /tmp/tomdroid\-src\-0.7.3.tar.gz
\- source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz
\- source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid\-src\-0.7.3.tar.gz/+md5
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.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 On Windows, this is ignored
.TP
.B mode
The permissions to set on this file, aka 644, 0775, 4664. Not supported
on Windows
.TP
.B template
If this setting is applied then the named templating engine will be
used to render the downloaded file, currently jinja, mako, and wempy
are supported
.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 dir_mode
If directories are to be created, passing this option specifies the
permissions for those directories. If this is not set, directories
will be assigned permissions from the \(aqmode\(aq argument.
.TP
.B replace
If this file should be replaced. If false, this command will
not overwrite file contents but will enforce permissions if the file
exists already. Default is True.
.TP
.B context
Overrides default context variables passed to the template.
.TP
.B defaults
Default context passed to the template.
.TP
.B backup
Overrides the default backup mode for this specific file.
.TP
.B show_diff
If set to False, the diff will not be shown.
.TP
.B create
Default is True, if create is set to False then the file will only be
managed if the file already exists on the system.
.TP
.B contents
Default is None. If specified, will use the given string as the
contents of the file. Should not be used in conjunction with a source
file of any kind. Ignores hashes and does not use a templating engine.
.TP
.B contents_pillar
New in version 0.17.0.
.sp
Operates like \fBcontents\fP, but draws from a value stored in pillar,
using the pillar path syntax used in \fBpillar.get\fP\&. This is useful when the pillar value
contains newlines, as referencing a pillar variable using a jinja/mako
template can result in YAML formatting issues due to the newlines
causing indentation mismatches.
.sp
For example, the following could be used to deploy an SSH private key:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/home/deployer/.ssh/id_rsa:
file.managed:
\- user: deployer
\- group: deployer
\- mode: 600
\- contents_pillar: userdata:deployer:id_rsa
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would populate \fB/home/deployer/.ssh/id_rsa\fP with the contents of
\fBpillar[\(aquserdata\(aq][\(aqdeployer\(aq][\(aqid_rsa\(aq]\fP\&. An example of this pillar
setup would be like so:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
userdata:
deployer:
id_rsa: |
\-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-
MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY
U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy
B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+
GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI
\-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The private key above is shortened to keep the example brief, but
shows how to do multiline string in YAML. The key is followed by a
pipe character, and the mutliline string is indented two more
spaces.
.UNINDENT
.UNINDENT
.TP
.B contents_grains
New in version 2014.7.0.
.sp
Same as contents_pillar, but with grains
.TP
.B contents_newline
New in version 2014.7.0.
.sp
When using contents, contents_pillar, or contents_grains, this option
ensures the file will have a newline at the end.
When loading some data this newline is better left off. Setting
contents_newline to False will omit this final newline.
.TP
.B follow_symlinks
True
New in version 2014.7.0.
.sp
If the desired path is a symlink follow it and make changes to the
file to which the symlink points.
.TP
.B check_cmd
New in version 2014.7.0.
.sp
The specified command will be run with the managed file as an argument.
If the command exits with a nonzero exit code, the command will not be
run.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.missing(name)
Verify that the named file or directory is missing, this returns True only
if the named file is missing but does not remove the file if it is present.
.INDENT 7.0
.TP
.B name
Absolute path which must NOT exist
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode=\(aq0600\(aq)
Create a special file similar to the \(aqnix mknod command. The supported
device types are \fBp\fP (fifo pipe), \fBc\fP (character device), and \fBb\fP
(block device). Provide the major and minor numbers when specifying a
character device or block device. A fifo pipe does not require this
information. The command will create the necessary dirs if needed. If a
file of the same name not of the same type/major/minor exists, it will not
be overwritten or unlinked (deleted). This is logically in place as a
safety measure because you can really shoot yourself in the foot here and
it is the behavior of \(aqnix \fBmknod\fP\&. It is also important to note that not
just anyone can create special devices. Usually this is only done as root.
If the state is executed as none other than root on a minion, you may
receive a permission error.
.INDENT 7.0
.TP
.B name
name of the file
.TP
.B ntype
node type \(aqp\(aq (fifo pipe), \(aqc\(aq (character device), or \(aqb\(aq
(block device)
.TP
.B major
major number of the device
does not apply to a fifo pipe
.TP
.B minor
minor number of the device
does not apply to a fifo pipe
.TP
.B user
owning user of the device/pipe
.TP
.B group
owning group of the device/pipe
.TP
.B mode
permissions on the device/pipe
.UNINDENT
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/dev/chr:
file.mknod:
\- ntype: c
\- major: 180
\- minor: 31
\- user: root
\- group: root
\- mode: 660
/dev/blk:
file.mknod:
\- ntype: b
\- major: 8
\- minor: 999
\- user: root
\- group: root
\- mode: 660
/dev/fifo:
file.mknod:
\- ntype: p
\- user: root
\- group: root
\- mode: 660
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 0.17.0.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.mod_run_check_cmd(cmd, filename, **check_cmd_opts)
Execute the check_cmd logic
Return a result dict if:
* check_cmd succeeded (check_cmd == 0)
else return True
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.patch(name, source=None, hash=None, options=\(aq\(aq, dry_run_first=True, env=None, **kwargs)
Apply a patch to a file. Note: a suitable \fBpatch\fP executable must be
available on the minion when using this state function.
.INDENT 7.0
.TP
.B name
The file to with the patch will be applied.
.TP
.B source
The source patch to download to the minion, this source file must be
hosted on the salt master server. If the file is located in the
directory named spam, and is called eggs, the source string is
salt://spam/eggs. A source is required.
.TP
.B hash
Hash of the patched file. If the hash of the target file matches this
value then the patch is assumed to have been applied. The hash string
is the hash algorithm followed by the hash of the file:
md5=e138491e9d5b97023cea823fe17bac22
.TP
.B options
Extra options to pass to patch.
.TP
.B dry_run_first
\fBTrue\fP
Run patch with \fB\-\-dry\-run\fP first to check if it will apply cleanly.
.TP
.B env
Specify the environment from which to retrieve the patch file indicated
by the \fBsource\fP parameter. If not provided, this defaults to the
environment from which the state is being executed.
.UNINDENT
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Equivalent to \(ga\(gapatch \-\-forward /opt/file.txt file.patch\(ga\(ga
/opt/file.txt:
file.patch:
\- source: salt://file.patch
\- hash: md5=e138491e9d5b97023cea823fe17bac22
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.prepend(name, text=None, makedirs=False, source=None, source_hash=None, template=\(aqjinja\(aq, sources=None, source_hashes=None, defaults=None, context=None)
Ensure that some text appears at the beginning of a file
.sp
The text will not be prepended 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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/motd:
file.prepend:
\- text: |
Thou hadst better eat salt with the Philosophers of Greece,
than sugar with the Courtiers of Italy.
\- Benjamin Franklin
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple lines of text:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/motd:
file.prepend:
\- 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
.UNINDENT
.UNINDENT
.sp
Gather text from multiple template files:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/motd:
file:
\- prepend
\- template: jinja
\- sources:
\- salt://motd/devops\-messages.tmpl
\- salt://motd/hr\-messages.tmpl
\- salt://motd/general\-messages.tmpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 2014.7.0.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.recurse(name, source, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, sym_mode=None, template=None, context=None, defaults=None, env=None, include_empty=False, backup=\(aq\(aq, include_pat=None, exclude_pat=None, maxdepth=None, keep_symlinks=False, force_symlinks=False, **kwargs)
Recurse through a subdirectory on the master and copy said subdirectory
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.
.TP
.B require
Require other resources such as packages or files
.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. On Windows, this is ignored
.TP
.B dir_mode
The permissions mode to set on any directories created. Not supported on
Windows
.TP
.B file_mode
The permissions mode to set on any files created. Not supported on
Windows
.TP
.B sym_mode
The permissions mode to set on any symlink created. Not supported on
Windows
.TP
.B template
If this setting is applied then the named templating engine will be
used to render the downloaded file. Supported templates are:
\fIjinja\fP, \fImako\fP and \fIwempy\fP\&.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The template option is required when recursively applying templates.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B context
Overrides default context variables passed to the template.
.TP
.B defaults
Default context passed to the template.
.TP
.B include_empty
Set this to True if empty directories should also be created
(default is False)
.TP
.B include_pat
When copying, include only this pattern from the source. Default
is glob match; if prefixed with \(aqE@\(aq, then regexp match.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- include_pat: hello* :: glob matches \(aqhello01\(aq, \(aqhello02\(aq
... but not \(aqotherhello\(aq
\- include_pat: E@hello :: regexp matches \(aqotherhello\(aq,
\(aqhello01\(aq ...
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B exclude_pat
Exclude this pattern from the source when copying. If both
\fIinclude_pat\fP and \fIexclude_pat\fP are supplied, then it will apply
conditions cumulatively. i.e. first select based on include_pat, and
then within that result apply exclude_pat.
.sp
Also, when \(aqclean=True\(aq, exclude this pattern from the removal
list and preserve in the destination.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- exclude_pat: APPDATA* :: glob matches APPDATA.01,
APPDATA.02,.. for exclusion
\- exclude_pat: E@(APPDATA)|(TEMPDATA) :: regexp matches APPDATA
or TEMPDATA for exclusion
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B maxdepth
When copying, only copy paths which are of depth \fImaxdepth\fP from the
source path.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- maxdepth: 0 :: Only include files located in the source
directory
\- maxdepth: 1 :: Only include files located in the source
or immediate subdirectories
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B keep_symlinks
Keep symlinks when copying from the source. This option will cause
the copy operation to terminate at the symlink. If desire behavior
similar to rsync, then set this to True.
.TP
.B force_symlinks
Force symlink creation. This option will force the symlink creation.
If a file or directory is obstructing symlink creation it will be
recursively removed so that symlink creation can proceed. This
option is usually not needed except in special circumstances.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.rename(name, source, force=False, makedirs=False)
If the source file exists on the system, rename it to the named file. The
named file will not be overwritten if it already exists unless the force
option is set to True.
.INDENT 7.0
.TP
.B name
The location of the file to rename to
.TP
.B source
The location of the file to move to the location specified with name
.TP
.B force
If the target location is present then the file will not be moved,
specify "force: True" to overwrite the target file
.TP
.B makedirs
If the target subdirectories don\(aqt exist create them
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.replace(name, pattern, repl, count=0, flags=0, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, backup=\(aq.bak\(aq, show_changes=True)
Maintain an edit in a file
.sp
New in version 0.17.0.
.sp
Params are identical to the remote execution function \fBfile.replace\fP\&.
.sp
For complex regex patterns it can be useful to avoid the need for complex
quoting and escape sequences by making use of YAML\(aqs multiline string
syntax.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
complex_search_and_replace:
file.replace:
# <...snip...>
\- pattern: |
CentOS \e(2.6.32[^\en]+\en\es+root[^\en]+\en\e)+
.ft P
.fi
.UNINDENT
.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, negate_match=False)
Deprecated since version 0.17.0: Use the \fI\%file.replace\fP state instead.
.sp
Maintain a simple edit to a file
.sp
The file will be searched for the \fBbefore\fP pattern before making the
edit. In general the \fBlimit\fP pattern should be as specific as possible
and \fBbefore\fP and \fBafter\fP should contain the minimal text to be changed.
.INDENT 7.0
.TP
.B before
A pattern that should exist in the file before the edit.
.TP
.B after
A pattern that should exist in the file after the edit.
.TP
.B limit
An optional second pattern that can limit the scope of the before
pattern.
.TP
.B backup
\(aq.bak\(aq
The extension for the backed\-up version of the file before the edit. If
no backups is desired, pass in the empty string: \(aq\(aq
.TP
.B options
\fB\-r \-e\fP
Any options to pass to the \fBsed\fP command. \fB\-r\fP uses extended
regular expression syntax and \fB\-e\fP denotes that what follows is an
expression that sed will execute.
.TP
.B flags
\fBg\fP
Any flags to append to the sed expression. \fBg\fP specifies the edit
should be made globally (and not stop after the first replacement).
.TP
.B negate_match
False
Negate the search command (\fB!\fP)
.sp
New in version 0.17.0.
.UNINDENT
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# Disable the epel repo by default
/etc/yum.repos.d/epel.repo:
file.sed:
\- before: 1
\- after: 0
\- limit: ^enabled=
# Remove ldap from nsswitch
/etc/nsswitch.conf:
file.sed:
\- before: \(aqldap\(aq
\- after: \(aq\(aq
\- limit: \(aq^passwd:\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 0.9.5.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.serialize(name, dataset, user=None, group=None, mode=None, env=None, backup=\(aq\(aq, makedirs=False, show_diff=True, create=True, merge_if_exists=False, **kwargs)
Serializes dataset and store it into managed file. Useful for sharing
simple configuration files.
.INDENT 7.0
.TP
.B name
The location of the file to create
.TP
.B dataset
the dataset that will be serialized
.TP
.B formatter
Write the data as this format. Supported output formats:
.INDENT 7.0
.IP \(bu 2
JSON
.IP \(bu 2
YAML
.IP \(bu 2
Python (via pprint.pformat)
.UNINDENT
.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 file, aka 644, 0775, 4664
.TP
.B backup
Overrides the default backup mode for this specific file.
.TP
.B makedirs
Create parent directories for destination file.
.sp
New in version 2014.1.3.
.TP
.B show_diff
If set to False, the diff will not be shown.
.TP
.B create
Default is True, if create is set to False then the file will only be
managed if the file already exists on the system.
.TP
.B merge_if_exists
Default is False, if merge_if_exists is True then the existing file will
be parsed and the dataset passed in will be merged with the existing
content
.sp
New in version 2014.7.0.
.UNINDENT
.sp
For example, this state:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/dummy/package.json:
file.serialize:
\- dataset:
name: naive
description: A package using naive versioning
author: A confused individual <iam@confused.com>
dependencies:
express: >= 1.2.0
optimist: >= 0.1.0
engine: node 0.4.1
\- formatter: json
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will manage the file \fB/etc/dummy/package.json\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
{
"author": "A confused individual <iam@confused.com>",
"dependencies": {
"express": ">= 1.2.0",
"optimist": ">= 0.1.0"
},
"description": "A package using naive versioning",
"engine": "node 0.4.1",
"name": "naive"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.symlink(name, target, force=False, backupname=None, makedirs=False, user=None, group=None, mode=None, **kwargs)
Create a symlink
.sp
If the file already exists and is a symlink pointing to any location other
than the specified target, the symlink will be replaced. If the symlink is
a regular file or directory then the state will return False. If the
regular file or directory is desired to be replaced with a symlink pass
force: True, if it is to be renamed, pass a backupname.
.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 name of the symlink exists and is not a symlink and
force is set to False, the state will fail. If force is set to
True, the file or directory in the way of the symlink file
will be deleted to make room for the symlink, unless
backupname is set, when it will be renamed
.TP
.B backupname
If the name of the symlink exists and is not a symlink, it will be
renamed to the backupname. If the backupname already
exists and force is False, the state will fail. Otherwise, the
backupname will be removed first.
.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
.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. On Windows, this is ignored
.TP
.B mode
The permissions to set on this file, aka 644, 0775, 4664. Not supported
on Windows
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.file.touch(name, atime=None, mtime=None, makedirs=False)
Replicate the \(aqnix "touch" command to create a new empty
file or update the atime and mtime of an existing file.
.sp
Note that if you just want to create a file and don\(aqt care about atime or
mtime, you should use \fBfile.managed\fP instead, as it is more
feature\-complete. (Just leave out the \fBsource\fP/\fBtemplate\fP/\fBcontents\fP
arguments, and it will just create the file and/or check its permissions,
without messing with contents)
.INDENT 7.0
.TP
.B name
name of the file
.TP
.B atime
atime of the file
.TP
.B mtime
mtime of the file
.TP
.B makedirs
whether we should create the parent directory/directories in order to
touch the file
.UNINDENT
.sp
Usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/var/log/httpd/logrotate.empty:
file.touch
.ft P
.fi
.UNINDENT
.UNINDENT
.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)
Uncomment specified commented lines in a file
.INDENT 7.0
.TP
.B name
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()). The regex will be searched for
from the beginning of the line, ignoring leading spaces (we prepend
\(aq^[ t]*\(aq)
.TP
.B char
\fB#\fP
The character to remove in order to uncomment a line
.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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/adduser.conf:
file.uncomment:
\- regex: EXTRA_GROUPS
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 0.9.5.
.UNINDENT
.SS salt.states.gem
.SS Installation of Ruby modules packaged as gems
.sp
A state module to manage rubygems. Gems can be set up to be installed
or removed. This module will use RVM or rbenv if they are installed. In that case,
you can specify what ruby version and gemset to target.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
addressable:
gem.installed:
\- user: rvm
\- ruby: jruby@jgemset
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.gem.installed(name, ruby=None, runas=None, user=None, version=None, rdoc=False, ri=False, proxy=None)
Make sure that a gem is installed.
.INDENT 7.0
.TP
.B name
The name of the gem to install
.TP
.B ruby: None
For RVM or rbenv installations: the ruby version and gemset to target.
.TP
.B runas: None
The user under which to run the \fBgem\fP command
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user under which to run the \fBgem\fP command
.sp
New in version 0.17.0.
.TP
.B version
None
Specify the version to install for the gem.
Doesn\(aqt play nice with multiple gems at once
.TP
.B rdoc
False
Generate RDoc documentation for the gem(s).
.TP
.B ri
False
Generate RI documentation for the gem(s).
.TP
.B proxy
None
Use the specified HTTP proxy server for all outgoing traffic.
Format: \fI\%http://hostname[:port\fP]
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.gem.removed(name, ruby=None, runas=None, user=None)
Make sure that a gem is not installed.
.INDENT 7.0
.TP
.B name
The name of the gem to uninstall
.TP
.B ruby: None
For RVM or rbenv installations: the ruby version and gemset to target.
.TP
.B runas: None
The user under which to run the \fBgem\fP command
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user under which to run the \fBgem\fP command
.sp
New in version 0.17.0.
.UNINDENT
.UNINDENT
.SS salt.states.git
.SS Interaction with Git repositories
.sp
Important: Before using git over ssh, make sure your remote host fingerprint
exists in "~/.ssh/known_hosts" file. To avoid requiring password
authentication, it is also possible to pass private keys to use explicitly.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
https://github.com/saltstack/salt.git:
git.latest:
\- rev: develop
\- target: /tmp/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.git.config(name, value, repo=None, user=None, is_global=False)
New in version 2014.7.0.
.sp
Manage a git config setting for a user or repository
.INDENT 7.0
.TP
.B name
Name of the git config value to set
.TP
.B value
Value to set
.TP
.B repo
None
An optional location of a git repository for local operations
.TP
.B user
None
Optional name of a user as whom \fIgit config\fP will be run
.TP
.B is_global
False
Whether or not to pass the \fI\-\-global\fP option to \fIgit config\fP
.UNINDENT
.sp
Local config example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mylocalrepo:
git.config:
\- name: user.email
\- value: fester@bestertester.net
\- repo: file://my/path/to/repo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Global config example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mylocalrepo:
git.config:
\- name: user.name
\- value: Esther Bestertester
\- user: ebestertester
\- is_global: True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.git.latest(name, rev=None, target=None, runas=None, user=None, force=None, force_checkout=False, force_reset=False, submodules=False, mirror=False, bare=False, remote_name=\(aqorigin\(aq, always_fetch=False, identity=None, onlyif=False, unless=False)
Make sure the repository is cloned to the given directory and is up to date
.INDENT 7.0
.TP
.B name
Address of the remote repository as passed to "git clone"
.TP
.B rev
The remote branch, tag, or revision ID to checkout after
clone / before update
.TP
.B target
Name of the target directory where repository is about to be cloned
.TP
.B runas
Name of the user performing repository management operations
.sp
Deprecated since version 0.17.0.
.TP
.B user
Name of the user performing repository management operations
.sp
New in version 0.17.0.
.TP
.B force
Force git to clone into pre\-existing directories (deletes contents)
.TP
.B force_checkout
Force a checkout even if there might be overwritten changes
(Default: False)
.TP
.B submodules
Update submodules on clone or branch change (Default: False)
.TP
.B mirror
True if the repository is to be a mirror of the remote repository.
This implies bare, and thus is incompatible with rev.
.TP
.B bare
True if the repository is to be a bare clone of the remote repository.
This is incompatible with rev, as nothing will be checked out.
.TP
.B remote_name
defines a different remote name.
For the first clone the given name is set to the default remote,
else it is just a additional remote. (Default: \(aqorigin\(aq)
.TP
.B always_fetch
If a tag or branch name is used as the rev a fetch will not occur
until the tag or branch name changes. Setting this to true will force
a fetch to occur. Only applies when rev is set. (Default: False)
.TP
.B identity
A path to a private key to use over SSH
.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
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Clashing ID declarations can be avoided when including different
branches from the same git repository in the same sls file by using the
\fBname\fP declaration. The example below checks out the \fBgh\-pages\fP
and \fBgh\-pages\-prod\fP branches from the same repository into separate
directories. The example also sets up the \fBssh_known_hosts\fP ssh key
required to perform the git checkout.
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
gitlab.example.com:
ssh_known_hosts:
\- present
\- user: root
\- enc: ecdsa
\- fingerprint: 4e:94:b0:54:c1:5b:29:a2:70:0e:e1:a3:51:ee:ee:e3
git\-website\-staging:
git.latest:
\- name: git@gitlab.example.com:user/website.git
\- rev: gh\-pages
\- target: /usr/share/nginx/staging
\- identity: /root/.ssh/website_id_rsa
\- require:
\- pkg: git
\- ssh_known_hosts: gitlab.example.com
git\-website\-prod:
git.latest:
\- name: git@gitlab.example.com:user/website.git
\- rev: gh\-pages\-prod
\- target: /usr/share/nginx/prod
\- identity: /root/.ssh/website_id_rsa
\- require:
\- pkg: git
\- ssh_known_hosts: gitlab.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.git.mod_run_check(cmd_kwargs, onlyif, unless)
Execute the onlyif and unless logic.
Return a result dict if:
* onlyif failed (onlyif != 0)
* unless succeeded (unless == 0)
else return True
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.git.present(name, bare=True, runas=None, user=None, force=False)
Make sure the repository is present in the given directory
.INDENT 7.0
.TP
.B name
Name of the directory where the repository is about to be created
.TP
.B bare
Create a bare repository (Default: True)
.TP
.B runas
Name of the user performing repository management operations
.sp
Deprecated since version 0.17.0.
.TP
.B user
Name of the user performing repository management operations
.sp
New in version 0.17.0.
.TP
.B force
Force\-create a new repository into an pre\-existing non\-git directory
(deletes contents)
.UNINDENT
.UNINDENT
.SS salt.states.glusterfs
.sp
Manage glusterfs pool.
.INDENT 0.0
.TP
.B salt.states.glusterfs.created(name, bricks, stripe=False, replica=False, device_vg=False, transport=\(aqtcp\(aq, start=False)
Check if volume already exists
.INDENT 7.0
.TP
.B name
name of the volume
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
myvolume:
glusterfs.created:
\- bricks:
\- host1:/srv/gluster/drive1
\- host2:/srv/gluster/drive2
Replicated Volume:
glusterfs.created:
\- name: volume2
\- bricks:
\- host1:/srv/gluster/drive2
\- host2:/srv/gluster/drive3
\- replica: 2
\- start: True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.glusterfs.peered(name)
Check if node is peered.
.INDENT 7.0
.TP
.B name
The remote host with which to peer.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
peer\-cluster:
glusterfs.peered:
\- name: two
peer\-clusters:
glusterfs.peered:
\- names:
\- one
\- two
\- three
\- four
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.glusterfs.started(name)
Check if volume has been started
.INDENT 7.0
.TP
.B name
name of the volume
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mycluster:
glusterfs.started: []
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.gnomedesktop
.SS Configuration of the GNOME desktop
.sp
Control the GNOME settings
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
localdesktop_wm_prefs:
gnomedesktop.wm_preferences:
\- user: username
\- audible_bell: false
\- action_double_click_titlebar: \(aqtoggle\-maximize\(aq
\- visual_bell: true
\- num_workspaces: 6
localdesktop_lockdown:
gnomedesktop.desktop_lockdown:
\- user: username
\- disable_user_switching: true
localdesktop_interface:
gnomedesktop.desktop_interface:
\- user: username
\- clock_show_date: true
\- clock_format: 12h
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.gnomedesktop.desktop_interface(name, user=None, automatic_mnemonics=None, buttons_have_icons=None, can_change_accels=None, clock_format=None, clock_show_date=None, clock_show_seconds=None, cursor_blink=None, cursor_blink_time=None, cursor_blink_timeout=None, cursor_size=None, cursor_theme=None, document_font_name=None, enable_animations=None, font_name=None, gtk_color_palette=None, gtk_color_scheme=None, gtk_im_module=None, gtk_im_preedit_style=None, gtk_im_status_style=None, gtk_key_theme=None, gtk_theme=None, gtk_timeout_initial=None, gtk_timeout_repeat=None, icon_theme=None, menubar_accel=None, menubar_detachable=None, menus_have_icons=None, menus_have_tearoff=None, monospace_font_name=None, show_input_method_menu=None, show_unicode_menu=None, text_scaling_factor=None, toolbar_detachable=None, toolbar_icons_size=None, toolbar_style=None, toolkit_accessibility=None, **kwargs)
desktop_interface: sets values in the org.gnome.desktop.interface schema
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.gnomedesktop.desktop_lockdown(name, user=None, disable_application_handlers=None, disable_command_line=None, disable_lock_screen=None, disable_log_out=None, disable_print_setup=None, disable_printing=None, disable_save_to_disk=None, disable_user_switching=None, user_administration_disabled=None, **kwargs)
desktop_lockdown: sets values in the org.gnome.desktop.lockdown schema
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.gnomedesktop.wm_preferences(name, user=None, action_double_click_titlebar=None, action_middle_click_titlebar=None, action_right_click_titlebar=None, application_based=None, audible_bell=None, auto_raise=None, auto_raise_delay=None, button_layout=None, disable_workarounds=None, focus_mode=None, focus_new_windows=None, mouse_button_modifier=None, num_workspaces=None, raise_on_click=None, resize_with_right_button=None, theme=None, titlebar_font=None, titlebar_uses_system_font=None, visual_bell=None, visual_bell_type=None, workspace_names=None, **kwargs)
wm_preferences: sets values in the org.gnome.desktop.wm.preferences schema
.UNINDENT
.SS salt.states.grains
.SS Manage grains on the minion
.sp
This state allows for grains to be set.
Grains set or altered this way are stored in the \(aqgrains\(aq
file on the minions, by default at: /etc/salt/grains
.sp
Note: This does NOT override any grains set in the minion file.
.INDENT 0.0
.TP
.B salt.states.grains.absent(name, destructive=False)
New in version 2014.7.0.
.sp
Delete a grain from the grains config file
.INDENT 7.0
.TP
.B name
The grain name
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBdestructive\fP \-\- If destructive is True, delete the entire grain. If
destructive is False, set the grain\(aqs value to None. Defaults to False.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
grain_name:
grains.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.grains.append(name, value, convert=False)
New in version 2014.7.0.
.sp
Append a value to a list in the grains config file
.INDENT 7.0
.TP
.B name
The grain name
.TP
.B value
The value to append
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBconvert\fP \-\- If convert is True, convert non\-list contents into a list.
If convert is False and the grain contains non\-list contents, an error
is given. Defaults to False.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
grain_name:
grains.append:
\- value: to_be_appended
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.grains.list_absent(name, value)
Delete a value from a grain formed as a list
.INDENT 7.0
.TP
.B name
The grain name
.TP
.B value
The value to delete from the grain list
.UNINDENT
.sp
The grain should be \fI\%list type\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
roles:
grains.list_absent:
\- value: db
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.grains.list_present(name, value)
New in version 2014.1.0.
.sp
Ensure the value is present in the list type grain
.INDENT 7.0
.TP
.B name
The grain name
.TP
.B value
The value is present in the list type grain
.UNINDENT
.sp
The grain should be \fI\%list type\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
roles:
grains.list_present:
\- value: web
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.grains.present(name, value)
Ensure that a grain is set
.INDENT 7.0
.TP
.B name
The grain name
.TP
.B value
The value to set on the grain
.UNINDENT
.sp
If the grain with the given name exists, its value is updated to the new value.
If the grain does not yet exist, a new grain is set to the given value.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
cheese:
grains.present:
\- value: edam
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.group
.SS Management of user groups
.sp
The group module is used to create and manage unix group settings, groups
can be either present or absent:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cheese:
group.present:
\- gid: 7648
\- system: True
\- addusers:
\- user1
\- users2
\- delusers:
\- foo
cheese:
group.present:
\- gid: 7648
\- system: True
\- members:
\- foo
\- bar
\- user1
\- user2
.ft P
.fi
.UNINDENT
.UNINDENT
.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, system=False, addusers=None, delusers=None, members=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
.TP
.B system
Whether or not the named group is a system group. This is essentially
the \(aq\-r\(aq option of \(aqgroupadd\(aq.
.TP
.B addusers
List of additional users to be added as a group members.
.TP
.B delusers
Ensure these user are removed from the group membership.
.TP
.B members
Replace existing group members with a list of new members.
.TP
.B Note: Options \(aqmembers\(aq and \(aqaddusers/delusers\(aq are mutually exclusive and
can not be used together.
.UNINDENT
.UNINDENT
.SS salt.states.hg
.SS Interaction with Mercurial repositories
.sp
Before using hg over ssh, make sure the remote host fingerprint already exists
in ~/.ssh/known_hosts, and the remote host has this host\(aqs public key.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
https://bitbucket.org/example_user/example_repo:
hg.latest:
\- rev: tip
\- target: /tmp/example_repo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.hg.latest(name, rev=None, target=None, clean=False, runas=None, user=None, force=False, opts=False)
Make sure the repository is cloned to the given directory and is up to date
.INDENT 7.0
.TP
.B name
Address of the remote repository as passed to "hg clone"
.TP
.B rev
The remote branch, tag, or revision hash to clone/pull
.TP
.B target
Name of the target directory where repository is about to be cloned
.TP
.B clean
Force a clean update with \-C (Default: False)
.TP
.B runas
Name of the user performing repository management operations
.sp
Deprecated since version 0.17.0.
.TP
.B user
Name of the user performing repository management operations
.TP
.B force
Force hg to clone into pre\-existing directories (deletes contents)
.TP
.B opts
Include additional arguments and options to the hg command line
.UNINDENT
.UNINDENT
.SS salt.states.host
.SS Management of addresses and names in hosts file
.sp
The \fB/etc/hosts\fP file can be managed to contain definitions for specific hosts:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master:
host.present:
\- ip: 192.168.0.42
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or using the \fBnames\fP directive, you can put several names for the same IP.
(Do not try one name with space\-separated values).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server1:
host.present:
\- ip: 192.168.0.42
\- names:
\- server1
\- florida
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Changing the \fBnames\fP in \fBhost.present\fP does not cause an
update to remove the old entry.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server1:
host.present:
\- ip:
\- 192.168.0.42
\- 192.168.0.43
\- 192.168.0.44
\- names:
\- server1
.ft P
.fi
.UNINDENT
.UNINDENT
.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(s) 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(s) to apply to the host
.UNINDENT
.UNINDENT
.SS salt.states.htpasswd
.sp
Support for htpasswd module
.sp
New in version 2014.7.0.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
username:
webutil.user_exists:
\- password: secr3t
\- htpasswd_file: /etc/nginx/htpasswd
\- options: d
\- force: true
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.htpasswd.user_exists(name, password=None, htpasswd_file=None, options=\(aq\(aq, force=False, **kwargs)
Make sure the user is inside the \fB/etc/nginx/htpasswd\fP
.INDENT 7.0
.TP
.B \fBname\fP
username
.TP
.B \fBpassword\fP
password of the user
.TP
.B \fBhtpasswd_file\fP
path to the file that htpasswd will handle
.TP
.B \fBoptions\fP
see \fBsalt.module.htpasswd.useradd\fP
.TP
.B \fBforce\fP
touch the file even if user already created
.UNINDENT
.UNINDENT
.SS salt.states.incron
.SS Management of incron, the inotify cron
.sp
The incron state module allows for user incrontabs to be cleanly managed.
.sp
Incron declarations require a number of parameters. The parameters needed
to be declared: \fBpath\fP, \fBmask\fP, and \fBcmd\fP\&. The \fBuser\fP whose incrontab is to be edited
also needs to be defined.
.sp
When making changes to an existing incron job, the \fBpath\fP declaration is the unique
factor, so if an existing cron that looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Watch for modifications in /home/user:
incron.present:
\- user: root
\- path: /home/user
\- mask:
\- IN_MODIFY
\- cmd: \(aqecho "$$ $@"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Is changed to this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Watch for modifications and access in /home/user:
incron.present:
\- user: root
\- path: /home/user
\- mask:
\- IN_MODIFY
\- IN_ACCESS
\- cmd: \(aqecho "$$ $@"\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.sp
New in version 0.17.0.
.INDENT 0.0
.TP
.B salt.states.incron.absent(name, path, mask, cmd, user=\(aqroot\(aq)
Verifies that the specified incron job is absent for the specified user; only
the name is matched when removing a incron job.
.INDENT 7.0
.TP
.B name
Unique comment describing the entry
.TP
.B path
The path that should be watched
.TP
.B user
The name of the user who\(aqs crontab needs to be modified, defaults to
the root user
.TP
.B mask
The mask of events that should be monitored for
.TP
.B cmd
The cmd that should be executed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.incron.present(name, path, mask, cmd, user=\(aqroot\(aq)
Verifies that the specified incron job is present for the specified user.
For more advanced information about what exactly can be set in the cron
timing parameters, check your incron system\(aqs documentation. Most Unix\-like
systems\(aq incron documentation can be found via the incrontab man page:
\fBman 5 incrontab\fP\&.
.INDENT 7.0
.TP
.B name
Unique comment describing the entry
.TP
.B path
The path that should be watched
.TP
.B user
The name of the user who\(aqs crontab needs to be modified, defaults to
the root user
.TP
.B mask
The mask of events that should be monitored for
.TP
.B cmd
The cmd that should be executed
.UNINDENT
.UNINDENT
.SS salt.states.influxdb_database
.SS Management of InfluxDB databases
.sp
(compatible with InfluxDB version 0.5+)
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B salt.states.influxdb_database.absent(name, user=None, password=None, host=None, port=None)
Ensure that the named database is absent
.INDENT 7.0
.TP
.B name
The name of the database to remove
.TP
.B user
The user to connect as (must be able to remove the database)
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.influxdb_database.present(name, user=None, password=None, host=None, port=None)
Ensure that the named database is present
.INDENT 7.0
.TP
.B name
The name of the database to create
.TP
.B user
The user to connect as (must be able to remove the database)
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.UNINDENT
.SS salt.states.influxdb_user
.SS Management of InfluxDB users
.sp
(compatible with InfluxDB version 0.5+)
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B salt.states.influxdb_user.absent(name, database=None, user=None, password=None, host=None, port=None)
Ensure that the named cluster admin or database user is absent.
.INDENT 7.0
.TP
.B name
The name of the user to remove
.TP
.B database
The database to remove the user from
.TP
.B user
The user to connect as (must be able to remove the user)
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.influxdb_user.present(name, passwd, database=None, user=None, password=None, host=None, port=None)
Ensure that the cluster admin or database user is present.
.INDENT 7.0
.TP
.B name
The name of the user to manage
.TP
.B passwd
The password of the user
.TP
.B database
The database to create the user in
.TP
.B user
The user to connect as (must be able to create the user)
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.UNINDENT
.SS salt.states.ini_manage
.SS Manage ini files
.INDENT 0.0
.TP
.B maintainer
<\fI\%akilesh1597@gmail.com\fP>
.TP
.B maturity
new
.TP
.B depends
re
.TP
.B platform
all
.UNINDENT
.sp
use section as DEFAULT_IMPLICIT if your ini file does not have any section
for example /etc/sysctl.conf
.INDENT 0.0
.TP
.B salt.states.ini_manage.options_absent(name, sections=None)
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/home/saltminion/api\-paste.ini:
ini_manage:
\- options_absent
\- sections:
test:
\- testkey
\- secondoption
test1:
\- testkey1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
options present in file and not specified in sections
dict will be untouched
.sp
changes dict will contain the list of changes made
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ini_manage.options_present(name, sections=None)
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/home/saltminion/api\-paste.ini:
ini_manage:
\- options_present
\- sections:
test:
testkey: \(aqtestval\(aq
secondoption: \(aqsecondvalue\(aq
test1:
testkey1: \(aqtestval121\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
options present in file and not specified in sections
dict will be untouched
.sp
changes dict will contain the list of changes made
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ini_manage.sections_absent(name, sections=None)
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/home/saltminion/api\-paste.ini:
ini_manage:
\- sections_absent
\- sections:
\- test
\- test1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
options present in file and not specified in sections will be deleted
changes dict will contain the sections that changed
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ini_manage.sections_present(name, sections=None)
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/home/saltminion/api\-paste.ini:
ini_manage:
\- sections_present
\- sections:
test:
testkey: testval
secondoption: secondvalue
test1:
testkey1: \(aqtestval121\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
options present in file and not specified in sections will be deleted
changes dict will contain the sections that changed
.UNINDENT
.SS salt.states.ipset
.SS Management of ipsets
.sp
This is an ipset\-specific module designed to manage IPSets for use
in IPTables Firewalls.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
setname:
ipset.set_present:
\- set_type: bitmap:ip
\- range: 192.168.0.0/16
\- comment: True
setname:
ipset.set_absent:
\- set_type: bitmap:ip
\- range: 192.168.0.0/16
\- comment: True
setname_entries:
ipset.present:
\- set_name: setname
\- entry: 192.168.0.3
\- comment: Hello
\- require:
\- ipset: baz
setname_entries:
ipset.present:
\- set_name: setname
\- entry:
\- 192.168.0.3
\- 192.168.1.3
\- comment: Hello
\- require:
\- ipset: baz
setname_entries:
ipset.absent:
\- set_name: setname
\- entry:
\- 192.168.0.3
\- 192.168.1.3
\- comment: Hello
\- require:
\- ipset: baz
setname:
ipset.flush:
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ipset.absent(name, entry=None, entries=None, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Remove a entry or entries from a chain
.INDENT 7.0
.TP
.B name
A user\-defined name to call this entry by in another part of a state or
formula. This should not be an actual entry.
.TP
.B family
Network family, ipv4 or ipv6.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ipset.flush(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Flush current ipset set
.INDENT 7.0
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ipset.present(name, entry=None, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Append a entry to a set
.INDENT 7.0
.TP
.B name
A user\-defined name to call this entry by in another part of a state or
formula. This should not be an actual entry.
.TP
.B entry
A single entry to add to a set or a list of entries to add to a set
.TP
.B family
Network family, ipv4 or ipv6.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ipset.set_absent(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Verify the set is absent.
.INDENT 7.0
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ipset.set_present(name, set_type, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Verify the chain is exist.
.INDENT 7.0
.TP
.B name
A user\-defined set name.
.TP
.B set_type
The type for the set
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.SS salt.states.iptables
.SS Management of iptables
.sp
This is an iptables\-specific module designed to manage Linux firewalls. It is
expected that this state module, and other system\-specific firewall states, may
at some point be deprecated in favor of a more generic \fIfirewall\fP state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
iptables.append:
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.append:
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match:
\- state
\- comment
\- comment: "Allow HTTP"
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.append:
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match:
\- state
\- comment
\- comment: "Allow HTTP"
\- connstate: NEW
\- source: \(aq127.0.0.1\(aq
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
\&.. Invert Rule
httpd:
iptables.append:
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match:
\- state
\- comment
\- comment: "Allow HTTP"
\- connstate: NEW
\- source: \(aq! 127.0.0.1\(aq
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.append:
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match:
\- state
\- comment
\- comment: "Allow HTTP"
\- connstate: NEW
\- source: \(aqnot 127.0.0.1\(aq
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.append:
\- table: filter
\- family: ipv6
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.append:
\- table: filter
\- family: ipv4
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dports:
\- 80
\- 443
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.insert:
\- position: 1
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.insert:
\- position: 1
\- table: filter
\- family: ipv6
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.delete:
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.delete:
\- position: 1
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
iptables.delete:
\- table: filter
\- family: ipv6
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.iptables.append(name, family=\(aqipv4\(aq, **kwargs)
New in version 0.17.0.
.sp
Append a rule to a chain
.INDENT 7.0
.TP
.B name
A user\-defined name to call this rule by in another part of a state or
formula. This should not be an actual rule.
.TP
.B family
Network family, ipv4 or ipv6.
.UNINDENT
.sp
All other arguments are passed in with the same name as the long option
that would normally be used for iptables, with one exception: \fB\-\-state\fP is
specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with
\fIctstate\fP).
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.iptables.chain_absent(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq)
New in version 2014.1.0.
.sp
Verify the chain is absent.
.INDENT 7.0
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.iptables.chain_present(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq)
New in version 2014.1.0.
.sp
Verify the chain is exist.
.INDENT 7.0
.TP
.B name
A user\-defined chain name.
.TP
.B table
The table to own the chain.
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.iptables.delete(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.1.0.
.sp
Delete a rule to a chain
.INDENT 7.0
.TP
.B name
A user\-defined name to call this rule by in another part of a state or
formula. This should not be an actual rule.
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.sp
All other arguments are passed in with the same name as the long option
that would normally be used for iptables, with one exception: \fB\-\-state\fP is
specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with
\fIctstate\fP).
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.iptables.flush(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.1.0.
.sp
Flush current iptables state
.INDENT 7.0
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.iptables.insert(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.1.0.
.sp
Insert a rule into a chain
.INDENT 7.0
.TP
.B name
A user\-defined name to call this rule by in another part of a state or
formula. This should not be an actual rule.
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.sp
All other arguments are passed in with the same name as the long option
that would normally be used for iptables, with one exception: \fB\-\-state\fP is
specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with
\fIctstate\fP).
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.iptables.set_policy(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.1.0.
.sp
Sets the default policy for iptables firewall tables
.INDENT 7.0
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.SS salt.states.keyboard
.SS Management of keyboard layouts
.sp
The keyboard layout can be managed for the system:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
us:
keyboard.system
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or it can be managed for XOrg:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
us:
keyboard.xorg
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keyboard.system(name)
Set the keyboard layout for the system
.INDENT 7.0
.TP
.B name
The keyboard layout to use
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keyboard.xorg(name)
Set the keyboard layout for XOrg
.INDENT 7.0
.TP
.B layout
The keyboard layout to use
.UNINDENT
.UNINDENT
.SS salt.states.keystone
.SS Management of Keystone users
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
keystoneclient Python module
.UNINDENT
.TP
.B configuration
See \fBsalt.modules.keystone\fP for setup instructions.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Keystone tenants:
keystone.tenant_present:
\- names:
\- admin
\- demo
\- service
Keystone roles:
keystone.role_present:
\- names:
\- admin
\- Member
admin:
keystone.user_present:
\- password: R00T_4CC3SS
\- email: admin@domain.com
\- roles:
admin: # tenants
\- admin # roles
service:
\- admin
\- Member
\- require:
\- keystone: Keystone tenants
\- keystone: Keystone roles
nova:
keystone.user_present:
\- password: \(aq$up3rn0v4\(aq
\- email: nova@domain.com
\- tenant: service
\- roles:
service:
\- admin
\- require:
\- keystone: Keystone tenants
\- keystone: Keystone roles
demo:
keystone.user_present:
\- password: \(aqd3m0n$trati0n\(aq
\- email: demo@domain.com
\- tenant: demo
\- roles:
demo:
\- Member
\- require:
\- keystone: Keystone tenants
\- keystone: Keystone roles
nova service:
keystone.service_present:
\- name: nova
\- service_type: compute
\- description: OpenStack Compute Service
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.endpoint_absent(name, profile=None, **connection_args)
Ensure that the endpoint for a service doesn\(aqt exist in Keystone catalog
.INDENT 7.0
.TP
.B name
The name of the service whose endpoints should not exist
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.endpoint_present(name, publicurl=None, internalurl=None, adminurl=None, region=\(aqRegionOne\(aq, profile=None, **connection_args)
Ensure the specified endpoints exists for service
.INDENT 7.0
.TP
.B name
The Service name
.TP
.B public url
The public url of service endpoint
.TP
.B internal url
The internal url of service endpoint
.TP
.B admin url
The admin url of the service endpoint
.TP
.B region
The region of the endpoint
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.role_absent(name, profile=None, **connection_args)
Ensure that the keystone role is absent.
.INDENT 7.0
.TP
.B name
The name of the role that should not exist
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.role_present(name, profile=None, **connection_args)
\(aq
Ensures that the keystone role exists
.INDENT 7.0
.TP
.B name
The name of the role that should be present
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.service_absent(name, profile=None, **connection_args)
Ensure that the service doesn\(aqt exist in Keystone catalog
.INDENT 7.0
.TP
.B name
The name of the service that should not exist
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.service_present(name, service_type, description=None, profile=None, **connection_args)
Ensure service present in Keystone catalog
.INDENT 7.0
.TP
.B name
The name of the service
.TP
.B service_type
The type of Openstack Service
.TP
.B description (optional)
Description of the service
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.tenant_absent(name, profile=None, **connection_args)
Ensure that the keystone tenant is absent.
.INDENT 7.0
.TP
.B name
The name of the tenant that should not exist
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.tenant_present(name, description=None, enabled=True, profile=None, **connection_args)
Ensures that the keystone tenant exists
.INDENT 7.0
.TP
.B name
The name of the tenant to manage
.TP
.B description
The description to use for this tenant
.TP
.B enabled
Availability state for this tenant
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.user_absent(name, profile=None, **connection_args)
Ensure that the keystone user is absent.
.INDENT 7.0
.TP
.B name
The name of the user that should not exist
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.keystone.user_present(name, password, email, tenant=None, enabled=True, roles=None, profile=None, **connection_args)
Ensure that the keystone user is present with the specified properties.
.INDENT 7.0
.TP
.B name
The name of the user to manage
.TP
.B password
The password to use for this user
.TP
.B email
The email address for this user
.TP
.B tenant
The tenant for this user
.TP
.B enabled
Availability state for this user
.TP
.B roles
The roles the user should have under tenants
.UNINDENT
.UNINDENT
.SS salt.states.kmod
.SS Loading and unloading of kernel modules
.sp
The Kernel modules on a system can be managed cleanly with the kmod state
module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kvm_amd:
kmod.present
pcspkr:
kmod.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.kmod.absent(name, persist=False, comment=True)
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
.TP
.B persist
Delete module from \fB/etc/modules\fP
.TP
.B comment
Don\(aqt remove module from \fB/etc/modules\fP, only comment it
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.kmod.present(name, persist=False)
Ensure that the specified kernel module is loaded
.INDENT 7.0
.TP
.B name
The name of the kernel module to verify is loaded
.TP
.B persist
Also add module to \fB/etc/modules\fP
.UNINDENT
.UNINDENT
.SS salt.states.layman
.SS Management of Gentoo Overlays using layman
.sp
A state module to manage Gentoo package overlays via layman
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sunrise:
layman.present
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.layman.absent(name)
Verify that the overlay is absent
.INDENT 7.0
.TP
.B name
The name of the overlay to delete
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.layman.present(name)
Verify that the overlay is present
.INDENT 7.0
.TP
.B name
The name of the overlay to add
.UNINDENT
.UNINDENT
.SS salt.states.libvirt
.SS Manage libvirt certificates
.sp
This state uses the external pillar in the master to call
for the generation and signing of certificates for systems running libvirt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
libvirt_keys:
libvirt.keys
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.libvirt.keys(name, basepath=\(aq/etc/pki\(aq)
Manage libvirt keys.
.INDENT 7.0
.TP
.B name
The name variable used to track the execution
.TP
.B basepath
Defaults to \fB/etc/pki\fP, this is the root location used for libvirt
keys on the hypervisor
.UNINDENT
.UNINDENT
.SS salt.states.locale
.SS Management of languages/locales
.sp
The locale can be managed for the system:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
en_US.UTF\-8:
locale.system
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.locale.present(name)
Generate a locale if it is not present
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B name
The name of the locale to be present
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.locale.system(name)
Set the locale for the system
.INDENT 7.0
.TP
.B name
The name of the locale to use
.UNINDENT
.UNINDENT
.SS salt.states.lvm
.SS Management of Linux logical volumes
.sp
A state module to manage LVMs
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/dev/sda:
lvm.pv_present
my_vg:
lvm.vg_present:
\- devices: /dev/sda
lvroot:
lvm.lv_present:
\- vgname: my_vg
\- size: 10G
\- stripes: 5
\- stripesize: 8K
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvm.lv_absent(name, vgname=None)
Remove a given existing logical volume from a named existing volume group
.INDENT 7.0
.TP
.B name
The logical volume to remove
.TP
.B vgname
The volume group name
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvm.lv_present(name, vgname=None, size=None, extents=None, snapshot=None, pv=\(aq\(aq, **kwargs)
Create a new logical volume
.INDENT 7.0
.TP
.B name
The name of the logical volume
.TP
.B vgname
The volume group name for this logical volume
.TP
.B size
The initial size of the logical volume
.TP
.B extents
The number of logical extents to allocate
.TP
.B snapshot
The name of the snapshot
.TP
.B pv
The physical volume to use
.TP
.B kwargs
Any supported options to lvcreate. See
\fBlinux_lvm\fP for more details.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvm.pv_absent(name)
Ensure that a Physical Device is not being used by lvm
.INDENT 7.0
.TP
.B name
The device name to initialize.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvm.pv_present(name, **kwargs)
Set a physical device to be used as an LVM physical volume
.INDENT 7.0
.TP
.B name
The device name to initialize.
.TP
.B kwargs
Any supported options to pvcreate. See
\fBlinux_lvm\fP for more details.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvm.vg_absent(name)
Remove an LVM volume group
.INDENT 7.0
.TP
.B name
The volume group to remove
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvm.vg_present(name, devices=None, **kwargs)
Create an LVM volume group
.INDENT 7.0
.TP
.B name
The volume group name to create
.TP
.B devices
A list of devices that will be added to the volume group
.TP
.B kwargs
Any supported options to vgcreate. See
\fBlinux_lvm\fP for more details.
.UNINDENT
.UNINDENT
.SS salt.states.lvs_server
.SS Management of LVS (Linux Virtual Server) Real Server
.INDENT 0.0
.TP
.B salt.states.lvs_server.absent(name, protocol=None, service_address=None, server_address=None)
Ensure the LVS Real Server in specified service is absent.
.INDENT 7.0
.TP
.B name
The name of the LVS server.
.TP
.B protocol
The service protocol(only support \fBtcp\fP, \fBudp\fP and \fBfwmark\fP service).
.TP
.B service_address
The LVS service address.
.TP
.B server_address
The LVS real server address.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvs_server.present(name, protocol=None, service_address=None, server_address=None, packet_forward_method=\(aqdr\(aq, weight=1)
Ensure that the named service is present.
.INDENT 7.0
.TP
.B name
The LVS server name
.TP
.B protocol
The service protocol
.TP
.B service_address
The LVS service address
.TP
.B server_address
The real server address.
.TP
.B packet_forward_method
The LVS packet forwarding method(\fBdr\fP for direct routing, \fBtunnel\fP for tunneling, \fBnat\fP for network access translation).
.TP
.B weight
The capacity of a server relative to the others in the pool.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
lvsrs:
lvs_server.present:
\- protocol: tcp
\- service_address: 1.1.1.1:80
\- server_address: 192.168.0.11:8080
\- packet_forward_method: dr
\- weight: 10
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.lvs_service
.SS Management of LVS (Linux Virtual Server) Service
.INDENT 0.0
.TP
.B salt.states.lvs_service.absent(name, protocol=None, service_address=None)
Ensure the LVS service is absent.
.INDENT 7.0
.TP
.B name
The name of the LVS service
.TP
.B protocol
The service protocol
.TP
.B service_address
The LVS service address
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lvs_service.present(name, protocol=None, service_address=None, scheduler=\(aqwlc\(aq)
Ensure that the named service is present.
.INDENT 7.0
.TP
.B name
The LVS service name
.TP
.B protocol
The service protocol
.TP
.B service_address
The LVS service address
.TP
.B scheduler
Algorithm for allocating TCP connections and UDP datagrams to real servers.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
lvstest:
lvs_service.present:
\- service_address: 1.1.1.1:80
\- protocol: tcp
\- scheduler: rr
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.lxc
.SS lxc / Spin up and control LXC containers
.INDENT 0.0
.TP
.B salt.states.lxc.absent(name)
Destroy a container
.INDENT 7.0
.TP
.B name
id of the container to destroy
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
destroyer:
lxc.absent:
\- name: my_instance_name2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lxc.cloned(name, orig, snapshot=True, size=None, vgname=None, profile=None)
Clone a container
.INDENT 7.0
.TP
.B name
id of the container to clone to
.TP
.B orig
id of the container to clone from
.TP
.B snapshot
do we use snapshots
.TP
.B size
Which size
.TP
.B vgname
If LVM, which volume group
.TP
.B profile
pillar lxc profile
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
myclone:
lxc.cloned:
\- name: my_instance_name2
\- orig: ubuntu
\- vgname: lxc
\- snapshot: true
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lxc.created(name, template=\(aqubuntu\(aq, profile=None, fstype=None, size=None, backing=None, vgname=None, lvname=None)
Create a container using a template
.INDENT 7.0
.TP
.B name
id of the container to act on
.TP
.B template
template to create from
.TP
.B profile
pillar lxc profile
.TP
.B fstype
fstype to use
.TP
.B size
Which size
.TP
.B backing
Which backing
.INDENT 7.0
.TP
.B None
Filesystem
.TP
.B lvm
lv
.TP
.B brtfs
brtfs
.UNINDENT
.TP
.B vgname
If LVM, which volume group
.TP
.B lvname
If LVM, which lv
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mycreation:
lxc.created:
\- name: my_instance_name2
\- backing: lvm
\- size: 1G
\- template: ubuntu
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lxc.edited_conf(name, lxc_conf=None, lxc_conf_unset=None)
Edit LXC configuration options
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
setconf:
lxc.edited_conf:
\- name: ubuntu
\- lxc_conf:
\- network.ipv4.ip: 10.0.3.6
\- lxc_conf_unset:
\- lxc.utsname
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lxc.set_pass(name, password=None, user=None, users=None)
Set the password of system users inside containers
.INDENT 7.0
.TP
.B name
id of the container to act on
.TP
.B user
user to set password
.TP
.B users
users to set password to
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
setpass:
lxc.stopped:
\- name: my_instance_name2
\- password: s3cret
\- user: foo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
setpass2:
lxc.stopped:
\- name: my_instance_name2
\- password: s3cret
\- users:
\- foo
\- bar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lxc.started(name, restart=False)
Start a container
.INDENT 7.0
.TP
.B name
id of the container to start
.TP
.B force
force reboot
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
destroyer:
lxc.started:
\- name: my_instance_name2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.lxc.stopped(name)
Stop a container
.INDENT 7.0
.TP
.B name
id of the container to stop
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
sleepingcontainer:
lxc.stopped:
\- name: my_instance_name2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.makeconf
.SS Management of Gentoo make.conf
.sp
A state module to manage Gentoo\(aqs \fBmake.conf\fP file
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
makeopts:
makeconf.present:
\- value: \(aq\-j3\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.makeconf.absent(name)
Verify that the variable is not in the \fBmake.conf\fP\&.
.INDENT 7.0
.TP
.B name
The variable name. This will automatically be converted to upper
case since variables in \fBmake.conf\fP are in upper case
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.makeconf.present(name, value=None, contains=None, excludes=None)
Verify that the variable is in the \fBmake.conf\fP and has the provided
settings. If value is set, contains and excludes will be ignored.
.INDENT 7.0
.TP
.B name
The variable name. This will automatically be converted to upper
case since variables in \fBmake.conf\fP are in upper case
.TP
.B value
Enforce that the value of the variable is set to the provided value
.TP
.B contains
Enforce that the value of the variable contains the provided value
.TP
.B excludes
Enforce that the value of the variable does not contain the provided
value.
.UNINDENT
.UNINDENT
.SS salt.states.mdadm
.SS Managing software RAID with mdadm
.sp
A state module for creating or destroying software RAID devices.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/dev/md0:
raid.present:
\- opts: level=1 chunk=256 raid\-devices=2 /dev/xvdd /dev/xvde
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mdadm.absent(name)
Verify that the raid is absent
.INDENT 7.0
.TP
.B name
The name of raid device to be destroyed
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/dev/md0:
raid:
\- absent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mdadm.present(name, level, devices, **kwargs)
Verify that the raid is present
.sp
Changed in version 2014.7.0.
.INDENT 7.0
.TP
.B name
The name of raid device to be created
.TP
.B level
The RAID level to use when creating the raid.
.TP
.B devices
A list of devices used to build the array.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/dev/md0:
raid.present:
\- level: 5
\- devices:
\- /dev/xvdd
\- /dev/xvde
\- /dev/xvdf
\- chunk: 256
\- run: True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.memcached
.SS States for Management of Memcached Keys
.sp
New in version 2014.1.0.
.INDENT 0.0
.TP
.B salt.states.memcached.absent(name, value=None, host=\(aq127.0.0.1\(aq, port=11211, time=0)
Ensure that a memcached key is not present.
.INDENT 7.0
.TP
.B name
The key
.TP
.B value
None
If specified, only ensure that the key is absent if it matches the
specified value.
.TP
.B host
The memcached server IP address
.TP
.B port
The memcached server port
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
foo:
memcached.absent
bar:
memcached.absent:
\- host: 10.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.memcached.managed(name, value=None, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0)
Manage a memcached key.
.INDENT 7.0
.TP
.B name
The key to manage
.TP
.B value
The value to set for that key
.TP
.B host
The memcached server IP address
.TP
.B port
The memcached server port
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
foo:
memcached.managed:
\- value: bar
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.modjk
.sp
State to control Apache modjk
.INDENT 0.0
.TP
.B salt.states.modjk.worker_activated(name, workers=None, profile=\(aqdefault\(aq)
Activate all the workers in the modjk load balancer
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
loadbalancer:
modjk.worker_activated:
\- workers:
\- app1
\- app2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.modjk.worker_disabled(name, workers=None, profile=\(aqdefault\(aq)
Disable all the workers in the modjk load balancer
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
loadbalancer:
modjk.worker_disabled:
\- workers:
\- app1
\- app2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.modjk.worker_recover(name, workers=None, profile=\(aqdefault\(aq)
Recover all the workers in the modjk load balancer
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
loadbalancer:
modjk.worker_recover:
\- workers:
\- app1
\- app2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.modjk.worker_stopped(name, workers=None, profile=\(aqdefault\(aq)
Stop all the workers in the modjk load balancer
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
loadbalancer:
modjk.worker_stopped:
\- workers:
\- app1
\- app2
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.modjk_worker
.SS Manage modjk workers
.sp
Send commands to a \fBmodjk\fP load balancer via the peer system.
.sp
This module can be used with the \fBprereq\fP
requisite to remove/add the worker from the load balancer before
deploying/restarting service.
.sp
Mandatory Settings:
.INDENT 0.0
.IP \(bu 2
The minion needs to have permission to publish the \fBmodjk.*\fP
functions (see \fBhere\fP for information on configuring
peer publishing permissions)
.IP \(bu 2
The modjk load balancer must be configured as stated in the \fBmodjk\fP
execution module \fBdocumentation\fP
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.modjk_worker.activate(name, lbn, target, profile=\(aqdefault\(aq, expr_form=\(aqglob\(aq)
Activate the named worker from the lbn load balancers at the targeted
minions
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
disable\-before\-deploy:
modjk_worker.activate:
\- name: {{ grains[\(aqid\(aq] }}
\- lbn: application
\- target: \(aqroles:balancer\(aq
\- expr_form: grain
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.modjk_worker.disable(name, lbn, target, profile=\(aqdefault\(aq, expr_form=\(aqglob\(aq)
Disable the named worker from the lbn load balancers at the targeted
minions.
The worker will get traffic only for current sessions and won\(aqt get new
ones.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
disable\-before\-deploy:
modjk_worker.disable:
\- name: {{ grains[\(aqid\(aq] }}
\- lbn: application
\- target: \(aqroles:balancer\(aq
\- expr_form: grain
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.modjk_worker.stop(name, lbn, target, profile=\(aqdefault\(aq, expr_form=\(aqglob\(aq)
Stop the named worker from the lbn load balancers at the targeted minions
The worker won\(aqt get any traffic from the lbn
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
disable\-before\-deploy:
modjk_worker.stop:
\- name: {{ grains[\(aqid\(aq] }}
\- lbn: application
\- target: \(aqroles:balancer\(aq
\- expr_form: grain
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.module
.SS Execution of Salt modules from within states
.sp
These states allow individual execution module calls to be made via states. To
call a single module function use a \fI\%module.run\fP
state:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mine.send:
module.run:
\- name: network.interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that this example is probably unnecessary to use in practice, since the
\fBmine_functions\fP and \fBmine_interval\fP config parameters can be used to
schedule updates for the mine (see \fBhere\fP for more
info).
.sp
It is sometimes desirable to trigger a function call after a state is executed,
for this the \fI\%module.wait\fP state can be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mine.send:
module.wait:
\- name: network.interfaces
\- watch:
\- file: /etc/network/interfaces
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All arguments that the \fBmodule\fP state does not consume are passed through to
the execution module function being executed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fetch_out_of_band:
module.run:
\- name: git.fetch
\- cwd: /path/to/my/repo
\- user: myuser
\- opts: \(aq\-\-all\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Due to how the state system works, if a module function accepts an
argument called, \fBname\fP, then \fBm_name\fP must be used to specify that
argument, to avoid a collision with the \fBname\fP argument. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
disable_nfs:
module.run:
\- name: service.disable
\- m_name: nfs
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.module.mod_watch(name, **kwargs)
Run a single module function
.INDENT 7.0
.TP
.B \fBname\fP
The module function to execute
.TP
.B \fBreturner\fP
Specify the returner to send the return of the module execution to
.TP
.B \fB**kwargs\fP
Pass any arguments needed to execute the function
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.module.run(name, **kwargs)
Run a single module function
.INDENT 7.0
.TP
.B \fBname\fP
The module function to execute
.TP
.B \fBreturner\fP
Specify the returner to send the return of the module execution to
.TP
.B \fB**kwargs\fP
Pass any arguments needed to execute the function
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.module.wait(name, **kwargs)
Run a single module function only if the watch statement calls it
.INDENT 7.0
.TP
.B \fBname\fP
The module function to execute
.TP
.B \fB**kwargs\fP
Pass any arguments needed to execute the function
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Like the \fBcmd.run\fP state, this state will
return \fBTrue\fP but not actually execute, unless one of the following
two things happens:
.INDENT 0.0
.IP 1. 3
The state has a \fBwatch requisite\fP, and
the state which it is watching changes.
.IP 2. 3
Another state has a \fBwatch_in requisite\fP which references this state, and the state
wth the \fBwatch_in\fP changes.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.mongodb_database
.sp
Management of Mongodb databases
.sp
Only deletion is supported, creation doesn\(aqt make sense
and can be done using mongodb_user.present
.INDENT 0.0
.TP
.B salt.states.mongodb_database.absent(name, user=None, password=None, host=None, port=None)
Ensure that the named database is absent
.INDENT 7.0
.TP
.B name
The name of the database to remove
.TP
.B user
The user to connect as (must be able to create the user)
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.UNINDENT
.UNINDENT
.SS salt.states.mongodb_user
.SS Management of Mongodb users
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module requires PyMongo to be installed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mongodb_user.absent(name, user=None, password=None, host=None, port=None, database=\(aqadmin\(aq)
Ensure that the named user is absent
.INDENT 7.0
.TP
.B name
The name of the user to remove
.TP
.B user
The user to connect as (must be able to create the user)
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.TP
.B database
The database to create the user in (if the db doesn\(aqt exist, it will be created)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mongodb_user.present(name, passwd, database=\(aqadmin\(aq, user=None, password=None, host=\(aqlocalhost\(aq, port=27017)
Ensure that the user is present with the specified properties
.INDENT 7.0
.TP
.B name
The name of the user to manage
.TP
.B passwd
The password of the user
.TP
.B user
The user to connect as (must be able to create the user)
.TP
.B password
The password of the user
.TP
.B host
The host to connect to
.TP
.B port
The port to connect to
.TP
.B database
The database to create the user in (if the db doesn\(aqt exist, it will be created)
.UNINDENT
.UNINDENT
.SS salt.states.mount
.SS Mounting of filesystems
.sp
Mount any type of mountable filesystem with the mounted function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/mnt/sdb:
mount.mounted:
\- device: /dev/sdb1
\- fstype: ext4
\- mkmnt: True
\- opts:
\- defaults
/srv/bigdata:
mount.mounted:
\- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314
\- fstype: xfs
\- opts: nobootwait,noatime,nodiratime,nobarrier,logbufs=8
\- dump: 0
\- pass_num: 2
\- persist: True
\- mkmnt: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mount.mod_watch(name, **kwargs)
The mounted watcher, called to invoke the watch command.
.INDENT 7.0
.TP
.B name
The name of the mount point
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mount.mounted(name, device, fstype, mkmnt=False, opts=None, dump=0, pass_num=0, config=\(aq/etc/fstab\(aq, persist=True, mount=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 \fB/dev/sdb1\fP
or \fBUUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314\fP or \fBLABEL=DATA\fP
.TP
.B fstype
The filesystem type, this will be \fBxfs\fP, \fBext2/3/4\fP in the case of classic
filesystems, and \fBfuse\fP in the case of fuse mounts
.TP
.B mkmnt
If the mount point is not present then the state will fail, set \fBmkmnt: True\fP
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 is \fB0\fP
.TP
.B pass_num
The pass value to be passed into the fstab, Default is \fB0\fP
.TP
.B config
Set an alternative location for the fstab, Default is \fB/etc/fstab\fP
.TP
.B persist
Set if the mount should be saved in the fstab, Default is \fBTrue\fP
.TP
.B mount
Set if the mount should be mounted immediately, Default is \fBTrue\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mount.swap(name, persist=True, config=\(aq/etc/fstab\(aq)
Activates a swap device
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/root/swapfile:
mount.swap
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
\fBswap\fP does not currently support LABEL
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mount.unmounted(name, config=\(aq/etc/fstab\(aq, persist=False)
New in version 0.17.0.
.sp
Verify that a device is not mounted
.INDENT 7.0
.TP
.B name
The path to the location where the device is to be unmounted from
.TP
.B config
Set an alternative location for the fstab, Default is \fB/etc/fstab\fP
.TP
.B persist
Set if the mount should be purged from the fstab, Default is \fBFalse\fP
.UNINDENT
.UNINDENT
.SS salt.states.mysql_database
.SS Management of MySQL databases (schemas)
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
MySQLdb Python module
.UNINDENT
.TP
.B configuration
See \fBsalt.modules.mysql\fP for setup instructions.
.UNINDENT
.sp
The mysql_database module is used to create and manage MySQL databases.
Databases can be set as either absent or present.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
frank:
mysql_database.present
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mysql_database.absent(name, **connection_args)
Ensure that the named database is absent
.INDENT 7.0
.TP
.B name
The name of the database to remove
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mysql_database.present(name, **connection_args)
Ensure that the named database is present with the specified properties
.INDENT 7.0
.TP
.B name
The name of the database to manage
.UNINDENT
.UNINDENT
.SS salt.states.mysql_grants
.SS Management of MySQL grants (user permissions)
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
MySQLdb Python module
.UNINDENT
.TP
.B configuration
See \fBsalt.modules.mysql\fP for setup instructions.
.UNINDENT
.sp
The mysql_grants module is used to grant and revoke MySQL permissions.
.sp
The \fBname\fP you pass in purely symbolic and does not have anything to do
with the grant itself.
.sp
The \fBdatabase\fP parameter needs to specify a \(aqpriv_level\(aq in the same
specification as defined in the MySQL documentation:
.INDENT 0.0
.IP \(bu 2
*
.IP \(bu 2
*.*
.IP \(bu 2
db_name.*
.IP \(bu 2
db_name.tbl_name
.IP \(bu 2
etc...
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
frank_exampledb:
mysql_grants.present:
\- grant: select,insert,update
\- database: exampledb.*
\- user: frank
\- host: localhost
frank_otherdb:
mysql_grants.present:
\- grant: all privileges
\- database: otherdb.*
\- user: frank
restricted_singletable:
mysql_grants.present:
\- grant: select
\- database: somedb.sometable
\- user: joe
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mysql_grants.absent(name, grant=None, database=None, user=None, host=\(aqlocalhost\(aq, grant_option=False, escape=True, **connection_args)
Ensure that the grant is absent
.INDENT 7.0
.TP
.B name
The name (key) of the grant to add
.TP
.B grant
The grant priv_type (i.e. select,insert,update OR all privileges)
.TP
.B database
The database priv_level (i.e. db.tbl OR db.*)
.TP
.B user
The user to apply the grant to
.TP
.B host
The network/host that the grant should apply to
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mysql_grants.present(name, grant=None, database=None, user=None, host=\(aqlocalhost\(aq, grant_option=False, escape=True, revoke_first=False, ssl_option=False, **connection_args)
Ensure that the grant is present with the specified properties
.INDENT 7.0
.TP
.B name
The name (key) of the grant to add
.TP
.B grant
The grant priv_type (i.e. select,insert,update OR all privileges)
.TP
.B database
The database priv_level (ie. db.tbl OR db.*)
.TP
.B user
The user to apply the grant to
.TP
.B host
The network/host that the grant should apply to
.TP
.B grant_option
Adds the WITH GRANT OPTION to the defined grant. Default is \fBFalse\fP
.TP
.B escape
Defines if the database value gets escaped or not. Default is \fBTrue\fP
.TP
.B revoke_first
By default, MySQL will not do anything if you issue a command to grant
privileges that are more restrictive than what\(aqs already in place. This
effectively means that you cannot downgrade permissions without first
revoking permissions applied to a db.table/user pair first.
.sp
To have Salt forcibly revoke perms before applying a new grant, enable
the \(aqrevoke_first options.
.sp
WARNING: This will \fIremove\fP permissions for a database before attempting
to apply new permissions. There is no guarantee that new permissions
will be applied correctly which can leave your database security in an
unknown and potentially dangerous state.
Use with caution!
.sp
Default is \fBFalse\fP
.TP
.B ssl_option
Adds the specified ssl options for the connecting user as requirements for
this grant. Value is a list of single\-element dicts corresponding to the
list of ssl options to use.
.sp
Possible key/value pairings for the dicts in the value:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\- SSL: True
\- X509: True
\- SUBJECT: <subject>
\- ISSUER: <issuer>
\- CIPHER: <cipher>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The non\-boolean ssl options take a string as their values, which should
be an appropriate value as specified by the MySQL documentation for these
options.
.sp
Default is \fBFalse\fP (no ssl options will be used)
.UNINDENT
.UNINDENT
.SS salt.states.mysql_query
.SS Execution of MySQL queries
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
MySQLdb Python module
.UNINDENT
.TP
.B configuration
See \fBsalt.modules.mysql\fP for setup instructions.
.UNINDENT
.sp
The mysql_query module is used to execute queries on MySQL databases.
Its output may be stored in a file or in a grain.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
query_id:
mysql_query.run
\- database: my_database
\- query: "SELECT * FROM table;"
\- output: "/tmp/query_id.txt"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mysql_query.run(name, database, query, output=None, grain=None, key=None, overwrite=True, **connection_args)
Execute an arbitrary query on the specified database
.INDENT 7.0
.TP
.B name
Used only as an ID
.TP
.B database
The name of the database to execute the query on
.TP
.B query
The query to execute
.TP
.B output
grain: output in a grain
other: the file to store results
None: output to the result comment (default)
.TP
.B grain:
grain to store the output (need output=grain)
.TP
.B key:
the specified grain will be treated as a dictionnary, the result
of this state will be stored under the specified key.
.TP
.B overwrite:
The file or grain will be overwritten if it already exists (default)
.UNINDENT
.UNINDENT
.SS salt.states.mysql_user
.SS Management of MySQL users
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
MySQLdb Python module
.UNINDENT
.TP
.B configuration
See \fBsalt.modules.mysql\fP for setup instructions.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
frank:
mysql_user.present:
\- host: localhost
\- password: bobcat
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 0.16.2: Authentication overrides have been added.
.sp
The MySQL authentication information specified in the minion config file can be
overidden in states using the following arguments: \fBconnection_host\fP,
\fBconnection_port\fP, \fBconnection_user\fP, \fBconnection_pass\fP,
\fBconnection_db\fP, \fBconnection_unix_socket\fP, \fBconnection_default_file\fP and
\fBconnection_charset\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
frank:
mysql_user.present:
\- host: localhost
\- password: "bob@cat"
\- connection_user: someuser
\- connection_pass: somepass
\- connection_charset: utf8
\- saltenv:
\- LC_ALL: "en_US.utf8"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mysql_user.absent(name, host=\(aqlocalhost\(aq, **connection_args)
Ensure that the named user is absent
.INDENT 7.0
.TP
.B name
The name of the user to remove
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mysql_user.present(name, host=\(aqlocalhost\(aq, password=None, password_hash=None, allow_passwordless=False, unix_socket=False, **connection_args)
Ensure that the named user is present with the specified properties. A
passwordless user can be configured by omitting \fBpassword\fP and
\fBpassword_hash\fP, and setting \fBallow_passwordless\fP to \fBTrue\fP\&.
.INDENT 7.0
.TP
.B name
The name of the user to manage
.TP
.B host
Host for which this user/password combo applies
.TP
.B password
The password to use for this user. Will take precedence over the
\fBpassword_hash\fP option if both are specified.
.TP
.B password_hash
The password in hashed form. Be sure to quote the password because YAML
doesn\(aqt like the \fB*\fP\&. A password hash can be obtained from the mysql
command\-line client like so:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mysql> SELECT PASSWORD(\(aqmypass\(aq);
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| PASSWORD(\(aqmypass\(aq) |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
| *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
1 row in set (0.00 sec)
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B allow_passwordless
If \fBTrue\fP, then \fBpassword\fP and \fBpassword_hash\fP can be omitted to
permit a passwordless login.
.sp
New in version 0.16.2.
.TP
.B unix_socket
If \fBTrue\fP and allow_passwordless is \fBTrue\fP, the unix_socket auth
plugin will be used.
.UNINDENT
.UNINDENT
.SS salt.states.network
.SS Configuration of network interfaces
.sp
The network module is used to create and manage network settings,
interfaces can be set as either managed or ignored. By default
all interfaces are ignored unless specified.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Prior to version 2014.1.0, only RedHat\-based systems (RHEL,
CentOS, Scientific Linux, etc.) are supported. Support for Debian/Ubuntu is
new in 2014.1.0 and should be considered experimental.
.sp
Other platforms are not yet supported.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
system:
network.system:
\- enabled: True
\- hostname: server1.example.com
\- gateway: 192.168.0.1
\- gatewaydev: eth0
\- nozeroconf: True
\- nisdomain: example.com
\- require_reboot: True
eth0:
network.managed:
\- enabled: True
\- type: eth
\- proto: none
\- ipaddr: 10.1.0.1
\- netmask: 255.255.255.0
\- dns:
\- 8.8.8.8
\- 8.8.4.4
routes:
network.routes:
\- name: eth0
\- routes:
\- name: secure_network
ipaddr: 10.2.0.0
netmask: 255.255.255.0
gateway: 10.1.0.3
\- name: HQ_network
ipaddr: 10.100.0.0
netmask: 255.255.0.0
gateway: 10.1.0.10
eth2:
network.managed:
\- enabled: True
\- type: slave
\- master: bond0
eth3:
network.managed:
\- enabled: True
\- type: slave
\- master: bond0
eth4:
network.managed:
\- enabled: True
\- type: eth
\- proto: dhcp
\- bridge: br0
bond0:
network.managed:
\- type: bond
\- ipaddr: 10.1.0.1
\- netmask: 255.255.255.0
\- mode: active\-backup
\- proto: static
\- dns:
\- 8.8.8.8
\- 8.8.4.4
\- ipv6:
\- enabled: False
\- slaves: eth2 eth3
\- require:
\- network: eth2
\- network: eth3
\- miimon: 100
\- arp_interval: 250
\- downdelay: 200
\- lacp_rate: fast
\- max_bonds: 1
\- updelay: 0
\- use_carrier: on
\- xmit_hash_policy: layer2
\- mtu: 9000
\- autoneg: on
\- speed: 1000
\- duplex: full
\- rx: on
\- tx: off
\- sg: on
\- tso: off
\- ufo: off
\- gso: off
\- gro: off
\- lro: off
bond0.2:
network.managed:
\- type: vlan
\- ipaddr: 10.1.0.2
\- use:
\- network: bond0
\- require:
\- network: bond0
bond0.3:
network.managed:
\- type: vlan
\- ipaddr: 10.1.0.3
\- use:
\- network: bond0
\- require:
\- network: bond0
bond0.10:
network.managed:
\- type: vlan
\- ipaddr: 10.1.0.4
\- use:
\- network: bond0
\- require:
\- network: bond0
bond0.12:
network.managed:
\- type: vlan
\- ipaddr: 10.1.0.5
\- use:
\- network: bond0
\- require:
\- network: bond0
br0:
network.managed:
\- enabled: True
\- type: bridge
\- proto: dhcp
\- bridge: br0
\- delay: 0
\- ports: eth4
\- bypassfirewall: True
\- use:
\- network: eth4
\- require:
\- network: eth4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When managing bridged interfaces on a Debian or Ubuntu based system, the
ports argument is required. Red Hat systems will ignore the argument.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.network.managed(name, type, enabled=True, **kwargs)
Ensure that the named interface is configured properly.
.INDENT 7.0
.TP
.B name
The name of the interface to manage
.TP
.B type
Type of interface and configuration.
.TP
.B enabled
Designates the state of this interface.
.TP
.B kwargs
The IP parameters for this interface.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.network.routes(name, **kwargs)
Manage network interface static routes.
.INDENT 7.0
.TP
.B name
Interface name to apply the route to.
.TP
.B kwargs
Named routes
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.network.system(name, **kwargs)
Ensure that global network settings are configured properly.
.INDENT 7.0
.TP
.B name
Custom name to represent this configuration change.
.TP
.B kwargs
The global parameters for the system.
.UNINDENT
.UNINDENT
.SS salt.states.nftables
.SS Management of nftables
.sp
This is an nftables\-specific module designed to manage Linux firewalls. It is
expected that this state module, and other system\-specific firewall states, may
at some point be deprecated in favor of a more generic \fIfirewall\fP state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
nftables.append:
\- table: filter
\- chain: input
\- jump: accept
\- match: state
\- connstate: new
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
nftables.append:
\- table: filter
\- family: ipv6
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
nftables.insert:
\- position: 1
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
nftables.insert:
\- position: 1
\- table: filter
\- family: ipv6
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
nftables.delete:
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
nftables.delete:
\- position: 1
\- table: filter
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
httpd:
nftables.delete:
\- table: filter
\- family: ipv6
\- chain: INPUT
\- jump: ACCEPT
\- match: state
\- connstate: NEW
\- dport: 80
\- proto: tcp
\- sport: 1025:65535
\- save: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.nftables.append(name, family=\(aqipv4\(aq, **kwargs)
New in version 0.17.0.
.sp
Append a rule to a chain
.INDENT 7.0
.TP
.B name
A user\-defined name to call this rule by in another part of a state or
formula. This should not be an actual rule.
.TP
.B family
Network family, ipv4 or ipv6.
.UNINDENT
.sp
All other arguments are passed in with the same name as the long option
that would normally be used for nftables, with one exception: \fI\-\-state\fP is
specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with
\fIctstate\fP).
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.nftables.chain_absent(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Verify the chain is absent.
.INDENT 7.0
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.nftables.chain_present(name, table=\(aqfilter\(aq, table_type=None, hook=None, priority=None, family=\(aqipv4\(aq)
New in version 2014.7.0.
.sp
Verify the chain is exist.
.INDENT 7.0
.TP
.B name
A user\-defined chain name.
.TP
.B table
The table to own the chain.
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.nftables.delete(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Delete a rule to a chain
.INDENT 7.0
.TP
.B name
A user\-defined name to call this rule by in another part of a state or
formula. This should not be an actual rule.
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.sp
All other arguments are passed in with the same name as the long option
that would normally be used for nftables, with one exception: \fI\-\-state\fP is
specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with
\fIctstate\fP).
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.nftables.flush(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Flush current nftables state
.INDENT 7.0
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.nftables.insert(name, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
.sp
Insert a rule into a chain
.INDENT 7.0
.TP
.B name
A user\-defined name to call this rule by in another part of a state or
formula. This should not be an actual rule.
.TP
.B family
Networking family, either ipv4 or ipv6
.UNINDENT
.sp
All other arguments are passed in with the same name as the long option
that would normally be used for nftables, with one exception: \fI\-\-state\fP is
specified as \fIconnstate\fP instead of \fIstate\fP (not to be confused with
\fIctstate\fP).
.UNINDENT
.SS salt.states.npm
.SS Installation of NPM Packages
.sp
These states manage the installed packages for node.js using the Node Package
Manager (npm). Note that npm must be installed for these states to be
available, so npm states should include a requisite to a pkg.installed state
for the package which provides npm (simply \fBnpm\fP in most cases). Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
npm:
pkg.installed
yaml:
npm.installed:
\- require:
\- pkg: npm
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.npm.bootstrap(name, runas=None, user=None)
Bootstraps a node.js application.
.sp
will execute npm install \-\-json on the specified directory
.INDENT 7.0
.TP
.B runas
The user to run NPM with
.sp
Deprecated since version 0.17.0.
.TP
.B user
The user to run NPM with
.sp
New in version 0.17.0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.npm.installed(name, pkgs=None, dir=None, runas=None, user=None, force_reinstall=False, registry=None, env=None)
Verify that the given package is installed and is at the correct version
(if specified).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
coffee\-script:
npm.installed:
\- user: someuser
coffee\-script@1.0.1:
npm.installed: []
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
The package to install
.sp
Changed in version 2014.7.2: This parameter is no longer lowercased by salt so that
case\-sensitive NPM package names will work.
.TP
.B pkgs
A list of packages to install with a single npm invocation; specifying
this argument will ignore the \fBname\fP argument
.sp
New in version 2014.7.0.
.TP
.B dir
The target directory in which to install the package, or None for
global installation
.TP
.B runas
The user to run NPM with
.sp
Deprecated since version 0.17.0.
.TP
.B user
The user to run NPM with
.sp
New in version 0.17.0.
.TP
.B registry
The NPM registry from which to install the package
.sp
New in version 2014.7.0.
.TP
.B env
A list of environment variables to be set prior to execution. The
format is the same as the \fBcmd.run\fP\&.
state function.
.sp
New in version 2014.7.0.
.TP
.B force_reinstall
Install the package even if it is already installed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.npm.removed(name, dir=None, runas=None, user=None)
Verify that the given package is not installed.
.INDENT 7.0
.TP
.B dir
The target directory in which to install the package, or None for
global installation
.TP
.B runas
The user to run NPM with
.sp
Deprecated since version 0.17.0.
.TP
.B user
The user to run NPM with
.sp
New in version 0.17.0.
.UNINDENT
.UNINDENT
.SS salt.states.ntp
.SS Management of NTP servers
.sp
New in version 2014.1.0.
.sp
This state is used to manage NTP servers. Currently only Windows is supported.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
win_ntp:
ntp.managed:
\- servers:
\- pool.ntp.org
\- us.pool.ntp.org
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ntp.managed(name, servers=None)
Manage NTP servers
.INDENT 7.0
.TP
.B servers
A list of NTP servers
.UNINDENT
.UNINDENT
.SS salt.states.openstack_config
.sp
Manage OpenStack configuration file settings.
.INDENT 0.0
.TP
.B maintainer
Jeffrey C. Ollie <\fI\%jeff@ocjtech.us\fP>
.TP
.B maturity
new
.TP
.B depends
.TP
.B platform
linux
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.openstack_config.absent(name, filename, section, parameter=None)
Ensure a value is not set in an OpenStack configuration file.
.INDENT 7.0
.TP
.B filename
The full path to the configuration file
.TP
.B section
The section in which the parameter will be set
.TP
.B parameter (optional)
The parameter to change. If the parameter is not supplied, the name will be used as the parameter.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.openstack_config.present(name, filename, section, value, parameter=None)
Ensure a value is set in an OpenStack configuration file.
.INDENT 7.0
.TP
.B filename
The full path to the configuration file
.TP
.B section
The section in which the parameter will be set
.TP
.B parameter (optional)
The parameter to change. If the parameter is not supplied, the name will be used as the parameter.
.TP
.B value
The value to set
.UNINDENT
.UNINDENT
.SS salt.states.pagerduty
.SS Create an Event in PagerDuty
.sp
New in version 2014.1.0.
.sp
This state is useful for creating events on the PagerDuty service during state
runs.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server\-warning\-message:
pagerduty.create_event:
\- name: \(aqThis is a server warning message\(aq
\- details: \(aqThis is a much more detailed message\(aq
\- service_key: 9abcd123456789efabcde362783cdbaf
\- profile: my\-pagerduty\-account
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pagerduty.create_event(name, details, service_key, profile)
Create an event on the PagerDuty service
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
server\-warning\-message:
pagerduty.create_event:
\- name: \(aqThis is a server warning message\(aq
\- details: \(aqThis is a much more detailed message\(aq
\- service_key: 9abcd123456789efabcde362783cdbaf
\- profile: my\-pagerduty\-account
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following parameters are required:
.INDENT 7.0
.TP
.B name
This is a short description of the event.
.TP
.B details
This can be a more detailed description of the event.
.TP
.B service_key
This key can be found by using pagerduty.list_services.
.TP
.B profile
This refers to the configuration profile to use to connect to the
PagerDuty service.
.UNINDENT
.UNINDENT
.SS salt.states.pecl
.SS Installation of PHP Extensions Using pecl
.sp
These states manage the installed pecl extensions. Note that php\-pear must be
installed for these states to be available, so pecl states should include a
requisite to a pkg.installed state for the package which provides pecl
(\fBphp\-pear\fP in most cases). Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
php\-pear:
pkg.installed
mongo:
pecl.installed:
\- require:
\- pkg: php\-pear
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pecl.installed(name, version=None, defaults=False, force=False, preferred_state=\(aqstable\(aq)
New in version 0.17.0.
.sp
Make sure that a pecl extension is installed.
.INDENT 7.0
.TP
.B name
The pecl extension name to install
.TP
.B version
The pecl extension version to install. This option may be
ignored to install the latest stable version.
.TP
.B defaults
Use default answers for extensions such as pecl_http which ask
questions before installation. Without this option, the pecl.installed
state will hang indefinitely when trying to install these extensions.
.TP
.B force
Whether to force the installed version or not
.TP
.B preferred_state
The pecl extension state to install
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pecl.removed(name)
Make sure that a pecl extension is not installed.
.INDENT 7.0
.TP
.B name
The pecl extension name to uninstall
.UNINDENT
.UNINDENT
.SS salt.states.pip_state
.SS Installation of Python Packages Using pip
.sp
These states manage system installed python packages. Note that pip must be
installed for these states to be available, so pip states should include a
requisite to a pkg.installed state for the package which provides pip
(\fBpython\-pip\fP in most cases). Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python\-pip:
pkg.installed
virtualenvwrapper:
pip.installed:
\- require:
\- pkg: python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pip_state.installed(name, pip_bin=None, requirements=None, env=None, bin_env=None, use_wheel=False, no_use_wheel=False, log=None, proxy=None, timeout=None, repo=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, exists_action=None, no_deps=False, no_install=False, no_download=False, install_options=None, global_options=None, user=None, runas=None, no_chown=False, cwd=None, activate=False, pre_releases=False, cert=None, allow_all_external=False, allow_external=None, allow_unverified=None, process_dependency_links=False)
Make sure the package is installed
.INDENT 7.0
.TP
.B name
The name of the python package to install. You can also specify version
numbers here using the standard operators \fB==, >=, <=\fP\&. If
\fBrequirements\fP is given, this parameter will be ignored.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
django:
pip.installed:
\- name: django >= 1.6, <= 1.7
\- require:
\- pkg: python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will install the latest Django version greater than 1.6 but less
than 1.7.
.INDENT 7.0
.TP
.B requirements
Path to a pip requirements file. If the path begins with salt://
the file will be transferred from the master file server.
.TP
.B user
The user under which to run pip
.TP
.B use_wheel
False
Prefer wheel archives (requires pip>=1.4)
.TP
.B no_use_wheel
False
Force to not use wheel archives (requires pip>=1.4)
.TP
.B log
Log file where a complete (maximum verbosity) record will be kept
.TP
.B proxy
Specify a proxy in the form
user:passwd@proxy.server:port. Note that the
user:password@ is optional and required only if you
are behind an authenticated proxy. If you provide
user@proxy.server:port then you will be prompted for a
password.
.TP
.B timeout
Set the socket timeout (default 15 seconds)
.TP
.B editable
install something editable (i.e.
git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed)
.TP
.B find_links
URL to look for packages at
.TP
.B index_url
Base URL of Python Package Index
.TP
.B extra_index_url
Extra URLs of package indexes to use in addition to \fBindex_url\fP
.TP
.B no_index
Ignore package index
.TP
.B mirrors
Specific mirror URL(s) to query (automatically adds \-\-use\-mirrors)
.TP
.B build
Unpack packages into \fBbuild\fP dir
.TP
.B target
Install packages into \fBtarget\fP dir
.TP
.B download
Download packages into \fBdownload\fP instead of installing them
.TP
.B download_cache
Cache downloaded packages in \fBdownload_cache\fP dir
.TP
.B source
Check out \fBeditable\fP packages into \fBsource\fP dir
.TP
.B upgrade
Upgrade all packages to the newest available version
.TP
.B force_reinstall
When upgrading, reinstall all packages even if they are already
up\-to\-date.
.TP
.B ignore_installed
Ignore the installed packages (reinstalling instead)
.TP
.B exists_action
Default action when a path already exists: (s)witch, (i)gnore, (w)ipe,
(b)ackup
.TP
.B no_deps
Ignore package dependencies
.TP
.B no_install
Download and unpack all packages, but don\(aqt actually install them
.TP
.B no_chown
When user is given, do not attempt to copy and chown
a requirements file
.TP
.B cwd
Current working directory to run pip from
.TP
.B activate
Activates the virtual environment, if given via bin_env,
before running install.
.sp
Deprecated since version 2014.7.2: If \fIbin_env\fP is given, pip will already be sourced from that
virualenv, making \fIactivate\fP effectively a noop.
.TP
.B pre_releases
Include pre\-releases in the available versions
.TP
.B cert
Provide a path to an alternate CA bundle
.TP
.B allow_all_external
Allow the installation of all externally hosted files
.TP
.B allow_external
Allow the installation of externally hosted files (comma separated list)
.TP
.B allow_unverified
Allow the installation of insecure and unverifiable files (comma separated list)
.TP
.B process_dependency_links
Enable the processing of dependency links
.TP
.B bin_env
None
Absolute path to a virtual environment directory or absolute path to
a pip executable. The example below assumes a virtual environment
has been created at \fB/foo/.virtualenvs/bar\fP\&.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
django:
pip.installed:
\- name: django >= 1.6, <= 1.7
\- bin_env: /foo/.virtualenvs/bar
\- require:
\- pkg: python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
django:
pip.installed:
\- name: django >= 1.6, <= 1.7
\- bin_env: /foo/.virtualenvs/bar/bin/pip
\- require:
\- pkg: python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
The following arguments are deprecated, do not use.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B pip_bin
None
Deprecated, use \fBbin_env\fP
.TP
.B env
None
Deprecated, use \fBbin_env\fP
.UNINDENT
.sp
Changed in version 0.17.0: \fBuse_wheel\fP option added.
.sp
install_options
.INDENT 7.0
.INDENT 3.5
Extra arguments to be supplied to the setup.py install command.
If you are using an option with a directory path, be sure to use
absolute path.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
django:
pip.installed:
\- name: django
\- install_options:
\- \-\-prefix=/blah
\- require:
\- pkg: python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B global_options
Extra global options to be supplied to the setup.py call before the
install command.
.sp
New in version 2014.1.3.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.IP "Attention"
.sp
As of Salt 0.17.0 the pip state \fBneeds\fP an importable pip module.
This usually means having the system\(aqs pip package installed or running
Salt from an active \fI\%virtualenv\fP\&.
.sp
The reason for this requirement is because \fBpip\fP already does a
pretty good job parsing its own requirements. It makes no sense for
Salt to do \fBpip\fP requirements parsing and validation before passing
them to the \fBpip\fP library. It\(aqs functionality duplication and it\(aqs
more error prone.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pip_state.removed(name, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, user=None, runas=None, cwd=None)
Make sure that a package is not installed.
.INDENT 7.0
.TP
.B name
The name of the package to uninstall
.TP
.B user
The user under which to run pip
.TP
.B bin_env
None
the pip executable or virtualenenv to use
.UNINDENT
.UNINDENT
.SS salt.states.pkg
.SS Installation of packages using OS package managers such as yum or apt\-get
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A more involved example involves pulling from a custom repository.
Note that the pkgrepo has a require_in clause.
This is necessary and can not be replaced by a require clause in the pkg.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
pkgrepo.managed:
\- humanname: Logstash PPA
\- name: ppa:wolfnet/logstash
\- dist: precise
\- file: /etc/apt/sources.list.d/logstash.list
\- keyid: 28B04E4A
\- keyserver: keyserver.ubuntu.com
\- require_in:
\- pkg: logstash
logstash:
pkg.installed
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.installed(name, version=None, refresh=None, fromrepo=None, skip_verify=False, skip_suggestions=False, pkgs=None, sources=None, allow_updates=False, pkg_verify=False, normalize=True, **kwargs)
Ensure that the package is installed, and that it is the correct version
(if specified).
.INDENT 7.0
.TP
.B name
The name of the package to be installed. This parameter is ignored if
either "pkgs" or "sources" is used. Additionally, please note that this
option can only be used to install packages from a software repository.
To install a package file manually, use the "sources" option detailed
below.
.TP
.B fromrepo
Specify a repository from which to install
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Distros which use APT (Debian, Ubuntu, etc.) do not have a concept
of repositories, in the same way as YUM\-based distros do. When a
source is added, it is assigned to a given release. Consider the
following source configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
deb http://ppa.launchpad.net/saltstack/salt/ubuntu precise main
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The packages provided by this source would be made available via
the \fBprecise\fP release, therefore \fBfromrepo\fP would need to be
set to \fBprecise\fP for Salt to install the package from this
source.
.sp
Having multiple sources in the same release may result in the
default install candidate being newer than what is desired. If this
is the case, the desired version must be specified using the
\fBversion\fP parameter.
.sp
If the \fBpkgs\fP parameter is being used to install multiple
packages in the same state, then instead of using \fBversion\fP,
use the method of version specification described in the \fBMultiple
Package Installation Options\fP section below.
.sp
Running the shell command \fBapt\-cache policy pkgname\fP on a minion
can help elucidate the APT configuration and aid in properly
configuring states:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root@saltmaster:~# salt ubuntu01 cmd.run \(aqapt\-cache policy ffmpeg\(aq
ubuntu01:
ffmpeg:
Installed: (none)
Candidate: 7:0.10.11\-1~precise1
Version table:
7:0.10.11\-1~precise1 0
500 http://ppa.launchpad.net/jon\-severinsson/ffmpeg/ubuntu/ precise/main amd64 Packages
4:0.8.10\-0ubuntu0.12.04.1 0
500 http://us.archive.ubuntu.com/ubuntu/ precise\-updates/main amd64 Packages
500 http://security.ubuntu.com/ubuntu/ precise\-security/main amd64 Packages
4:0.8.1\-0ubuntu1 0
500 http://us.archive.ubuntu.com/ubuntu/ precise/main amd64 Packages
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The release is located directly after the source\(aqs URL. The actual
release name is the part before the slash, so to install version
\fB4:0.8.10\-0ubuntu0.12.04.1\fP either \fBprecise\-updates\fP or
\fBprecise\-security\fP could be used for the \fBfromrepo\fP value.
.UNINDENT
.UNINDENT
.TP
.B skip_verify
Skip the GPG verification check for the package to be installed
.TP
.B skip_suggestions
Force strict package naming. Disables lookup of package alternatives.
.sp
New in version 2014.1.1.
.TP
.B version
Install a specific version of a package. This option is ignored if
either "pkgs" or "sources" is used. Currently, this option is supported
for the following pkg providers: \fBapt\fP,
\fBebuild\fP,
\fBpacman\fP,
\fByumpkg\fP, and
\fBzypper\fP\&. The version number includes the
release designation where applicable, to allow Salt to target a
specific release of a given version. When in doubt, using the
\fBpkg.latest_version\fP function for an uninstalled package will tell
you the version available.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# salt myminion pkg.latest_version httpd
myminion:
2.2.15\-30.el6.centos
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Also, while this function is not yet implemented for all pkg frontends,
\fBpkg.list_repo_pkgs\fP will
show all versions available in the various repositories for a given
package, irrespective of whether or not it is installed.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# salt myminion pkg.list_repo_pkgs httpd
myminion:
\-\-\-\-\-\-\-\-\-\-
base:
|_
\-\-\-\-\-\-\-\-\-\-
httpd:
2.2.15\-29.el6.centos
updates:
|_
\-\-\-\-\-\-\-\-\-\-
httpd:
2.2.15\-30.el6.centos
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The version strings returned by either of these functions can be used
as version specifiers in pkg states.
.TP
.B refresh
Update the repo database of available packages prior to installing the
requested package.
.TP
.B hold
Force the package to be held at the current installed version.
Currently works with YUM & APT based systems.
.sp
New in version 2014.7.0.
.TP
.B allow_updates
Allow the package to be updated outside Salt\(aqs control (e.g. auto updates on Windows).
This means a package on the Minion can have a newer version than the latest available
in the repository without enforcing a re\-installation of the package.
.sp
New in version 2014.7.0.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed:
\- fromrepo: mycustomrepo
\- skip_verify: True
\- skip_suggestions: True
\- version: 2.0.6~ubuntu3
\- refresh: True
\- hold: False
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B pkg_verify
New in version 2014.7.0.
.sp
For requested packages that are already installed and would not be targeted for
upgrade or downgrade, use pkg.verify to determine if any of the files installed
by the package have been altered. If files have been altered, the reinstall
option of pkg.install is used to force a reinstall. Types to ignore can be
passed to pkg.verify (see example below). Currently, this option is supported
for the following pkg providers: \fByumpkg\fP\&.
.UNINDENT
.sp
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed:
\- version: 2.2.15\-30.el6.centos
\- pkg_verify: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.installed:
\- pkgs:
\- foo
\- bar: 1.2.3\-4
\- baz
\- pkg_verify:
\- ignore_types: [config,doc]
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B normalize
Normalize the package name by removing the architecture. Default is True.
This is useful for poorly created packages which might include the
architecture as an actual part of the name such as kernel modules
which match a specific kernel version.
.sp
New in version 2014.7.0.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
gpfs.gplbin\-2.6.32\-279.31.1.el6.x86_64:
pkg.installed:
\- normalize: False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBMultiple Package Installation Options: (not supported in Windows or
pkgng)\fP
.INDENT 7.0
.TP
.B pkgs
A list of packages to install from a software repository. All packages
listed under \fBpkgs\fP will be installed via a single command.
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.installed:
\- pkgs:
\- foo
\- bar
\- baz
\- hold: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP For \fBapt\fP,
\fBebuild\fP,
\fBpacman\fP, \fByumpkg\fP,
and \fBzypper\fP, version numbers can be specified
in the \fBpkgs\fP argument. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.installed:
\- pkgs:
\- foo
\- bar: 1.2.3\-4
\- baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Additionally, \fBebuild\fP,
\fBpacman\fP and
\fBzypper\fP support the \fB<\fP, \fB<=\fP, \fB>=\fP, and
\fB>\fP operators for more control over what versions will be installed. For
example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.installed:
\- pkgs:
\- foo
\- bar: \(aq>=1.2.3\-4\(aq
\- baz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP When using comparison operators, the expression must be enclosed
in quotes to avoid a YAML render error.
.sp
With \fBebuild\fP is also possible to specify a use
flag list and/or if the given packages should be in package.accept_keywords
file and/or the overlay from which you want the package to be installed.
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.installed:
\- pkgs:
\- foo: \(aq~\(aq
\- bar: \(aq~>=1.2:slot::overlay[use,\-otheruse]\(aq
\- baz
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B names
A list of packages to install from a software repository. Each package
will be installed individually by the package manager.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Unlike \fBpkgs\fP, the \fBnames\fP parameter cannot specify a version.
In addition, it makes a separate call to the package management
frontend to install each package, whereas \fBpkgs\fP makes just a
single call. It is therefore recommended to use \fBpkgs\fP instead of
\fBnames\fP to install multiple packages, both for the additional
features and the performance improvement that it brings.
.UNINDENT
.UNINDENT
.TP
.B sources
A list of packages to install, along with the source URI or local path
from which to install each package. In the example below, \fBfoo\fP,
\fBbar\fP, \fBbaz\fP, etc. refer to the name of the package, as it would
appear in the output of the \fBpkg.version\fP or \fBpkg.list_pkgs\fP salt
CLI commands.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.installed:
\- sources:
\- foo: salt://rpms/foo.rpm
\- bar: http://somesite.org/bar.rpm
\- baz: ftp://someothersite.org/baz.rpm
\- qux: /minion/path/to/qux.rpm
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.latest(name, refresh=None, fromrepo=None, skip_verify=False, pkgs=None, **kwargs)
Ensure 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
\fI\%installed\fP function to be
used, as \fI\%latest\fP will update 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.
This parameter is ignored if "pkgs" is used.
.TP
.B fromrepo
Specify a repository from which to install
.TP
.B skip_verify
Skip the GPG verification check for the package to be installed
.UNINDENT
.sp
Multiple Package Installation Options:
.sp
(Not yet supported for: Windows, FreeBSD, OpenBSD, MacOS, and Solaris
pkgutil)
.INDENT 7.0
.TP
.B pkgs
A list of packages to maintain at the latest available version.
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.latest:
\- pkgs:
\- foo
\- bar
\- baz
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.mod_aggregate(low, chunks, running)
The mod_aggregate function which looks up all packages in the available
low chunks and merges them into a single pkgs ref in the present low data
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.purged(name, pkgs=None, **kwargs)
Verify that a package is not installed, calling \fBpkg.purge\fP if necessary
to purge the package. All configuration files are also removed.
.INDENT 7.0
.TP
.B name
The name of the package to be purged.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to purge. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.removed(name, pkgs=None, **kwargs)
Verify that a package is not installed, calling \fBpkg.remove\fP if necessary
to remove the package.
.INDENT 7.0
.TP
.B name
The name of the package to be removed.
.UNINDENT
.sp
Multiple Package Options:
.INDENT 7.0
.TP
.B pkgs
A list of packages to remove. Must be passed as a python list. The
\fBname\fP parameter will be ignored if this option is passed.
.UNINDENT
.sp
New in version 0.16.0.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkg.uptodate(name, refresh=False)
New in version 2014.7.0.
.sp
Verify that the system is completely up to date.
.INDENT 7.0
.TP
.B name
The name has no functional value and is only used as a tracking
reference
.TP
.B refresh
refresh the package database before checking for new upgrades
.UNINDENT
.UNINDENT
.SS salt.states.pkgng
.SS Manage package remote repo using FreeBSD pkgng
.sp
Salt can manage the URL pkgng pulls packages from.
ATM the state and module are small so use cases are
typically rather simple:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pkgng_clients:
pkgng.update_packaging_site:
\- name: "http://192.168.0.2"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkgng.update_packaging_site(name)
.UNINDENT
.SS salt.states.pkgrepo
.SS Management of APT/YUM package repos
.sp
Package repositories for APT\-based and YUM\-based distros can be managed with
these states. Here is some example SLS:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
pkgrepo.managed:
\- humanname: CentOS\-$releasever \- Base
\- mirrorlist: http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=os
\- comments:
\- \(aq#http://mirror.centos.org/centos/$releasever/os/$basearch/\(aq
\- gpgcheck: 1
\- gpgkey: file:///etc/pki/rpm\-gpg/RPM\-GPG\-KEY\-CentOS\-6
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
pkgrepo.managed:
\- humanname: Logstash PPA
\- name: deb http://ppa.launchpad.net/wolfnet/logstash/ubuntu precise main
\- dist: precise
\- file: /etc/apt/sources.list.d/logstash.list
\- keyid: 28B04E4A
\- keyserver: keyserver.ubuntu.com
\- require_in:
\- pkg: logstash
pkg.latest:
\- name: logstash
\- refresh: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
pkgrepo.managed:
\- ppa: wolfnet/logstash
pkg.latest:
\- name: logstash
\- refresh: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
On Ubuntu systems, the \fBpython\-software\-properties\fP package should be
installed for better support of PPA repositories. To check if this package
is installed, run \fBdpkg \-l python\-software\-properties\fP\&.
.sp
Also, some Ubuntu releases have a \fI\%bug\fP in their
\fBpython\-software\-properties\fP package, a missing dependency on pycurl, so
\fBpython\-pycurl\fP will need to be manually installed if it is not present
once \fBpython\-software\-properties\fP is installed.
.sp
On Ubuntu & Debian systems, the \fB\(gapython\-apt\fP package is required to be installed.
To check if this package is installed, run \fBdpkg \-l python\-software\-properties\fP\&.
\fBpython\-apt\fP will need to be manually installed if it is not present.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkgrepo.absent(name, **kwargs)
This function deletes the specified repo on the system, if it exists. It
is essentially a wrapper around pkg.del_repo.
.INDENT 7.0
.TP
.B name
The name of the package repo, as it would be referred to when running
the regular package manager commands.
.TP
.B ppa
On Ubuntu, you can take advantage of Personal Package Archives on
Launchpad simply by specifying the user and archive name.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
logstash\-ppa:
pkgrepo.absent:
\- ppa: wolfnet/logstash
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B ppa_auth
For Ubuntu PPAs there can be private PPAs that require authentication
to access. For these PPAs the username/password can be specified. This
is required for matching if the name format uses the "ppa:" specifier
and is private (requires username/password to access, which is encoded
in the URI).
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
logstash\-ppa:
pkgrepo.absent:
\- ppa: wolfnet/logstash
\- ppa_auth: username:password
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pkgrepo.managed(name, **kwargs)
This function manages the configuration on a system that points to the
repositories for the system\(aqs package manager.
.INDENT 7.0
.TP
.B name
The name of the package repo, as it would be referred to when running
the regular package manager commands.
.UNINDENT
.sp
For yum\-based systems, take note of the following configuration values:
.INDENT 7.0
.TP
.B humanname
On yum\-based systems, this is stored as the "name" value in the .repo
file in /etc/yum.repos.d/. On yum\-based systems, this is required.
.TP
.B baseurl
On yum\-based systems, baseurl refers to a direct URL to be used for
this yum repo.
One of baseurl or mirrorlist is required.
.TP
.B mirrorlist
a URL which contains a collection of baseurls to choose from. On
yum\-based systems.
One of baseurl or mirrorlist is required.
.TP
.B comments
Sometimes you want to supply additional information, but not as
enabled configuration. Anything supplied for this list will be saved
in the repo configuration with a comment marker (#) in front.
.UNINDENT
.sp
Additional configuration values, such as gpgkey or gpgcheck, are used
verbatim to update the options for the yum repo in question.
.sp
For apt\-based systems, take note of the following configuration values:
.INDENT 7.0
.TP
.B ppa
On Ubuntu, you can take advantage of Personal Package Archives on
Launchpad simply by specifying the user and archive name. The keyid
will be queried from launchpad and everything else is set
automatically. You can override any of the below settings by simply
setting them as you would normally. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
logstash\-ppa:
pkgrepo.managed:
\- ppa: wolfnet/logstash
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B ppa_auth
For Ubuntu PPAs there can be private PPAs that require authentication
to access. For these PPAs the username/password can be passed as an
HTTP Basic style username/password combination.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
logstash\-ppa:
pkgrepo.managed:
\- ppa: wolfnet/logstash
\- ppa_auth: username:password
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B name
On apt\-based systems this must be the complete entry as it would be
seen in the sources.list file. This can have a limited subset of
components (i.e. \(aqmain\(aq) which can be added/modified with the
"comps" option.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
precise\-repo:
pkgrepo.managed:
\- name: deb http://us.archive.ubuntu.com/ubuntu precise main
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B disabled
Toggles whether or not the repo is used for resolving dependencies
and/or installing packages.
.TP
.B enabled
Enables the repository, even if the repository has been disabled, in
order for the respective package requiring the repository can be found
and installed.
.TP
.B comps
On apt\-based systems, comps dictate the types of packages to be
installed from the repository (e.g. main, nonfree, ...). For
purposes of this, comps should be a comma\-separated list.
.TP
.B file
The filename for the .list that the repository is configured in.
It is important to include the full\-path AND make sure it is in
a directory that APT will look in when handling packages
.TP
.B dist
This dictates the release of the distro the packages should be built
for. (e.g. unstable)
.TP
.B keyid
The KeyID of the GPG key to install. This option also requires
the \(aqkeyserver\(aq option to be set.
.TP
.B keyserver
This is the name of the keyserver to retrieve gpg keys from. The
keyid option must also be set for this option to work.
.TP
.B key_url
URL to retrieve a GPG key from.
.TP
.B consolidate
If set to true, this will consolidate all sources definitions to
the sources.list file, cleanup the now unused files, consolidate
components (e.g. main) for the same URI, type, and architecture
to a single line, and finally remove comments from the sources.list
file. The consolidate will run every time the state is processed. The
option only needs to be set on one repo managed by salt to take effect.
.TP
.B refresh_db
If set to false this will skip refreshing the apt package database on
debian based systems.
.TP
.B require_in
Set this to a list of pkg.installed or pkg.latest to trigger the
running of apt\-get update prior to attempting to install these
packages. Setting a require in the pkg will not work for this.
.UNINDENT
.UNINDENT
.SS salt.states.portage_config
.SS Management of Portage package configuration on Gentoo
.sp
A state module to manage Portage configuration on Gentoo
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt:
portage_config.flags:
\- use:
\- openssl
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.portage_config.flags(name, use=None, accept_keywords=None, env=None, license=None, properties=None, unmask=False, mask=False)
Enforce the given flags on the given package or DEPEND atom.
Please be warned that, in most cases, you need to rebuild the affected packages in
order to apply the changes.
.INDENT 7.0
.TP
.B name
The name of the package or his DEPEND atom
.TP
.B use
A list of use flags
.TP
.B accept_keywords
A list of keywords to accept. "~ARCH" means current host arch, and will
be translated in a line without keywords
.TP
.B env
A list of environment files
.TP
.B license
A list of accepted licenses
.TP
.B properties
A list of additional properties
.TP
.B unmask
A boolean to unmask the package
.TP
.B mask
A boolean to mask the package
.UNINDENT
.UNINDENT
.SS salt.states.ports
.sp
Manage software from FreeBSD ports
.sp
New in version 2014.1.0.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
It may be helpful to use a higher timeout when running a
\fI\%ports.installed\fP state, since compiling the port
may exceed Salt\(aqs timeout.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-t 1200 \(aq*\(aq state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ports.installed(name, options=None)
Verify that the desired port is installed, and that it was compiled with
the desired options.
.INDENT 7.0
.TP
.B options
Make sure that the desired non\-default options are set
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Any build options not passed here assume the default values for the
port, and are not just differences from the existing cached options
from a previous \fBmake config\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Example usage:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
security/nmap:
ports.installed:
\- options:
\- IPV6: off
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.postgres_database
.SS Management of PostgreSQL databases
.sp
The postgres_database module is used to create and manage Postgres databases.
Databases can be set as either absent or present
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
frank:
postgres_database.present
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_database.absent(name, runas=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named database is absent
.INDENT 7.0
.TP
.B name
The name of the database to remove
.TP
.B db_user
database username if different from config or defaul
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.TP
.B runas
System user all operations should be performed on behalf of
.sp
Deprecated since version 0.17.0.
.TP
.B user
System user all operations should be performed on behalf of
.sp
New in version 0.17.0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_database.present(name, tablespace=None, encoding=None, lc_collate=None, lc_ctype=None, owner=None, template=None, runas=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named database is present with the specified properties.
For more information about all of these options see man createdb(1)
.INDENT 7.0
.TP
.B name
The name of the database to manage
.TP
.B tablespace
Default tablespace for the database
.TP
.B encoding
The character encoding scheme to be used in this database
.TP
.B lc_collate
The LC_COLLATE setting to be used in this database
.TP
.B lc_ctype
The LC_CTYPE setting to be used in this database
.TP
.B owner
The username of the database owner
.TP
.B template
The template database from which to build this database
.TP
.B runas
System user all operations should be performed on behalf of
.sp
Deprecated since version 0.17.0.
.TP
.B user
System user all operations should be performed on behalf of
.TP
.B db_user
database username if different from config or default
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.sp
New in version 0.17.0.
.UNINDENT
.UNINDENT
.SS salt.states.postgres_extension
.SS Management of PostgreSQL extensions (e.g.: postgis)
.sp
The postgres_extensions module is used to create and manage Postgres extensions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
adminpack:
postgres_extension.present
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_extension.absent(name, if_exists=None, restrict=None, cascade=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named extension is absent
.INDENT 7.0
.TP
.B name
Extension name of the extension to remove
.TP
.B cascade
Drop on cascade
.TP
.B if_exists
Add if exist slug
.TP
.B restrict
Add restrict slug
.TP
.B maintenance_db
Database to act on
.TP
.B user
System user all operations should be performed on behalf of
.TP
.B db_user
database username if different from config or default
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_extension.present(name, if_not_exists=None, schema=None, ext_version=None, from_version=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named extension is present with the specified privileges
.INDENT 7.0
.TP
.B name
The name of the extension to manage
.TP
.B if_not_exists
Add a if_not_exists switch to the ddl statement
.TP
.B schema
Schema to install the extension into
.TP
.B from_version
Old extension version if already installed
.TP
.B ext_version
version to install
.TP
.B user
System user all operations should be performed on behalf of
.TP
.B maintenance_db
Database to act on
.TP
.B db_user
database username if different from config or default
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.UNINDENT
.UNINDENT
.SS salt.states.postgres_group
.SS Management of PostgreSQL groups (roles)
.sp
The postgres_group module is used to create and manage Postgres groups.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
frank:
postgres_group.present
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_group.absent(name, runas=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named group is absent
.INDENT 7.0
.TP
.B name
The groupname of the group to remove
.TP
.B runas
System user all operations should be performed on behalf of
.sp
Deprecated since version 0.17.0.
.TP
.B user
System user all operations should be performed on behalf of
.sp
New in version 0.17.0.
.TP
.B db_user
database username if different from config or defaul
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_group.present(name, createdb=None, createroles=None, createuser=None, encrypted=None, superuser=None, inherit=None, login=None, replication=None, password=None, refresh_password=None, groups=None, runas=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named group is present with the specified privileges
Please note that the user/group notion in postgresql is just abstract, we
have roles, where users can be seens as roles with the LOGIN privilege
and groups the others.
.INDENT 7.0
.TP
.B name
The name of the group to manage
.TP
.B createdb
Is the group allowed to create databases?
.TP
.B createroles
Is the group allowed to create other roles/users
.TP
.B createuser
Alias to create roles, and history problem, in pgsql normally
createuser == superuser
.TP
.B encrypted
Should the password be encrypted in the system catalog?
.TP
.B login
Should the group have login perm
.TP
.B inherit
Should the group inherit permissions
.TP
.B superuser
Should the new group be a "superuser"
.TP
.B replication
Should the new group be allowed to initiate streaming replication
.TP
.B password
The Group\(aqs password
It can be either a plain string or a md5 postgresql hashed password:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqmd5{MD5OF({password}{role}}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If encrypted is None or True, the password will be automatically
encrypted to the previous
format if it is not already done.
.TP
.B refresh_password
Password refresh flag
.sp
Boolean attribute to specify whether to password comparison check
should be performed.
.sp
If refresh_password is None or False, the password will be automatically
updated without extra password change check.
.sp
This behaviour allows to execute in environments without superuser access
available, e.g. Amazon RDS for PostgreSQL
.TP
.B groups
A string of comma separated groups the group should be in
.TP
.B runas
System user all operations should be performed on behalf of
.sp
Deprecated since version 0.17.0.
.TP
.B user
System user all operations should be performed on behalf of
.sp
New in version 0.17.0.
.TP
.B db_user
database username if different from config or defaul
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.UNINDENT
.UNINDENT
.SS salt.states.postgres_user
.SS Management of PostgreSQL users (roles)
.sp
The postgres_users module is used to create and manage Postgres users.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
frank:
postgres_user.present
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_user.absent(name, runas=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named user is absent
.INDENT 7.0
.TP
.B name
The username of the user to remove
.TP
.B runas
System user all operations should be performed on behalf of
.sp
Deprecated since version 0.17.0.
.TP
.B user
System user all operations should be performed on behalf of
.sp
New in version 0.17.0.
.TP
.B db_user
database username if different from config or default
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_user.present(name, createdb=None, createroles=None, createuser=None, encrypted=None, superuser=None, replication=None, inherit=None, login=None, password=None, refresh_password=None, groups=None, runas=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named user is present with the specified privileges
Please note that the user/group notion in postgresql is just abstract, we
have roles, where users can be seens as roles with the LOGIN privilege
and groups the others.
.INDENT 7.0
.TP
.B name
The name of the user to manage
.TP
.B createdb
Is the user allowed to create databases?
.TP
.B createroles
Is the user allowed to create other users?
.TP
.B createuser
Alias to create roles
.TP
.B encrypted
Should the password be encrypted in the system catalog?
.TP
.B login
Should the group have login perm
.TP
.B inherit
Should the group inherit permissions
.TP
.B superuser
Should the new user be a "superuser"
.TP
.B replication
Should the new user be allowed to initiate streaming replication
.TP
.B password
The user\(aqs password
It can be either a plain string or a md5 postgresql hashed password:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqmd5{MD5OF({password}{role}}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If encrypted is None or True, the password will be automatically
encrypted to the previous
format if it is not already done.
.TP
.B refresh_password
Password refresh flag
.sp
Boolean attribute to specify whether to password comparison check
should be performed.
.sp
If refresh_password is None or False, the password will be automatically
updated without extra password change check.
.sp
This behaviour allows to execute in environments without superuser access
available, e.g. Amazon RDS for PostgreSQL
.TP
.B groups
A string of comma separated groups the user should be in
.TP
.B runas
System user all operations should be performed on behalf of
.sp
Deprecated since version 0.17.0.
.TP
.B user
System user all operations should be performed on behalf of
.sp
New in version 0.17.0.
.TP
.B db_user
database username if different from config or default
.TP
.B db_password
user password if any password for a specified user
.TP
.B db_host
Database host if different from config or default
.TP
.B db_port
Database port if different from config or default
.UNINDENT
.UNINDENT
.SS salt.states.powerpath
.SS Powerpath configuration support
.sp
Allows configuration of EMC Powerpath. Currently
only addition/deletion of licenses is supported.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
key:
powerpath.license_present: []
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.powerpath.license_absent(name)
Ensures that the specified PowerPath license key is absent
on the host.
.INDENT 7.0
.TP
.B name
The licnese key to ensure is absent
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.powerpath.license_present(name)
Ensures that the specified PowerPath license key is present
on the host.
.INDENT 7.0
.TP
.B name
The licnese key to ensure is present
.UNINDENT
.UNINDENT
.SS salt.states.process
.SS Process Management
.sp
Ensure a process matching a given pattern is absent.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd\-absent:
process.absent:
\- name: apache2
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.process.absent(name, user=None, signal=None)
Ensures that the named command is not running.
.INDENT 7.0
.TP
.B name
The pattern to match.
.TP
.B user
The user process belongs
.TP
.B signal
Signal to send to the process(es).
.UNINDENT
.UNINDENT
.SS salt.states.pyenv
.SS Managing python installations with pyenv
.sp
This module is used to install and manage python installations with pyenv.
Different versions of python can be installed, and uninstalled. pyenv will
be installed automatically the first time it is needed and can be updated
later. This module will \fInot\fP automatically install packages which pyenv
will need to compile the versions of python.
.sp
If pyenv is run as the root user then it will be installed to /usr/local/pyenv,
otherwise it will be installed to the users ~/.pyenv directory. To make
pyenv available in the shell you may need to add the pyenv/shims and pyenv/bin
directories to the users PATH. If you are installing as root and want other
users to be able to access pyenv then you will need to add pyenv_ROOT to
their environment.
.sp
This is how a state configuration could look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pyenv\-deps:
pkg.installed:
\- pkgs:
\- make
\- build\-essential
\- libssl\-dev
\- zlib1g\-dev
\- libbz2\-dev
\- libreadline\-dev
\- libsqlite3\-dev
\- wget
\- curl
\- llvm
python\-2.6:
pyenv.absent:
\- require:
\- pkg: pyenv\-deps
python\-2.7.6:
pyenv.installed:
\- default: True
\- require:
\- pkg: pyenv\-deps
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pyenv.absent(name, runas=None, user=None)
Verify that the specified python is not installed with pyenv. pyenv
is installed if necessary.
.INDENT 7.0
.TP
.B name
The version of python to uninstall
.TP
.B runas: None
The user to run pyenv as.
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user to run pyenv as.
.sp
New in version 0.17.0.
.UNINDENT
.sp
New in version 0.16.0.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pyenv.install_pyenv(name, user=None)
Install pyenv if not installed. Allows you to require pyenv be installed
prior to installing the plugins. Useful if you want to install pyenv
plugins via the git or file modules and need them installed before
installing any rubies.
.sp
Use the pyenv.root configuration option to set the path for pyenv if you
want a system wide install that is not in a user home dir.
.INDENT 7.0
.TP
.B user: None
The user to run pyenv as.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pyenv.installed(name, default=False, runas=None, user=None)
Verify that the specified python is installed with pyenv. pyenv is
installed if necessary.
.INDENT 7.0
.TP
.B name
The version of python to install
.TP
.B default
False
Whether to make this python the default.
.TP
.B runas: None
The user to run pyenv as.
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user to run pyenv as.
.sp
New in version 0.17.0.
.UNINDENT
.sp
New in version 0.16.0.
.UNINDENT
.SS salt.states.quota
.SS Management of POSIX Quotas
.sp
The quota can be managed for the system:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/:
quota.mode:
mode: off
quotatype: user
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.quota.mode(name, mode, quotatype)
Set the quota for the system
.INDENT 7.0
.TP
.B name
The filesystem to set the quota mode on
.TP
.B mode
Whether the quota system is on or off
.TP
.B quotatype
Must be \fBuser\fP or \fBgroup\fP
.UNINDENT
.UNINDENT
.SS salt.states.rabbitmq_cluster
.SS Manage RabbitMQ Clusters
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rabbit@rabbit.example.com:
rabbitmq_cluster.join:
\- user: rabbit
\- host: rabbit.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_cluster.join(name, host, user=\(aqrabbit\(aq, runas=None)
Ensure the RabbitMQ plugin is enabled.
.INDENT 7.0
.TP
.B name
Irrelevant, not used (recommended: \fI\%user@host\fP)
.TP
.B user
The user to join the cluster as (default: rabbit)
.TP
.B host
The cluster host to join to
.TP
.B runas
The user to run the rabbitmq\-plugin command as
.UNINDENT
.UNINDENT
.SS salt.states.rabbitmq_plugin
.SS Manage RabbitMQ Plugins
.sp
New in version 2014.1.0.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
some_plugin:
rabbitmq_plugin.enabled: []
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_plugin.disabled(name, runas=None)
Ensure the RabbitMQ plugin is enabled.
.INDENT 7.0
.TP
.B name
The name of the plugin
.TP
.B runas
The user to run the rabbitmq\-plugin command as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_plugin.enabled(name, runas=None)
Ensure the RabbitMQ plugin is enabled.
.INDENT 7.0
.TP
.B name
The name of the plugin
.TP
.B runas
The user to run the rabbitmq\-plugin command as
.UNINDENT
.UNINDENT
.SS salt.states.rabbitmq_policy
.SS Manage RabbitMQ Policies
.INDENT 0.0
.TP
.B maintainer
Benn Eichhorn <\fI\%benn@getlocalmeasure.com\fP>
.TP
.B maturity
new
.TP
.B platform
all
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rabbit_policy:
rabbitmq_policy.present:
\- name: HA
\- pattern: \(aq.*\(aq
\- definition: \(aq{"ha\-mode": "all"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_policy.absent(name, vhost=\(aq/\(aq, runas=None)
Ensure the named policy is absent
.sp
Reference: \fI\%http://www.rabbitmq.com/ha.html\fP
.INDENT 7.0
.TP
.B name
The name of the policy to remove
.TP
.B runas
Name of the user to run the command as
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_policy.present(name, pattern, definition, priority=0, vhost=\(aq/\(aq, runas=None)
Ensure the RabbitMQ policy exists.
.sp
Reference: \fI\%http://www.rabbitmq.com/ha.html\fP
.INDENT 7.0
.TP
.B name
Policy name
.TP
.B pattern
A regex of queues to apply the policy to
.TP
.B definition
A json dict describing the policy
.TP
.B priority
Priority (defaults to 0)
.TP
.B vhost
Virtual host to apply to (defaults to \(aq/\(aq)
.TP
.B runas
Name of the user to run the command as
.UNINDENT
.UNINDENT
.SS salt.states.rabbitmq_user
.SS Manage RabbitMQ Users
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rabbit_user:
rabbitmq_user.present:
\- password: password
\- force: True
\- tags: administrator
\- perms:
\- \(aq/\(aq:
\- \(aq.*\(aq
\- \(aq.*\(aq
\- \(aq.*\(aq
\- runas: rabbitmq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_user.absent(name, runas=None)
Ensure the named user is absent
.INDENT 7.0
.TP
.B name
The name of the user to remove
.TP
.B runas
User to run the command
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_user.present(name, password=None, force=False, tags=None, perms=(), runas=None)
Ensure the RabbitMQ user exists.
.INDENT 7.0
.TP
.B name
User name
.TP
.B password
User\(aqs password, if one needs to be set
.TP
.B force
If user exists, forcibly change the password
.TP
.B tags
Optionally set user tags for user
.TP
.B perms
A list of dicts with vhost keys and 3\-tuple values
.TP
.B runas
Name of the user to run the command
.UNINDENT
.UNINDENT
.SS salt.states.rabbitmq_vhost
.SS Manage RabbitMQ Virtual Hosts
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virtual_host:
rabbitmq_vhost.present:
\- user: rabbit_user
\- conf: .*
\- write: .*
\- read: .*
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_vhost.absent(name, runas=None)
Ensure the RabbitMQ Virtual Host is absent
.INDENT 7.0
.TP
.B name
Name of the Virtual Host to remove
.TP
.B runas
User to run the command
.sp
Deprecated since version Beryllium.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rabbitmq_vhost.present(name, user=None, owner=None, conf=None, write=None, read=None, runas=None)
Ensure the RabbitMQ VHost exists.
.INDENT 7.0
.TP
.B name
VHost name
.TP
.B user
Initial user permission to set on the VHost, if present
.sp
Deprecated since version Beryllium.
.TP
.B owner
Initial owner permission to set on the VHost, if present
.TP
.B conf
Initial conf string to apply to the VHost and user. Defaults to .*
.TP
.B write
Initial write permissions to apply to the VHost and user.
Defaults to .*
.TP
.B read
Initial read permissions to apply to the VHost and user.
Defaults to .*
.TP
.B runas
Name of the user to run the command
.sp
Deprecated since version Beryllium.
.UNINDENT
.UNINDENT
.SS salt.states.rbenv
.SS Managing Ruby installations with rbenv
.sp
This module is used to install and manage ruby installations with rbenv.
Different versions of ruby can be installed, and uninstalled. Rbenv will
be installed automatically the first time it is needed and can be updated
later. This module will \fInot\fP automatically install packages which rbenv
will need to compile the versions of ruby.
.sp
If rbenv is run as the root user then it will be installed to /usr/local/rbenv,
otherwise it will be installed to the users ~/.rbenv directory. To make
rbenv available in the shell you may need to add the rbenv/shims and rbenv/bin
directories to the users PATH. If you are installing as root and want other
users to be able to access rbenv then you will need to add RBENV_ROOT to
their environment.
.sp
This is how a state configuration could look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rbenv\-deps:
pkg.installed:
\- pkgs:
\- bash
\- git
\- openssl
\- gmake
\- curl
ruby\-1.9.3\-p392:
rbenv.absent:
\- require:
\- pkg: rbenv\-deps
ruby\-1.9.3\-p429:
rbenv.installed:
\- default: True
\- require:
\- pkg: rbenv\-deps
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rbenv.absent(name, runas=None, user=None)
Verify that the specified ruby is not installed with rbenv. Rbenv
is installed if necessary.
.INDENT 7.0
.TP
.B name
The version of ruby to uninstall
.TP
.B runas: None
The user to run rbenv as.
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user to run rbenv as.
.sp
New in version 0.17.0.
.UNINDENT
.sp
New in version 0.16.0.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rbenv.install_rbenv(name, user=None)
Install rbenv if not installed. Allows you to require rbenv be installed
prior to installing the plugins. Useful if you want to install rbenv
plugins via the git or file modules and need them installed before
installing any rubies.
.sp
Use the rbenv.root configuration option to set the path for rbenv if you
want a system wide install that is not in a user home dir.
.INDENT 7.0
.TP
.B user: None
The user to run rbenv as.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rbenv.installed(name, default=False, runas=None, user=None)
Verify that the specified ruby is installed with rbenv. Rbenv is
installed if necessary.
.INDENT 7.0
.TP
.B name
The version of ruby to install
.TP
.B default
False
Whether to make this ruby the default.
.TP
.B runas: None
The user to run rbenv as.
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user to run rbenv as.
.sp
New in version 0.17.0.
.UNINDENT
.sp
New in version 0.16.0.
.UNINDENT
.SS salt.states.rdp
.sp
Manage RDP Service on Windows servers
.INDENT 0.0
.TP
.B salt.states.rdp.disabled(name)
Disable the RDP service
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rdp.enabled(name)
Enable the RDP service and make sure access to the RDP
port is allowed in the firewall configuration
.UNINDENT
.SS salt.states.redismod
.SS Management of Redis server
.sp
New in version 2014.7.0.
.INDENT 0.0
.TP
.B depends
.INDENT 7.0
.IP \(bu 2
redis Python module
.UNINDENT
.TP
.B configuration
See \fBsalt.modules.redis\fP for setup instructions.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
key_in_redis:
redis.string:
\- value: string data
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The redis server information specified in the minion config file can be
overidden in states using the following arguments: \fBhost\fP, \fBpost\fP, \fBdb\fP,
\fBpassword\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
key_in_redis:
redis.string:
\- value: string data
\- host: localhost
\- port: 6379
\- db: 0
\- password: somuchkittycat
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.redismod.absent(name, keys=None, **connection_args)
Ensure key absent from redis
.INDENT 7.0
.TP
.B name
Key to ensure absent from redis
.TP
.B keys
list of keys to ensure absent, name will be ignored if this is used
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.redismod.string(name, value, expire=None, expireat=None, **connection_args)
Ensure that the key exists in redis with the value specified
.INDENT 7.0
.TP
.B name
Redis key to manage
.TP
.B value
Data to persist in key
.TP
.B expire
Sets time to live for key in seconds
.TP
.B expireat
Sets expiration time for key via UNIX timestamp, overrides \fIexpire\fP
.UNINDENT
.UNINDENT
.SS salt.states.reg
.sp
Manage the registry on Windows
.INDENT 0.0
.TP
.B salt.states.reg.absent(name)
Remove a registry key
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqHKEY_CURRENT_USER\eSOFTWARE\eSalt\eversion\(aq:
reg.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.reg.present(name, value, vtype=\(aqREG_DWORD\(aq, reflection=True)
Set a registry entry
.sp
Optionally set \fBreflection\fP to \fBFalse\fP to disable reflection.
\fBreflection\fP has no effect on a 32\-bit OS.
.sp
In the example below, this will prevent Windows from silently creating
the key in:
\fBHKEY_CURRENT_USER\eSOFTWARE\eWow6432Node\eSalt\eversion\fP
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
HKEY_CURRENT_USER\eSOFTWARE\eSalt\eversion:
reg.present:
\- value: 0.15.3
\- vtype: REG_SZ
\- reflection: False
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.rvm
.SS Managing Ruby installations and gemsets with Ruby Version Manager (RVM)
.sp
This module is used to install and manage ruby installations and
gemsets with RVM, the Ruby Version Manager. Different versions of ruby
can be installed and gemsets created. RVM itself will be installed
automatically if it\(aqs not present. This module will not automatically
install packages that RVM depends on or ones that are needed to build
ruby. If you want to run RVM as an unprivileged user (recommended) you
will have to create this user yourself. This is how a state
configuration could look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rvm:
group.present: []
user.present:
\- gid: rvm
\- home: /home/rvm
\- require:
\- group: rvm
rvm\-deps:
pkg.installed:
\- pkgs:
\- bash
\- coreutils
\- gzip
\- bzip2
\- gawk
\- sed
\- curl
\- git\-core
\- subversion
mri\-deps:
pkg.installed:
\- pkgs:
\- build\-essential
\- openssl
\- libreadline6
\- libreadline6\-dev
\- curl
\- git\-core
\- zlib1g
\- zlib1g\-dev
\- libssl\-dev
\- libyaml\-dev
\- libsqlite3\-0
\- libsqlite3\-dev
\- sqlite3
\- libxml2\-dev
\- libxslt1\-dev
\- autoconf
\- libc6\-dev
\- libncurses5\-dev
\- automake
\- libtool
\- bison
\- subversion
\- ruby
jruby\-deps:
pkg.installed:
\- pkgs:
\- curl
\- g++
\- openjdk\-6\-jre\-headless
ruby\-1.9.2:
rvm.installed:
\- default: True
\- user: rvm
\- require:
\- pkg: rvm\-deps
\- pkg: mri\-deps
\- user: rvm
jruby:
rvm.installed:
\- user: rvm
\- require:
\- pkg: rvm\-deps
\- pkg: jruby\-deps
\- user: rvm
jgemset:
rvm.gemset_present:
\- ruby: jruby
\- user: rvm
\- require:
\- rvm: jruby
mygemset:
rvm.gemset_present:
\- ruby: ruby\-1.9.2
\- user: rvm
\- require:
\- rvm: ruby\-1.9.2
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rvm.gemset_present(name, ruby=\(aqdefault\(aq, runas=None, user=None)
Verify that the gemset is present.
.INDENT 7.0
.TP
.B name
The name of the gemset.
.TP
.B ruby: default
The ruby version this gemset belongs to.
.TP
.B runas: None
The user to run rvm as.
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user to run rvm as.
.sp
New in version 0.17.0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.rvm.installed(name, default=False, runas=None, user=None)
Verify that the specified ruby is installed with RVM. RVM is
installed when necessary.
.INDENT 7.0
.TP
.B name
The version of ruby to install
.TP
.B default
False
Whether to make this ruby the default.
.TP
.B runas: None
The user to run rvm as.
.sp
Deprecated since version 0.17.0.
.TP
.B user: None
The user to run rvm as.
.sp
New in version 0.17.0.
.UNINDENT
.UNINDENT
.SS salt.states.saltmod
.SS Control the Salt command interface
.sp
This state is intended for use from the Salt Master. It provides access to
sending commands down to minions as well as access to executing master\-side
modules. These state functions wrap Salt\(aqs \fIPython API\fP\&.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
More Orchestrate documentation
.INDENT 0.0
.IP \(bu 2
\fIFull Orchestrate Tutorial\fP
.IP \(bu 2
\fBThe Orchestrate runner\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.saltmod.function(name, tgt, ssh=False, tgt_type=None, expr_form=None, ret=\(aq\(aq, expect_minions=False, fail_minions=None, fail_function=None, arg=None, kwarg=None, timeout=None)
Execute a single module function on a remote minion via salt or salt\-ssh
.INDENT 7.0
.TP
.B name
The name of the function to run, aka cmd.run or pkg.install
.TP
.B tgt
The target specification, aka \(aq*\(aq for all minions
.TP
.B tgt_type | expr_form
The target type, defaults to glob
.TP
.B arg
The list of arguments to pass into the function
.TP
.B kwarg
The list of keyword arguments to pass into the function
.TP
.B ret
Optionally set a single or a list of returners to use
.TP
.B expect_minions
An optional boolean for failing if some minions do not respond
.TP
.B fail_minions
An optional list of targeted minions where failure is an option
.TP
.B fail_function
An optional string that points to a salt module that returns True or False
based on the returned data dict for individual minions
.TP
.B ssh
Set to \fITrue\fP to use the ssh client instaed of the standard salt client
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.saltmod.runner(name, **kwargs)
Execute a runner module on the master
.sp
New in version 2014.7.
.INDENT 7.0
.TP
.B name
The name of the function to run
.TP
.B kwargs
Any keyword arguments to pass to the runner function
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.saltmod.state(name, tgt, ssh=False, tgt_type=None, expr_form=None, ret=\(aq\(aq, highstate=None, sls=None, top=None, env=None, test=False, pillar=None, expect_minions=False, fail_minions=None, allow_fail=0, concurrent=False, timeout=None)
Invoke a state run on a given target
.INDENT 7.0
.TP
.B name
An arbitrary name used to track the state execution
.TP
.B tgt
The target specification for the state run.
.TP
.B tgt_type | expr_form
The target type to resolve, defaults to glob
.TP
.B ret
Optionally set a single or a list of returners to use
.TP
.B highstate
Defaults to None, if set to True the target systems will ignore any
sls references specified in the sls option and call state.highstate
on the targeted minions
.TP
.B top
Should be the name of a top file. If set state.top is called with this
top file instead of state.sls.
.TP
.B sls
A group of sls files to execute. This can be defined as a single string
containing a single sls file, or a list of sls files
.TP
.B test
Pass \fBtest=true\fP through to the state function
.TP
.B pillar
Pass the \fBpillar\fP kwarg through to the state function
.TP
.B saltenv
The default salt environment to pull sls files from
.TP
.B ssh
Set to \fITrue\fP to use the ssh client instaed of the standard salt client
.TP
.B roster
In the event of using salt\-ssh, a roster system can be set
.TP
.B expect_minions
An optional boolean for failing if some minions do not respond
.TP
.B fail_minions
An optional list of targeted minions where failure is an option
.TP
.B allow_fail
Pass in the number of minions to allow for failure before setting
the result of the execution to False
.TP
.B concurrent
Allow multiple state runs to occur at once.
.sp
WARNING: This flag is potentially dangerous. It is designed
for use when multiple state runs can safely be run at the same
Do not use this flag for performance optimization.
.UNINDENT
.sp
Examples:
.sp
Run a list of sls files via \fBstate.sls\fP on target
minions:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
webservers:
salt.state:
\- tgt: \(aqweb*\(aq
\- sls:
\- apache
\- django
\- core
\- saltenv: prod
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Run a full \fBstate.highstate\fP on target
mininons.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
databases:
salt.state:
\- tgt: role:database
\- tgt_type: grain
\- highstate: True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.saltmod.wait_for_event(name, id_list, event_id=\(aqid\(aq, timeout=300)
Watch Salt\(aqs event bus and block until a condition is met
.sp
New in version 2014.7.
.INDENT 7.0
.TP
.B name
An event tag to watch for; supports Reactor\-style globbing.
.TP
.B id_list
A list of event identifiers to watch for \-\- usually the minion ID. Each
time an event tag is matched the event data is inspected for
\fBevent_id\fP, if found it is removed from \fBid_list\fP\&. When \fBid_list\fP
is empty this function returns success.
.TP
.B event_id
id
The name of a key in the event data. Default is \fBid\fP for the minion
ID, another common value is \fBname\fP for use with orchestrating
salt\-cloud events.
.TP
.B timeout
300
The maximum time in seconds to wait before failing.
.UNINDENT
.sp
The following example blocks until all the listed minions complete a
restart and reconnect to the Salt master:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
reboot_all_minions:
salt.function:
\- name: system.reboot
\- tgt: \(aq*\(aq
wait_for_reboots:
salt.wait_for_event:
\- name: salt/minion/*/start
\- id_list:
\- jerry
\- stuart
\- dave
\- phil
\- kevin
\- mike
\- require:
\- salt: reboot_all_minions
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.saltmod.wheel(name, **kwargs)
Execute a wheel module on the master
.sp
New in version 2014.7.
.INDENT 7.0
.TP
.B name
The name of the function to run
.TP
.B kwargs
Any keyword arguments to pass to the wheel function
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
accept_minion_key:
salt.wheel:
\- name: key.accept
\- match: frank
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.schedule
.SS Management of the Salt scheduler
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
job3:
schedule.present:
\- function: test.ping
\- seconds: 3600
\- splay: 10
This will schedule the command: test.ping every 3600 seconds
(every hour) splaying the time between 0 and 10 seconds
job2:
schedule.present:
\- function: test.ping
\- seconds: 15
\- splay:
\- start: 10
\- end: 20
This will schedule the command: test.ping every 3600 seconds
(every hour) splaying the time between 10 and 20 seconds
job1:
schedule.present:
\- function: state.sls
\- job_args:
\- httpd
\- job_kwargs:
test: True
\- when:
\- Monday 5:00pm
\- Tuesday 3:00pm
\- Wednesday 5:00pm
\- Thursday 3:00pm
\- Friday 5:00pm
This will schedule the command: state.sls httpd test=True at 5pm on Monday,
Wednesday and Friday, and 3pm on Tuesday and Thursday.
job1:
schedule.present:
\- function: state.sls
\- job_args:
\- httpd
\- job_kwargs:
test: True
\- cron: \(aq*/5 * * * *\(aq
Scheduled jobs can also be specified using the format used by cron. This will
schedule the command: state.sls httpd test=True to run every 5 minutes. Requires
that python\-croniter is installed.
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.schedule.absent(name, **kwargs)
Ensure a job is absent from the schedule
.INDENT 7.0
.TP
.B name
The unique name that is given to the scheduled job.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.schedule.present(name, **kwargs)
Ensure a job is present in the schedule
.INDENT 7.0
.TP
.B name
The unique name that is given to the scheduled job.
.TP
.B seconds
The scheduled job will be executed after the specified
number of seconds have passed.
.TP
.B minutes
The scheduled job will be executed after the specified
number of minutes have passed.
.TP
.B hours
The scheduled job will be executed after the specified
number of hours have passed.
.TP
.B days
The scheduled job will be executed after the specified
number of days have passed.
.TP
.B when
This will schedule the job at the specified time(s).
The when parameter must be a single value or a dictionary
with the date string(s) using the dateutil format.
.TP
.B cron
This will schedule the job at the specified time(s)
using the crontab format.
.TP
.B function
The function that should be executed by the scheduled job.
.TP
.B job_args
The arguments that will be used by the scheduled job.
.TP
.B job_kwargs
The keyword arguments that will be used by the scheduled job.
.TP
.B maxrunning
Ensure that there are no more than N copies of a particular job running.
.TP
.B jid_include
Include the job into the job cache.
.TP
.B splay
The amount of time in seconds to splay a scheduled job.
Can be specified as a single value in seconds or as a dictionary
range with \(aqstart\(aq and \(aqend\(aq values.
.TP
.B range
This will schedule the command within the range specified.
The range parameter must be a dictionary with the date strings
using the dateutil format.
.UNINDENT
.UNINDENT
.SS salt.states.selinux
.SS Management of SELinux rules
.sp
If SELinux is available for the running system, the mode can be managed and
booleans can be set.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
enforcing:
selinux.mode
samba_create_home_dirs:
selinux.boolean:
\- value: True
\- persist: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Use of these states require that the \fBselinux\fP
execution module is available.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.selinux.boolean(name, value, persist=False)
Set up an SELinux boolean
.INDENT 7.0
.TP
.B name
The name of the boolean to set
.TP
.B value
The value to set on the boolean
.TP
.B persist
Defaults to False, set persist to true to make the boolean apply on a
reboot
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.selinux.mode(name)
Verifies the mode SELinux is running in, can be set to enforcing or
permissive
.INDENT 7.0
.TP
.B name
The mode to run SELinux in, permissive or enforcing
.UNINDENT
.UNINDENT
.SS salt.states.serverdensity_device
.SS Monitor Server with Server Density
.sp
New in version 2014.7.0.
.sp
\fI\%Server Density\fP
Is a hosted monitoring service.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
This state module is beta. It might be changed later to include more or
less automation.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This state module requires a pillar for authentication with Server Density:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
serverdensity:
api_token: "b97da80a41c4f61bff05975ee51eb1aa"
account_url: "https://your\-account.serverdensity.io"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Although Server Density allows duplicate device names in its database, this
module will raise an exception if you try monitoring devices with the same
name.
.UNINDENT
.UNINDENT
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqserver_name\(aq:
serverdensity_device.monitored
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.serverdensity_device.monitored(name, group=None, salt_name=True, salt_params=True, **params)
Device is monitored with Server Density.
.INDENT 7.0
.TP
.B name
Device name in Server Density.
.TP
.B salt_name
If \fBTrue\fP (default), takes the name from the \fBid\fP grain. If
\fBFalse\fP, the provided name is used.
.TP
.B group
Group name under with device will appear in Server Density dashboard.
Default \- \fINone\fP\&.
.TP
.B salt_params
If \fBTrue\fP (default), needed config parameters will be sourced from
grains and from \fBstatus.all_status\fP\&.
.TP
.B params
Add parameters that you want to appear in the Server Density dashboard.
Will overwrite the \fIsalt_params\fP parameters. For more info, see the
\fI\%API docs\fP\&.
.UNINDENT
.sp
Usage example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqserver_name\(aq:
serverdensity_device.monitored
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqserver_name\(aq:
serverdensity_device.monitored:
\- group: web\-servers
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqmy_special_server\(aq:
serverdensity_device.monitored:
\- salt_name: False
\- group: web\-servers
\- cpuCores: 2
\- os: CentOS
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.service
.SS Starting or restarting of services and daemons
.sp
Services are defined as system daemons typically started with system init or
rc scripts, services can be defined as running or dead.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
service.running: []
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The service can also be set to be started at runtime via the enable option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
openvpn:
service.running:
\- enable: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default if a service is triggered to refresh due to a watch statement the
service is by default restarted. If the desired behavior is to reload the
service, then set the reload value to True:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
redis:
service.running:
\- enable: True
\- reload: True
\- watch:
\- pkg: redis
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
More details regarding \fBwatch\fP can be found in the
\fBRequisites\fP documentation.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.service.dead(name, enable=None, sig=None, **kwargs)
Ensure that the named service is dead by stopping the service if it 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, \fBTrue\fP sets the service
to be enabled, \fBFalse\fP sets the named service to be disabled. The
default is \fBNone\fP, 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.disabled(name, **kwargs)
Verify that the service is disabled on boot, only use this state if you
don\(aqt want to manage the running process, remember that if you want to
disable a service to use the enable: False option for the running or dead
function.
.INDENT 7.0
.TP
.B name
The name of the init or rc script used to manage the service
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.service.enabled(name, **kwargs)
Verify that the service is enabled on boot, only use this state if you
don\(aqt want to manage the running process, remember that if you want to
enable a running service to use the enable: True option for the running
or dead function.
.INDENT 7.0
.TP
.B name
The name of the init or rc script used to manage the service
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.service.mod_watch(name, sfun=None, sig=None, reload=False, full_restart=False)
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 sfun
The original function which triggered the mod_watch call
(\fIservice.running\fP, for example).
.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, **kwargs)
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
.SS salt.states.smtp
.SS Sending Messages via SMTP
.sp
New in version 2014.7.0.
.sp
This state is useful for firing messages during state runs, using the XMPP
protocol
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server\-warning\-message:
smtp.send_msg:
\- name: \(aqThis is a server warning message\(aq
\- profile: my\-smtp\-account
\- recipient: admins@example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.smtp.send_msg(name, recipient, subject, sender, profile, use_ssl=\(aqTrue\(aq)
Send a message via SMTP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
server\-warning\-message:
smtp.send_msg:
\- name: \(aqThis is a server warning message\(aq
\- profile: my\-smtp\-account
\- subject: \(aqMessage from Salt\(aq
\- recipient: admin@example.com
\- sender: admin@example.com
\- use_ssl: True
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
The message to send via SMTP
.UNINDENT
.UNINDENT
.SS salt.states.ssh_auth
.SS Control of entries in SSH authorized_key files
.sp
The information stored in a user\(aqs SSH authorized key file can be easily
controlled via the ssh_auth state. Defaults can be set by the enc, options,
and comment keys. These defaults can be overridden by including them in the
name.
.sp
Since the YAML specification limits the length of simple keys to 1024
characters, and since SSH keys are often longer than that, you may have
to use a YAML \(aqexplicit key\(aq, as demonstrated in the second example below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==:
ssh_auth.present:
\- user: root
\- enc: ssh\-dss
? AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==...
:
ssh_auth.present:
\- user: root
\- enc: ssh\-dss
thatch:
ssh_auth.present:
\- user: root
\- source: salt://ssh_keys/thatch.id_rsa.pub
sshkeys:
ssh_auth.present:
\- user: root
\- enc: ssh\-rsa
\- options:
\- option1="value1"
\- option2="value2 flag2"
\- comment: myuser
\- names:
\- AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==
\- ssh\-dss AAAAB3NzaCL0sQ9fJ5bYTEyY== user@domain
\- option3="value3" ssh\-dss AAAAB3NzaC1kcQ9J5bYTEyY== other@testdomain
\- AAAAB3NzaC1kcQ9fJFF435bYTEyY== newcomment
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ssh_auth.absent(name, user, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, options=None, 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 enc
Defines what type of key is being used; can be ed25519, ecdsa, 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
.INDENT 0.0
.TP
.B salt.states.ssh_auth.present(name, user, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, source=\(aq\(aq, options=None, config=\(aq.ssh/authorized_keys\(aq, **kwargs)
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 ed25519, ecdsa, ssh\-rsa
or ssh\-dss
.TP
.B comment
The comment to be placed with the SSH public key
.TP
.B source
The source file for the key(s). Can contain any number of public keys,
in standard "authorized_keys" format. If this is set, comment, enc,
and options will be ignored.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The source file must contain keys in the format \fB<enc> <key>
<comment>\fP\&. If you have generated a keypair using PuTTYgen, then you
will need to do the following to retrieve an OpenSSH\-compatible public
key.
.INDENT 0.0
.IP 1. 3
In PuTTYgen, click \fBLoad\fP, and select the \fIprivate\fP key file (not
the public key), and click \fBOpen\fP\&.
.IP 2. 3
Copy the public key from the box labeled \fBPublic key for pasting
into OpenSSH authorized_keys file\fP\&.
.IP 3. 3
Paste it into a new file.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.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.ssh_known_hosts
.SS Control of SSH known_hosts entries
.sp
Manage the information stored in the known_hosts files.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
github.com:
ssh_known_hosts:
\- present
\- user: root
\- fingerprint: 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48
example.com:
ssh_known_hosts:
\- absent
\- user: root
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ssh_known_hosts.absent(name, user=None, config=None)
Verifies that the specified host is not known by the given user
.INDENT 7.0
.TP
.B name
The host name
.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/known_hosts". If no user is specified,
defaults to "/etc/ssh/ssh_known_hosts". If present, must be an
absolute path when a user is not specified.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.ssh_known_hosts.present(name, user=None, fingerprint=None, key=None, port=None, enc=None, config=None, hash_hostname=True)
Verifies that the specified host is known by the specified user
.sp
On many systems, specifically those running with openssh 4 or older, the
\fBenc\fP option must be set, only openssh 5 and above can detect the key
type.
.INDENT 7.0
.TP
.B name
The name of the remote host (e.g. "github.com")
.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 ed25519, ecdsa ssh\-rsa
or ssh\-dss
.TP
.B fingerprint
The fingerprint of the key which must be presented in the known_hosts
file
.TP
.B port
optional parameter, denoting the port of the remote host, which will be
used in case, if the public key will be requested from it. By default
the port 22 is used.
.TP
.B config
The location of the authorized keys file relative to the user\(aqs home
directory, defaults to ".ssh/known_hosts". If no user is specified,
defaults to "/etc/ssh/ssh_known_hosts". If present, must be an
absolute path when a user is not specified.
.TP
.B hash_hostname
True
Hash all hostnames and addresses in the output.
.UNINDENT
.UNINDENT
.SS salt.states.stateconf
.SS Stateconf System
.sp
The stateconf system is intended for use only with the stateconf renderer. This
State module presents the set function. This function does not execute any
functionality, but is used to interact with the stateconf renderer.
.INDENT 0.0
.TP
.B salt.states.stateconf.context(name, **kwargs)
No\-op state to support state config via the stateconf renderer.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.stateconf.set(name, **kwargs)
No\-op state to support state config via the stateconf renderer.
.UNINDENT
.SS salt.states.status
.sp
Minion status monitoring
.sp
Maps to the \fIstatus\fP execution module.
.INDENT 0.0
.TP
.B salt.states.status.loadavg(name, maximum=None, minimum=None)
Return the current load average for the specified minion. Available values
for name are \fI1\-min\fP, \fI5\-min\fP and \fI15\-min\fP\&. \fIminimum\fP and \fImaximum\fP values
should be passed in as strings.
.UNINDENT
.SS salt.states.supervisord
.SS Interaction with the Supervisor daemon
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wsgi_server:
supervisord.running:
\- require:
\- pkg: supervisor
\- watch:
\- file: /etc/nginx/sites\-enabled/wsgi_server.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.supervisord.dead(name, user=None, runas=None, conf_file=None, bin_env=None)
Ensure the named service is dead (not running).
.INDENT 7.0
.TP
.B name
Service name as defined in the supervisor configuration file
.TP
.B runas
Name of the user to run the supervisorctl command
.sp
Deprecated since version 0.17.0.
.TP
.B user
Name of the user to run the supervisorctl command
.sp
New in version 0.17.0.
.TP
.B conf_file
path to supervisorctl config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.supervisord.mod_watch(name, restart=True, update=False, user=None, runas=None, conf_file=None, bin_env=None)
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.supervisord.running(name, restart=False, update=False, user=None, runas=None, conf_file=None, bin_env=None)
Ensure the named service is running.
.INDENT 7.0
.TP
.B name
Service name as defined in the supervisor configuration file
.TP
.B restart
Whether to force a restart
.TP
.B update
Whether to update the supervisor configuration.
.TP
.B runas
Name of the user to run the supervisorctl command
.sp
Deprecated since version 0.17.0.
.TP
.B user
Name of the user to run the supervisorctl command
.sp
New in version 0.17.0.
.TP
.B conf_file
path to supervisorctl config file
.TP
.B bin_env
path to supervisorctl bin or path to virtualenv with supervisor
installed
.UNINDENT
.UNINDENT
.SS salt.states.svn
.SS Manage SVN repositories
.sp
Manage repository checkouts via the svn vcs system:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
http://unladen\-swallow.googlecode.com/svn/trunk/:
svn.latest:
\- target: /tmp/swallow
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.svn.dirty(name, target, user=None, username=None, password=None, ignore_unversioned=False)
Determine if the working directory has been changed.
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.svn.export(name, target=None, rev=None, user=None, username=None, password=None, force=False, overwrite=False, externals=True, trust=False)
Export a file or directory from an SVN repository
.INDENT 7.0
.TP
.B name
Address and path to the file or directory to be exported.
.TP
.B target
Name of the target directory where the checkout will put the working
directory
.TP
.B rev
None
The name revision number to checkout. Enable "force" if the directory
already exists.
.TP
.B user
None
Name of the user performing repository management operations
.TP
.B username
None
The user to access the name repository with. The svn default is the
current user
.TP
.B password
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.TP
.B force
False
Continue if conflicts are encountered
.TP
.B overwrite
False
Overwrite existing target
.TP
.B externals
True
Change to False to not checkout or update externals
.TP
.B trust
False
Automatically trust the remote server. SVN\(aqs \-\-trust\-server\-cert
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.svn.latest(name, target=None, rev=None, user=None, username=None, password=None, force=False, externals=True, trust=False)
Checkout or update the working directory to the latest revision from the
remote repository.
.INDENT 7.0
.TP
.B name
Address of the name repository as passed to "svn checkout"
.TP
.B target
Name of the target directory where the checkout will put the working
directory
.TP
.B rev
None
The name revision number to checkout. Enable "force" if the directory
already exists.
.TP
.B user
None
Name of the user performing repository management operations
.TP
.B username
None
The user to access the name repository with. The svn default is the
current user
.TP
.B password
Connect to the Subversion server with this password
.sp
New in version 0.17.0.
.TP
.B force
False
Continue if conflicts are encountered
.TP
.B externals
True
Change to False to not checkout or update externals
.TP
.B trust
False
Automatically trust the remote server. SVN\(aqs \-\-trust\-server\-cert
.UNINDENT
.UNINDENT
.SS salt.states.sysctl
.SS Configuration of the Linux kernel using sysctl
.sp
Control the kernel sysctl system.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vm.swappiness:
sysctl.present:
\- value: 20
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.sysctl.present(name, value, config=None)
Ensure that the named sysctl value is set in memory and persisted to the
named configuration file. The default sysctl configuration file is
/etc/sysctl.conf
.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. If not specified, the
proper location will be detected based on platform.
.UNINDENT
.UNINDENT
.SS salt.states.test
.SS Test States
.INDENT 0.0
.TP
.B Provide test case states that enable easy testing of things to do with
state calls, e.g. running, calling, logging, output filtering etc.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
always\-passes:
test.succeed_without_changes:
\- name: foo
always\-fails:
test.fail_without_changes:
\- name: foo
always\-changes\-and\-succeeds:
test.succeed_with_changes:
\- name: foo
always\-changes\-and\-fails:
test.fail_with_changes:
\- name: foo
my\-custom\-combo:
test.configurable_test_state:
\- name: foo
\- changes: True
\- result: False
\- comment: bar.baz
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.test.configurable_test_state(name, changes=True, result=True, comment=\(aq\(aq)
A configurable test state which determines its output based on the inputs.
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B name:
A unique string.
.TP
.B changes:
Do we return anything in the changes field?
Accepts True, False, and \(aqRandom\(aq
Default is True
.TP
.B result:
Do we return successfully or not?
Accepts True, False, and \(aqRandom\(aq
Default is True
.TP
.B comment:
String to fill the comment field with.
Default is \(aq\(aq
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.test.fail_with_changes(name)
Returns failure and changes is not empty.
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B name:
A unique string.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.test.fail_without_changes(name)
Returns failure.
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B name:
A unique string.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.test.mod_watch(name, sfun=None, **kwargs)
\(aq
Call this function via a watch statement
.sp
New in version 2014.7.0.
.sp
Any parameters in the state return dictionary can be customized by adding
the keywords \fBresult\fP, \fBcomment\fP, and \fBchanges\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
this_state_will_return_changes:
test.succeed_with_changes
this_state_will_NOT_return_changes:
test.succeed_without_changes
this_state_is_watching_another_state:
test.succeed_without_changes:
\- comment: \(aqThis is a custom comment\(aq
\- watch:
\- test: this_state_will_return_changes
\- test: this_state_will_NOT_return_changes
this_state_is_also_watching_another_state:
test.succeed_without_changes:
\- watch:
\- test: this_state_will_NOT_return_changes
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.test.succeed_with_changes(name)
Returns successful and changes is not empty
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B name:
A unique string.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.test.succeed_without_changes(name)
Returns successful.
.sp
New in version 2014.7.0.
.INDENT 7.0
.TP
.B name
A unique string.
.UNINDENT
.UNINDENT
.SS salt.states.timezone
.SS Management of timezones
.sp
The timezone can be managed for the system:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
America/Denver:
timezone.system
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The system and the hardware clock are not necessarily set to the same time.
By default, the hardware clock is set to localtime, meaning it is set to the
same time as the system clock. If \fIutc\fP is set to True, then the hardware clock
will be set to UTC, and the system clock will be an offset of that.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
America/Denver:
timezone.system:
\- utc: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Ubuntu community documentation contains an explanation of this setting, as
it applies to systems that dual\-boot with Windows. This is explained in greater
detail \fI\%here\fP\&.
.INDENT 0.0
.TP
.B salt.states.timezone.system(name, utc=True)
Set the timezone for the system.
.INDENT 7.0
.TP
.B name
The name of the timezone to use (e.g.: America/Denver)
.TP
.B utc
Whether or not to set the hardware clock to UTC (default is True)
.UNINDENT
.UNINDENT
.SS salt.states.tomcat
.sp
This state uses the manager webapp to manage Apache tomcat webapps
This state requires the manager webapp to be enabled
.sp
The following grains/pillar should be set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tomcat\-manager:user: admin user name
tomcat\-manager:passwd: password
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and also configure a user in the conf/tomcat\-users.xml file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<?xml version=\(aq1.0\(aq encoding=\(aqutf\-8\(aq?>
<tomcat\-users>
<role rolename="manager\-script"/>
<user username="tomcat" password="tomcat" roles="manager\-script"/>
</tomcat\-users>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notes:
.INDENT 0.0
.IP \(bu 2
Not supported multiple version on the same context path
.IP \(bu 2
.INDENT 2.0
.TP
.B More information about tomcat manager:
\fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html\fP
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B if you use only this module for deployments you might want to restrict
access to the manager so its only accessible via localhost
for more info: \fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/manager\-howto.html#Configuring_Manager_Application_Access\fP
.UNINDENT
.IP \(bu 2
Tested on:
.INDENT 2.0
.TP
.B JVM Vendor:
Sun Microsystems Inc.
.TP
.B JVM Version:
1.6.0_43\-b01
.TP
.B OS Architecture:
amd64
.TP
.B OS Name:
Linux
.TP
.B OS Version:
2.6.32\-358.el6.x86_64
.TP
.B Tomcat Version:
Apache Tomcat/7.0.37
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.tomcat.mod_watch(name, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
The tomcat watcher function.
When called it will reload the webapp in question
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.tomcat.undeployed(name, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Enforce that the WAR will be un\-deployed from the server
.INDENT 7.0
.TP
.B name
the context path to deploy
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request to the tomcat manager
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
jenkins:
tomcat.undeployed:
\- name: /ran
\- require:
\- service: application\-service
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.tomcat.wait(name, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
Wait for the tomcat manager to load
.sp
Notice that if tomcat is not running we won\(aqt wait for it start and the
state will fail. This state can be required in the tomcat.war_deployed
state to make sure tomcat is running and that the manager is running as
well and ready for deployment
.INDENT 7.0
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request to the tomcat manager
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
tomcat\-service:
service.running:
\- name: tomcat
\- enable: True
wait\-for\-tomcatmanager:
tomcat.wait:
\- timeout: 300
\- require:
\- service: tomcat\-service
jenkins:
tomcat.war_deployed:
\- name: /ran
\- war: salt://jenkins\-1.2.4.war
\- require:
\- tomcat: wait\-for\-tomcatmanager
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.tomcat.war_deployed(name, war, force=False, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180, temp_war_location=None)
Enforce that the WAR will be deployed and started in the context path
it will make use of WAR versions
.INDENT 7.0
.TP
.B for more info:
\fI\%http://tomcat.apache.org/tomcat\-7.0\-doc/config/context.html#Naming\fP
.TP
.B name
the context path to deploy
.TP
.B war
absolute path to WAR file (should be accessible by the user running
tomcat) or a path supported by the salt.modules.cp.get_url function
.TP
.B force
force deploy even if version strings are the same, False by default.
.TP
.B url
\fI\%http://localhost:8080/manager\fP
the URL of the server manager webapp
.TP
.B timeout
180
timeout for HTTP request to the tomcat manager
.TP
.B temp_war_location
None
use another location to temporarily copy to war file
by default the system\(aqs temp directory is used
.UNINDENT
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
jenkins:
tomcat.war_deployed:
\- name: /ran
\- war: salt://jenkins\-1.2.4.war
\- require:
\- service: application\-service
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.user
.SS Management of user accounts
.sp
The user module is used to create and manage user settings, users can be set
as either absent or present
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
fred:
user.present:
\- fullname: Fred Jones
\- shell: /bin/zsh
\- home: /home/fred
\- uid: 4000
\- gid: 4000
\- groups:
\- wheel
\- storage
\- games
testuser:
user.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.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 files 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. Not
supported in FreeBSD and Solaris.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.user.present(name, uid=None, gid=None, gid_from_name=False, groups=None, optional_groups=None, remove_groups=True, home=None, createhome=True, password=None, enforce_password=True, empty_password=False, shell=None, unique=True, system=False, fullname=None, roomnumber=None, workphone=None, homephone=None, date=None, mindays=None, maxdays=None, inactdays=None, warndays=None, expire=None)
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 gid_from_name
If True, the default group id will be set to the id of the group with
the same name as the user.
.TP
.B groups
A list of groups to assign the user to, pass a list object. If a group
specified here does not exist on the minion, the state will fail.
If set to the empty list, the user will be removed from all groups
except the default group.
.TP
.B optional_groups
A list of groups to assign the user to, pass a list object. If a group
specified here does not exist on the minion, the state will silently
ignore it.
.UNINDENT
.sp
NOTE: If the same group is specified in both "groups" and
"optional_groups", then it will be assumed to be required and not optional.
.INDENT 7.0
.TP
.B remove_groups
Remove groups that the user is a member of that weren\(aqt specified in
the state, True by default
.TP
.B home
The location of the home directory to manage
.TP
.B createhome
If True, the home directory will be created if it doesn\(aqt exist.
Please note that directories leading up to the home directory
will NOT be created.
.TP
.B password
A password hash to set for the user. This field is only supported on
Linux, FreeBSD, NetBSD, OpenBSD, and Solaris.
.UNINDENT
.sp
Changed in version 0.16.0: BSD support added.
.INDENT 7.0
.TP
.B enforce_password
Set to False to keep the password from being changed if it has already
been set and the password hash differs from what is specified in the
"password" field. This option will be ignored if "password" is not
specified.
.TP
.B empty_password
Set to True to enable no password\-less login for user
.TP
.B shell
The login shell, defaults to the system default shell
.TP
.B unique
Require a unique UID, True by default
.TP
.B system
Choose UID in the range of FIRST_SYSTEM_UID and LAST_SYSTEM_UID.
.UNINDENT
.sp
User comment field (GECOS) support (currently Linux, FreeBSD, and MacOS
only):
.sp
The below values should be specified as strings to avoid ambiguities when
the values are loaded. (Especially the phone and room number fields which
are likely to contain numeric data)
.INDENT 7.0
.TP
.B fullname
The user\(aqs full name
.TP
.B roomnumber
The user\(aqs room number (not supported in MacOS)
.TP
.B workphone
The user\(aqs work phone number (not supported in MacOS)
.TP
.B homephone
The user\(aqs home phone number (not supported in MacOS)
.UNINDENT
.sp
Changed in version 2014.7.0: Shadow attribute support added.
.sp
Shadow attributes support (currently Linux only):
.sp
The below values should be specified as integers.
.INDENT 7.0
.TP
.B date
Date of last change of password, represented in days since epoch
(January 1, 1970).
.TP
.B mindays
The minimum number of days between password changes.
.TP
.B maxdays
The maximum number of days between password changes.
.TP
.B inactdays
The number of days after a password expires before an account is
locked.
.TP
.B warndays
Number of days prior to maxdays to warn users.
.TP
.B expire
Date that account expires, represented in days since epoch (January 1,
1970).
.UNINDENT
.UNINDENT
.SS salt.states.virtualenv
.SS Setup of Python virtualenv sandboxes
.INDENT 0.0
.TP
.B salt.states.virtualenv_mod.managed(name, venv_bin=None, requirements=None, system_site_packages=False, distribute=False, use_wheel=False, clear=False, python=None, extra_search_dir=None, never_download=None, prompt=None, user=None, runas=None, no_chown=False, cwd=None, index_url=None, extra_index_url=None, pre_releases=False, no_deps=False, pip_exists_action=None, proxy=None)
Create a virtualenv and optionally manage it with pip
.INDENT 7.0
.TP
.B name
Path to the virtualenv
.TP
.B requirements
Path to a pip requirements file. If the path begins with \fBsalt://\fP
the file will be transferred from the master file server.
.TP
.B cwd
Path to the working directory where "pip install" is executed.
.TP
.B use_wheel
False
Prefer wheel archives (requires pip>=1.4)
.TP
.B no_deps: False
Pass \fI\-\-no\-deps\fP to \fIpip\fP\&.
.TP
.B pip_exists_action: None
Default action of pip when a path already exists: (s)witch, (i)gnore,
(w)ipe, (b)ackup
.TP
.B proxy: None
Proxy address which is passed to "pip install"
.UNINDENT
.sp
Also accepts any kwargs that the virtualenv module will.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/var/www/myvirtualenv.com:
virtualenv.managed:
\- system_site_packages: False
\- requirements: salt://REQUIREMENTS.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.win_dns_client
.sp
Module for configuring DNS Client on Windows systems
.INDENT 0.0
.TP
.B salt.states.win_dns_client.dns_dhcp(name, interface=\(aqLocal Area Connection\(aq)
Configure the DNS server list from DHCP Server
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_dns_client.dns_exists(name, servers=None, interface=\(aqLocal Area Connection\(aq)
Configure the DNS server list in the specified interface
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
config_dns_servers:
win_dns_client.dns_exists:
\- servers:
\- 8.8.8.8
\- 8.8.8.9
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_dns_client.primary_suffix(name, suffix=None, updates=False)
New in version 2014.7.0.
.sp
Configure the global primary DNS suffix of a DHCP client.
.INDENT 7.0
.TP
.B suffix
None
The suffix which is advertised for this client when acquiring a DHCP lease
When none is set, the explicitly configured DNS suffix will be removed.
.TP
.B updates
False
Allow syncing the DNS suffix with the AD domain when the client\(aqs AD domain membership changes
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
primary_dns_suffix:
win_dns_client.primary_suffix:
\- suffix: sub.domain.tld
\- updates: True
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.win_firewall
.sp
State for configuring Windows Firewall
.INDENT 0.0
.TP
.B salt.states.win_firewall.add_rule(name, localport, protocol=\(aqtcp\(aq, action=\(aqallow\(aq, dir=\(aqin\(aq)
Add a new firewall rule (Windows only)
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_firewall.disabled(name)
Disable all the firewall profiles (Windows only)
.UNINDENT
.SS salt.states.win_network
.SS Configuration of network interfaces on Windows hosts
.sp
New in version 2014.1.0.
.sp
This module provides the \fBnetwork\fP state(s) on Windows hosts. DNS servers, IP
addresses and default gateways can currently be managed.
.sp
Below is an example of the configuration for an interface that uses DHCP for
both DNS servers and IP addresses:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Local Area Connection #2:
network.managed:
\- dns_proto: dhcp
\- ip_proto: dhcp
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Both the \fBdns_proto\fP and \fBip_proto\fP arguments are required.
.UNINDENT
.UNINDENT
.sp
Static DNS and IP addresses can be configured like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Local Area Connection #2:
network.managed:
\- dns_proto: static
\- dns_servers:
\- 8.8.8.8
\- 8.8.4.4
\- ip_proto: static
\- ip_addrs:
\- 10.2.3.4/24
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
IP addresses are specified using the format
\fB<ip\-address>/<subnet\-length>\fP\&. Salt provides a convenience function
called \fBip.get_subnet_length\fP
to calculate the subnet length from a netmask.
.UNINDENT
.UNINDENT
.sp
Optionally, if you are setting a static IP address, you can also specify the
default gateway using the \fBgateway\fP parameter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Local Area Connection #2:
network.managed:
\- dns_proto: static
\- dns_servers:
\- 8.8.8.8
\- 8.8.4.4
\- ip_proto: static
\- ip_addrs:
\- 10.2.3.4/24
\- gateway: 10.2.3.1
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_network.managed(name, dns_proto=None, dns_servers=None, ip_proto=None, ip_addrs=None, gateway=None, enabled=True, **kwargs)
Ensure that the named interface is configured properly.
.INDENT 7.0
.TP
.B name
The name of the interface to manage
.TP
.B dns_proto
None
Set to \fBstatic\fP and use the \fBdns_servers\fP parameter to provide a
list of DNS nameservers. set to \fBdhcp\fP to use DHCP to get the DNS
servers.
.TP
.B dns_servers
None
A list of static DNS servers.
.TP
.B ip_proto
None
Set to \fBstatic\fP and use the \fBip_addrs\fP and (optionally) \fBgateway\fP
parameters to provide a list of static IP addresses and the default
gateway. Set to \fBdhcp\fP to use DHCP.
.TP
.B ip_addrs
None
A list of static IP addresses.
.TP
.B gateway
None
A list of static IP addresses.
.TP
.B enabled
True
Set to \fBFalse\fP to ensure that this interface is disabled.
.UNINDENT
.UNINDENT
.SS salt.states.win_path
.sp
Manage the Windows System PATH
.INDENT 0.0
.TP
.B salt.states.win_path.absent(name)
Remove the directory from the SYSTEM path
.sp
index: where the directory should be placed in the PATH (default: 0)
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqC:\esysinternals\(aq:
win_path.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_path.exists(name, index=None)
Add the directory to the system PATH at index location
.sp
index: where the directory should be placed in the PATH (default: None)
[Note: Providing no index will append directory to PATH and
will not enforce its location within the PATH.]
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\(aqC:\epython27\(aq:
win_path.exists
\(aqC:\esysinternals\(aq:
win_path.exists:
index: 0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.win_servermanager
.sp
Manage Windows features via the ServerManager powershell module
.INDENT 0.0
.TP
.B salt.states.win_servermanager.installed(name, recurse=False, force=False)
Install the windows feature
.INDENT 7.0
.TP
.B name:
short name of the feature (the right column in win_servermanager.list_available)
.TP
.B recurse:
install all sub\-features as well
.TP
.B force:
if the feature is installed but on of its sub\-features are not installed set this to True to force
the installation of the sub\-features
.UNINDENT
.sp
Note:
Some features requires reboot after un/installation, if so until the server is restarted
Other features can not be installed !
.UNINDENT
.SS salt.states.win_system
.SS Management of Windows system information
.sp
New in version 2014.1.0.
.sp
This state is used to manage system information such as the computer name and
description.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ERIK\-WORKSTATION:
system.computer_name: []
This is Erik\(aqs computer, don\(aqt touch!:
system.computer_desc: []
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_system.computer_desc(name)
Manage the computer\(aqs description field
.INDENT 7.0
.TP
.B name
The desired computer description
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_system.computer_name(name)
Manage the computer\(aqs name
.INDENT 7.0
.TP
.B name
The desired computer name
.UNINDENT
.UNINDENT
.SS salt.states.win_update
.SS Management of the windows update agent
.sp
New in version 2014.7.0.
.sp
Set windows updates to run by category. Default behavior is to install
all updates that do not require user interaction to complete.
.sp
Optionally set \fBcategory\fP to a category of your choosing to only
install certain updates. default is all available updates.
.sp
In the example below, will install all Security and Critical Updates,
and download but not install standard updates.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
updates:
win_update.installed:
\- categories:
\- \(aqCritical Updates\(aq
\- \(aqSecurity Updates\(aq
win_update.downloaded:
\- categories:
\- \(aqUpdates\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can also specify a number of features about the update to have a
fine grain approach to specific types of updates. These are the following
features/states of updates available for configuring:
.INDENT 0.0
.IP \(bu 2
\fBUI\fP \- User interaction required, skipped by default
.IP \(bu 2
\fBdownloaded\fP \- Already downloaded, skipped by default (downloading)
.IP \(bu 2
\fBpresent\fP \- Present on computer, included by default (installing)
.IP \(bu 2
\fBinstalled\fP \- Already installed, skipped by default
.IP \(bu 2
\fBreboot\fP \- Reboot required, included by default
.IP \(bu 2
\fBhidden\fP \- skip those updates that have been hidden.
.IP \(bu 2
\fBsoftware\fP \- Software updates, included by default
.IP \(bu 2
\fBdriver\fP \- driver updates, skipped by default
.UNINDENT
.sp
This example installs all driver updates that don\(aqt require a reboot:
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gryffindor:
win_update.install:
\- includes:
\- driver: True
\- software: False
\- reboot: False
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class salt.states.win_update.PyWinUpdater(categories=None, skipUI=True, skipDownloaded=True, skipInstalled=True, skipReboot=False, skipPresent=True, softwareUpdates=True, driverUpdates=False, skipHidden=True)
.INDENT 7.0
.TP
.B AutoSearch()
.UNINDENT
.INDENT 7.0
.TP
.B Download()
.UNINDENT
.INDENT 7.0
.TP
.B GetAvailableCategories()
.UNINDENT
.INDENT 7.0
.TP
.B GetCategories()
.UNINDENT
.INDENT 7.0
.TP
.B GetDownloadResults()
.UNINDENT
.INDENT 7.0
.TP
.B GetInstallationResults()
.UNINDENT
.INDENT 7.0
.TP
.B Install()
.UNINDENT
.INDENT 7.0
.TP
.B Search(searchString)
.UNINDENT
.INDENT 7.0
.TP
.B SetCategories(categories)
.UNINDENT
.INDENT 7.0
.TP
.B SetInclude(include, state)
.UNINDENT
.INDENT 7.0
.TP
.B SetIncludes(includes)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_update.downloaded(name, categories=None, includes=None, retries=10)
Cache updates for later install.
.INDENT 7.0
.TP
.B name
If \fBcategories\fP is left empty, it will be assumed that you are
passing the category option through the name. These are separate
because you can only have one name, but can have multiple categories.
.TP
.B categories
The list of categories to be downloaded. These are simply strings in
the update\(aqs information, so there is no enumeration of the categories
available. Known categories include:
.INDENT 7.0
.IP \(bu 2
Updates
.IP \(bu 2
Windows 7
.IP \(bu 2
Critical Updates
.IP \(bu 2
Security Updates
.IP \(bu 2
Update Rollups
.UNINDENT
.TP
.B includes
A list of features of the updates to cull by. Available features
include:
.INDENT 7.0
.IP \(bu 2
\fBUI\fP \- User interaction required, skipped by default
.IP \(bu 2
\fBdownloaded\fP \- Already downloaded, skipped by default (downloading)
.IP \(bu 2
\fBpresent\fP \- Present on computer, included by default (installing)
.IP \(bu 2
\fBinstalled\fP \- Already installed, skipped by default
.IP \(bu 2
\fBreboot\fP \- Reboot required, included by default
.IP \(bu 2
\fBhidden\fP \- Kkip those updates that have been hidden.
.IP \(bu 2
\fBsoftware\fP \- Software updates, included by default
.IP \(bu 2
\fBdriver\fP \- Driver updates, skipped by default
.UNINDENT
.TP
.B retries
Number of retries to make before giving up. This is total, not per
step.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_update.installed(name, categories=None, includes=None, retries=10)
Install specified windows updates.
.INDENT 7.0
.TP
.B name
If \fBcategories\fP is left empty, it will be assumed that you are
passing the category option through the name. These are separate
because you can only have one name, but can have multiple categories.
.TP
.B categories
The list of categories to be downloaded. These are simply strings in
the update\(aqs information, so there is no enumeration of the categories
available. Known categories include:
.INDENT 7.0
.IP \(bu 2
Updates
.IP \(bu 2
Windows 7
.IP \(bu 2
Critical Updates
.IP \(bu 2
Security Updates
.IP \(bu 2
Update Rollups
.UNINDENT
.TP
.B includes
A list of features of the updates to cull by. Available features
include:
.INDENT 7.0
.IP \(bu 2
\fBUI\fP \- User interaction required, skipped by default
.IP \(bu 2
\fBdownloaded\fP \- Already downloaded, skipped by default (downloading)
.IP \(bu 2
\fBpresent\fP \- Present on computer, included by default (installing)
.IP \(bu 2
\fBinstalled\fP \- Already installed, skipped by default
.IP \(bu 2
\fBreboot\fP \- Reboot required, included by default
.IP \(bu 2
\fBhidden\fP \- Kkip those updates that have been hidden.
.IP \(bu 2
\fBsoftware\fP \- Software updates, included by default
.IP \(bu 2
\fBdriver\fP \- Driver updates, skipped by default
.UNINDENT
.TP
.B retries
Number of retries to make before giving up. This is total, not per
step.
.UNINDENT
.UNINDENT
.SS salt.states.winrepo
.sp
Manage Windows Package Repository
.INDENT 0.0
.TP
.B salt.states.winrepo.genrepo(name, force=False, allow_empty=False)
Refresh the winrepo.p file of the repository (salt\-run winrepo.genrepo)
.sp
if force is True no checks will be made and the repository will be generated
if allow_empty is True then the state will not return an error if there are 0 packages
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
winrepo:
winrepo.genrepo
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.xmpp
.SS Sending Messages over XMPP
.sp
New in version 2014.1.0.
.sp
This state is useful for firing messages during state runs, using the XMPP
protocol
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server\-warning\-message:
xmpp.send_msg:
\- name: \(aqThis is a server warning message\(aq
\- profile: my\-xmpp\-account
\- recipient: admins@xmpp.example.com/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.xmpp.send_msg(name, recipient, profile)
Send a message to an XMPP user
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
server\-warning\-message:
xmpp.send_msg:
\- name: \(aqThis is a server warning message\(aq
\- profile: my\-xmpp\-account
\- recipient: admins@xmpp.example.com/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B name
The message to send to the XMPP user
.UNINDENT
.UNINDENT
.SS salt.states.zcbuildout
.SS Management of zc.buildout
.sp
This module is inspired from minitage\(aqs buildout maker
(\fI\%https://github.com/minitage/minitage/blob/master/src/minitage/core/makers/buildout.py\fP)
.sp
New in version Boron.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This state module is beta; the API is subject to change and no promise
as to performance or functionality is yet present
.UNINDENT
.UNINDENT
.SS Available Functions
.INDENT 0.0
.IP \(bu 2
built
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
installed1
buildout.installed:
\- name: /path/to/buildout
installed2
buildout.installed:
\- name: /path/to/buildout
\- parts:
\- a
\- b
\- python: /path/to/pythonpath/bin/python
\- unless: /bin/test_something_installed
\- onlyif: /bin/test_else_installed
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.zcbuildout.installed(name, config=\(aqbuildout.cfg\(aq, quiet=False, parts=None, runas=None, user=None, env=(), buildout_ver=None, test_release=False, distribute=None, new_st=None, offline=False, newest=False, python=\(aq/usr/local/opt/python/bin/python2.7\(aq, debug=False, verbose=False, unless=None, onlyif=None, use_vt=False, loglevel=\(aqdebug\(aq)
Install buildout in a specific directory
.sp
It is a thin wrapper to modules.buildout.buildout
.INDENT 7.0
.TP
.B name
directory to execute in
.UNINDENT
.sp
quiet
.INDENT 7.0
.INDENT 3.5
do not output console & logs
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B config
buildout config to use (default: buildout.cfg)
.TP
.B parts
specific buildout parts to run
.TP
.B runas
user used to run buildout as
.sp
Deprecated since version 2014.1.4.
.TP
.B user
user used to run buildout as
.sp
New in version 2014.1.4.
.TP
.B env
environment variables to set when running
.TP
.B buildout_ver
force a specific buildout version (1 | 2)
.TP
.B test_release
buildout accept test release
.TP
.B new_st
Forcing use of setuptools >= 0.7
.TP
.B distribute
use distribute over setuptools if possible
.TP
.B offline
does buildout run offline
.TP
.B python
python to use
.TP
.B debug
run buildout with \-D debug flag
.TP
.B onlyif
Only execute cmd if statement on the host return 0
.TP
.B unless
Do not execute cmd if statement on the host return 0
.TP
.B newest
run buildout in newest mode
.TP
.B verbose
run buildout in verbose mode (\-vvvvv)
.TP
.B use_vt
Use the new salt VT to stream output [experimental]
.TP
.B loglevel
loglevel for buildout commands
.UNINDENT
.UNINDENT
.SS salt.states.zk_concurrency
.SS Control concurrency of steps within state execution using zookeeper
.sp
This module allows you to "wrap" a state\(aqs execution with concurrency control.
This is useful to protect against all hosts executing highstate simultaneously
if your services don\(aqt all HUP restart. The common way of protecting against this
is to run in batch mode, but that doesn\(aqt protect from another person running
the same batch command (and thereby having 2x the number of nodes deploying at once).
.sp
This module will bock while acquiring a slot, meaning that however the command gets
called it will coordinate with zookeeper to ensure that no more than max_concurrency
steps are executing with a single path.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
acquire_lock:
zk_concurrency.lock:
\- zk_hosts: \(aqzookeeper:2181\(aq
\- path: /trafficserver
\- max_concurrency: 4
\- prereq:
\- service: trafficserver
trafficserver:
service.running:
\- watch:
\- file: /etc/trafficserver/records.config
/etc/trafficserver/records.config:
file.managed:
\- source: salt://records.config
release_lock:
zk_concurrency.unlock:
\- path: /trafficserver
\- require:
\- service: trafficserver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example would allow the file state to change, but would limit the
concurrency of the trafficserver service restart to 4.
.INDENT 0.0
.TP
.B salt.states.zk_concurrency.lock(zk_hosts, path, max_concurrency, timeout=None, ephemeral_lease=False)
Block state execution until you are able to get the lock (or hit the timeout)
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.zk_concurrency.unlock(path)
Remove lease from semaphore
.UNINDENT
.SS Execution Modules
.sp
Salt execution modules are the functions called by the \fBsalt\fP command.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Salt execution modules are different from state modules and cannot be
called directly within state files. You must use the \fBmodule\fP
state module to call execution modules within state runs.
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIFull list of builtin modules\fP
.UNINDENT
.UNINDENT
.sp
Salt ships with many modules that cover a wide variety of tasks.
.SS Modules Are Easy to Write!
.sp
Writing Salt execution modules is straightforward.
.sp
A Salt execution modules is a Python or \fI\%Cython\fP module
placed in a directory called \fB_modules/\fP
within the \fBfile_roots\fP as specified by the master config file. By
default this is \fI/srv/salt/_modules\fP on Linux systems.
.sp
Modules placed in \fB_modules/\fP will be synced to the minions when any of the following
Salt functions are called:
.INDENT 0.0
.IP \(bu 2
\fBstate.highstate\fP
.IP \(bu 2
\fBsaltutil.sync_modules\fP
.IP \(bu 2
\fBsaltutil.sync_all\fP
.UNINDENT
.sp
Note that a module\(aqs default name is its filename
(i.e. \fBfoo.py\fP becomes module \fBfoo\fP), but that its name can be overridden
by using a \fI\%__virtual__ function\fP\&.
.sp
If a Salt module has errors and cannot be imported, the Salt minion will continue
to load without issue and the module with errors will simply be omitted.
.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 execution modules are available to each other and modules can call
functions available in other execution modules.
.sp
The variable \fB__salt__\fP is packed into the modules after they are loaded into
the Salt minion.
.sp
The \fB__salt__\fP variable is a \fI\%Python dictionary\fP
containing all of the Salt functions. Dictionary keys are strings representing the
names of the modules and the values are the functions themselves.
.sp
Salt modules can be cross\-called by accessing the value in the \fB__salt__\fP dict:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def foo(bar):
return __salt__[\(aqcmd.run\(aq](bar)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This code will call the \fIrun\fP function in the \fBcmd\fP and pass the argument
\fBbar\fP to it.
.SS Preloaded Execution Module Data
.sp
When interacting with execution modules often it is nice to be able to read information
dynamically about the minion or to load in configuration parameters for a module.
.sp
Salt allows for different types of data to be loaded into the modules by the
minion.
.SS Grains Data
.sp
The values detected by the Salt Grains on the minion are available in a
\fI\%dict\fP named \fB__grains__\fP and can be accessed
from within callable objects in the Python modules.
.sp
To see the contents of the grains dictionary for a given system in your deployment
run the \fBgrains.items()\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqhostname\(aq grains.items \-\-output=pprint
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Any value in a grains dictionary can be accessed as any other Python dictionary. For
example, the grain representing the minion ID is stored in the \fBid\fP key and from
an execution module, the value would be stored in \fB__grains__[\(aqid\(aq]\fP\&.
.SS Module Configuration
.sp
Since parameters for configuring a module may be desired, Salt allows for
configuration information from the minion configuration file to be passed to
execution modules.
.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 therefore
\fBstrongly\fP recommended that the values passed in the configuration file match
the module name. A value intended for the \fBtest\fP execution module should be named
\fBtest.<value>\fP\&.
.sp
The test execution module contains usage of the module configuration and the default
configuration file for the minion contains the information and format used to
pass data to the modules. \fBsalt.modules.test\fP, \fBconf/minion\fP\&.
.SS Printout Configuration
.sp
Since execution 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 dictionary can be declared in the module.
The \fB__outputter__\fP dictionary contains a mapping of function name to Salt
Outputter.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__outputter__ = {
\(aqrun\(aq: \(aqtxt\(aq
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will ensure that the text outputter is used.
.SS Virtual Modules
.sp
Sometimes an execution 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 execution 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
\fI\%string\fP or \fI\%False\fP\&. 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 \fBpkg\fP 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. Some examples:
.INDENT 0.0
.IP \(bu 2
\fI\%pacman.py\fP
.IP \(bu 2
\fI\%yumpkg.py\fP
.IP \(bu 2
\fI\%aptpkg.py\fP
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Modules which return a string from \fB__virtual__\fP that is already used by a module that
ships with Salt will _override_ the stock module.
.UNINDENT
.UNINDENT
.SS Documentation
.sp
Salt execution modules are documented. The \fBsys.doc()\fP function will return the
documentation for all available modules:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq sys.doc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBsys.doc\fP function simply prints out the docstrings found in the modules; when
writing Salt execution modules, please follow the formatting conventions for docstrings as
they appear in the other modules.
.SS Adding Documentation to Salt Modules
.sp
It is strongly suggested that all Salt modules have documentation added.
.sp
To add documentation add a \fI\%Python docstring\fP to the function.
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
Now when the sys.doc call is executed the docstring will be cleanly returned
to the calling terminal.
.sp
Documentation added to execution modules in docstrings will automatically be added
to the online web\-based documentation.
.SS Add Execution Module Metadata
.sp
When writing a Python docstring for an execution module, add information about the module
using the following field lists:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
:maintainer: Thomas Hatch <thatch@saltstack.com, Seth House <shouse@saltstack.com>
:maturity: new
:depends: python\-mysqldb
:platform: all
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The maintainer field is a comma\-delimited list of developers who help maintain
this module.
.sp
The maturity field indicates the level of quality and testing for this module.
Standard labels will be determined.
.sp
The depends field is a comma\-delimited list of modules that this module depends
on.
.sp
The platform field is a comma\-delimited list of platforms that this module is
known to run on.
.SS Private Functions
.sp
In Salt, Python callable objects contained within an execution module are made available
to the Salt minion for use. The only exception to this rule is a callable
object with a name starting with an underscore \fB_\fP\&.
.SS Objects Loaded Into the Salt Minion
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def foo(bar):
return bar
class baz:
def __init__(self, quo):
pass
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Objects NOT Loaded into the Salt Minion
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def _foobar(baz): # Preceded with an _
return baz
cheese = {} # Not a callable Python object
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Some callable names also end with an underscore \fB_\fP, to avoid keyword clashes
with Python keywords. When using execution modules, or state modules, with these
in them the trailing underscore should be omitted.
.UNINDENT
.UNINDENT
.SS Useful Decorators for Modules
.SS Depends Decorator
.sp
When writing execution modules there are many times where some of the module will
work on all hosts but some functions have an external dependency, such as a service
that needs to be installed or a binary that needs to be present on the system.
.sp
Instead of trying to wrap much of the code in large try/except blocks, a decorator can
be used.
.sp
If the dependencies passed to the decorator don\(aqt exist, then the salt minion will remove
those functions from the module on that host.
.sp
If a "fallback_function" is defined, it will replace the function instead of removing it
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import logging
from salt.utils.decorators import depends
log = logging.getLogger(__name__)
try:
import dependency_that_sometimes_exists
except ImportError as e:
log.trace(\(aqFailed to import dependency_that_sometimes_exists: {0}\(aq.format(e))
@depends(\(aqdependency_that_sometimes_exists\(aq)
def foo():
\(aq\(aq\(aq
Function with a dependency on the "dependency_that_sometimes_exists" module,
if the "dependency_that_sometimes_exists" is missing this function will not exist
\(aq\(aq\(aq
return True
def _fallback():
\(aq\(aq\(aq
Fallback function for the depends decorator to replace a function with
\(aq\(aq\(aq
return \(aq"dependency_that_sometimes_exists" needs to be installed for this function to exist\(aq
@depends(\(aqdependency_that_sometimes_exists\(aq, fallback_function=_fallback)
def foo():
\(aq\(aq\(aq
Function with a dependency on the "dependency_that_sometimes_exists" module.
If the "dependency_that_sometimes_exists" is missing this function will be
replaced with "_fallback"
\(aq\(aq\(aq
return True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Master Tops
.sp
Salt includes a number of built\-in subsystems to generate top file data, they
are listed listed at
\fIall\-salt.tops\fP\&.
.sp
The source for the built\-in Salt master tops can be found here:
\fI\%https://github.com/saltstack/salt/blob/develop/salt/tops\fP
.SS Full list of builtin master tops modules
.TS
center;
|l|l|.
_
T{
\fBcobbler\fP
T} T{
Cobbler Tops
T}
_
T{
\fBext_nodes\fP
T} T{
External Nodes Classifier
T}
_
T{
\fBmongo\fP
T} T{
Read tops data from a mongodb collection
T}
_
T{
\fBreclass_adapter\fP
T} T{
Read tops data from a reclass database
T}
_
.TE
.SS salt.tops.cobbler
.SS Cobbler Tops
.sp
Cobbler Tops is a master tops subsystem used to look up mapping information
from Cobbler via its API. The same cobbler.* parameters are used for both
the Cobbler tops and Cobbler pillar modules.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
cobbler: {}
cobbler.url: https://example.com/cobbler_api #default is http://localhost/cobbler_api
cobbler.user: username # default is no username
cobbler.password: password # default is no password
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Module Documentation
.INDENT 0.0
.TP
.B salt.tops.cobbler.top(**kwargs)
Look up top data in Cobbler for a minion.
.UNINDENT
.SS salt.tops.ext_nodes
.SS External Nodes Classifier
.sp
The External Nodes Classifier is a master tops subsystem that retrieves mapping
information from major configuration management systems. One of the most common
external nodes classifiers system is provided by Cobbler and is called
\fBcobbler\-ext\-nodes\fP\&.
.sp
The cobbler\-ext\-nodes command can be used with this configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
ext_nodes: cobbler\-ext\-nodes
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is noteworthy that the Salt system does not directly ingest the data
sent from the \fBcobbler\-ext\-nodes\fP command, but converts the data into
information that is used by a Salt top file.
.sp
Any command can replace the call to \(aqcobbler\-ext\-nodes\(aq above, but currently the
data must be formatted in the same way that the standard \(aqcobbler\-ext\-nodes\(aq
does.
.sp
See (admittedly degenerate and probably not complete) example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
classes:
\- basepackages
\- database
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above essentially is the same as a top.sls containing the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- basepackages
\- database
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.tops.ext_nodes.top(**kwargs)
Run the command configured
.UNINDENT
.SS salt.tops.mongo
.sp
Read tops data from a mongodb collection
.sp
This module will load tops data from a mongo collection. It uses the node\(aqs id
for lookups.
.SS Salt Master Mongo Configuration
.sp
The module shares the same base mongo connection variables as
\fBsalt.returners.mongo_return\fP\&. These variables go in your master
config file.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBmongo.db\fP \- The mongo database to connect to. Defaults to \fB\(aqsalt\(aq\fP\&.
.IP \(bu 2
\fBmongo.host\fP \- The mongo host to connect to. Supports replica sets by
specifying all hosts in the set, comma\-delimited. Defaults to \fB\(aqsalt\(aq\fP\&.
.IP \(bu 2
\fBmongo.port\fP \- The port that the mongo database is running on. Defaults
to \fB27017\fP\&.
.IP \(bu 2
\fBmongo.user\fP \- The username for connecting to mongo. Only required if
you are using mongo authentication. Defaults to \fB\(aq\(aq\fP\&.
.IP \(bu 2
\fBmongo.password\fP \- The password for connecting to mongo. Only required
if you are using mongo authentication. Defaults to \fB\(aq\(aq\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Configuring the Mongo Tops Subsystem
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
mongo:
collection: tops
id_field: _id
re_replace: ""
re_pattern: \e.example\e.com
states_field: states
environment_field: environment
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Module Documentation
.INDENT 0.0
.TP
.B salt.tops.mongo.top(**kwargs)
Connect to a mongo database and read per\-node tops data.
.INDENT 7.0
.TP
.B Parameters:
.INDENT 7.0
.IP \(bu 2
\fIcollection\fP: The mongodb collection to read data from. Defaults to
\fB\(aqtops\(aq\fP\&.
.IP \(bu 2
\fIid_field\fP: The field in the collection that represents an individual
minion id. Defaults to \fB\(aq_id\(aq\fP\&.
.IP \(bu 2
\fIre_pattern\fP: If your naming convention in the collection is shorter
than the minion id, you can use this to trim the name.
\fIre_pattern\fP will be used to match the name, and \fIre_replace\fP will
be used to replace it. Backrefs are supported as they are in the
Python standard library. If \fBNone\fP, no mangling of the name will
be performed \- the collection will be searched with the entire
minion id. Defaults to \fBNone\fP\&.
.IP \(bu 2
\fIre_replace\fP: Use as the replacement value in node ids matched with
\fIre_pattern\fP\&. Defaults to \(aq\(aq. Feel free to use backreferences here.
.IP \(bu 2
\fIstates_field\fP: The name of the field providing a list of states.
.IP \(bu 2
\fIenvironment_field\fP: The name of the field providing the environment.
Defaults to \fBenvironment\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.tops.reclass_adapter
.sp
Read tops data from a reclass database
.sp
This \fBmaster_tops\fP plugin provides access to
the \fBreclass\fP database, such that state information (top data) are retrieved
from \fBreclass\fP\&.
.sp
You can find more information about \fBreclass\fP at
\fI\%http://reclass.pantsfullofunix.net\fP\&.
.sp
To use the plugin, add it to the \fBmaster_tops\fP list in the Salt master config
and tell \fBreclass\fP by way of a few options how and where to find the
inventory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
reclass:
storage_type: yaml_fs
inventory_base_uri: /srv/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This would cause \fBreclass\fP to read the inventory from YAML files in
\fB/srv/salt/nodes\fP and \fB/srv/salt/classes\fP\&.
.sp
If you are also using \fBreclass\fP as \fBext_pillar\fP plugin, and you want to
avoid having to specify the same information for both, use YAML anchors (take
note of the differing data types for \fBext_pillar\fP and \fBmaster_tops\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
reclass: &reclass
storage_type: yaml_fs
inventory_base_uri: /srv/salt
reclass_source_path: ~/code/reclass
ext_pillar:
\- reclass: *reclass
master_tops:
reclass: *reclass
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you want to run reclass from source, rather than installing it, you can
either let the master know via the \fBPYTHONPATH\fP environment variable, or by
setting the configuration option, like in the example above.
.INDENT 0.0
.TP
.B salt.tops.reclass_adapter.top(**kwargs)
Query \fBreclass\fP for the top data (states of the minions).
.UNINDENT
.SS Full list of builtin wheel modules
.TS
center;
|l|l|.
_
T{
\fBconfig\fP
T} T{
Manage the master configuration file
T}
_
T{
\fBerror\fP
T} T{
Error generator to enable integration testing of salt wheel error handling
T}
_
T{
\fBfile_roots\fP
T} T{
Read in files from the file_root and save files to the file root
T}
_
T{
\fBkey\fP
T} T{
Wheel system wrapper for key system
T}
_
T{
\fBpillar_roots\fP
T} T{
The \fIpillar_roots\fP wheel module is used to manage files under the pillar roots directories on the master server.
T}
_
.TE
.SS salt.wheel.config
.sp
Manage the master configuration file
.INDENT 0.0
.TP
.B salt.wheel.config.apply(key, value)
Set a single key
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This will strip comments from your config file
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.config.values()
Return the raw values of the config file
.UNINDENT
.SS salt.wheel.error
.sp
Error generator to enable integration testing of salt wheel error handling
.INDENT 0.0
.TP
.B salt.wheel.error.error(name=None, message=\(aq\(aq)
If name is None Then return empty dict
.sp
Otherwise raise an exception with __name__ from name, message from message
.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-wheel error
salt\-wheel error.error name="Exception" message="This is an error."
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.wheel.file_roots
.sp
Read in files from the file_root and save files to the file root
.INDENT 0.0
.TP
.B salt.wheel.file_roots.find(path, saltenv=\(aqbase\(aq, env=None)
Return a dict of the files located with the given path and environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.file_roots.list_env(saltenv=\(aqbase\(aq, env=None)
Return all of the file paths found in an environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.file_roots.list_roots()
Return all of the files names in all available environments
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.file_roots.read(path, saltenv=\(aqbase\(aq, env=None)
Read the contents of a text file, if the file is binary then
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.file_roots.write(data, path, saltenv=\(aqbase\(aq, index=0, env=None)
Write the named file, by default the first file found is written, but the
index of the file can be specified to write to a lower priority file root
.UNINDENT
.SS salt.wheel.key
.sp
Wheel system wrapper for key system
.INDENT 0.0
.TP
.B salt.wheel.key.accept(match)
Accept keys based on a glob match
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.delete(match)
Delete keys based on a glob match
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.finger(match)
Return the matching key fingerprints
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.gen(id_=None, keysize=2048)
Generate a key pair. No keys are stored on the master, a keypair is
returned as a dict containing pub and priv keys
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.gen_accept(id_, keysize=2048, force=False)
Generate a key pair then accept the public key. This function returns the
key pair in a dict, only the public key is preserved on the master.
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.key_str(match)
Return the key strings
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.list_(match)
List all the keys under a named status
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.list_all()
List all the keys
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.reject(match)
Delete keys based on a glob match
.UNINDENT
.SS salt.wheel.pillar_roots
.sp
The \fIpillar_roots\fP wheel module is used to manage files under the pillar roots
directories on the master server.
.INDENT 0.0
.TP
.B salt.wheel.pillar_roots.find(path, saltenv=\(aqbase\(aq, env=None)
Return a dict of the files located with the given path and environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.pillar_roots.list_env(saltenv=\(aqbase\(aq, env=None)
Return all of the file paths found in an environment
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.pillar_roots.list_roots()
Return all of the files names in all available environments
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.pillar_roots.read(path, saltenv=\(aqbase\(aq, env=None)
Read the contents of a text file, if the file is binary then
.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.pillar_roots.write(data, path, saltenv=\(aqbase\(aq, index=0, env=None)
Write the named file, by default the first file found is written, but the
index of the file can be specified to write to a lower priority file root
.UNINDENT
.SH SALT BEST PRACTICES
.sp
Salt\(aqs extreme flexibility leads to many questions concerning the structure of
configuration files.
.sp
This document exists to clarify these points through examples and
code.
.SS General rules
.INDENT 0.0
.IP 1. 3
Modularity and clarity should be emphasized whenever possible.
.IP 2. 3
Create clear relations between pillars and states.
.IP 3. 3
Use variables when it makes sense but don\(aqt overuse them.
.IP 4. 3
Store sensitive data in pillar.
.IP 5. 3
Don\(aqt use grains for matching in your pillar top file for any sensitive
pillars.
.UNINDENT
.SS Structuring States and Formulas
.sp
When structuring Salt States and Formulas it is important to begin with the
directory structure. A proper directory structure clearly defines the
functionality of each state to the user via visual inspection of the state\(aqs
name.
.sp
Reviewing the \fI\%MySQL Salt Formula\fP
it is clear to see the benefits to the end\-user when reviewing a sample of the
available states:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/srv/salt/mysql/files/
/srv/salt/mysql/client.sls
/srv/salt/mysql/map.jinja
/srv/salt/mysql/python.sls
/srv/salt/mysql/server.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This directory structure would lead to these states being referenced in a top
file in the following way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqweb*\(aq:
\- mysql.client
\- mysql.python
\(aqdb*\(aq:
\- mysql.server
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This clear definition ensures that the user is properly informed of what each
state will do.
.sp
Another example comes from the \fI\%vim\-formula\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/srv/salt/vim/files/
/srv/salt/vim/absent.sls
/srv/salt/vim/init.sls
/srv/salt/vim/map.jinja
/srv/salt/vim/nerdtree.sls
/srv/salt/vim/pyflakes.sls
/srv/salt/vim/salt.sls
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once again viewing how this would look in a top file:
.sp
/srv/salt/top.sls:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqweb*\(aq:
\- vim
\- vim.nerdtree
\- vim.pyflakes
\- vim.salt
\(aqdb*\(aq:
\- vim.absent
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The usage of a clear top\-level directory as well as properly named states
reduces the overall complexity and leads a user to both understand what will
be included at a glance and where it is located.
.sp
In addition \fIFormulas\fP should
be used as often as possible.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Formulas repositories on the saltstack\-formulas GitHub organization should
not be pointed to directly from systems that automatically fetch new
updates such as GitFS or similar tooling. Instead formulas repositories
should be forked on GitHub or cloned locally, where unintended, automatic
changes will not take place.
.UNINDENT
.UNINDENT
.SS Structuring Pillar Files
.sp
\fIPillars\fP are used to store
secure and insecure data pertaining to minions. When designing the structure
of the \fB/srv/pillar\fP directory, the pillars contained within
should once again be focused on clear and concise data which users can easily
review, modify and understand.
.sp
The \fB/srv/pillar/\fP directory is primarily controlled by \fBtop.sls\fP\&. It
should be noted that the pillar \fBtop.sls\fP is not used as a location to
declare variables and their values. The \fBtop.sls\fP is used as a way to
include other pillar files and organize the way they are matched based on
environments or grains.
.sp
An example \fBtop.sls\fP may be as simple as the following:
.sp
/srv/pillar/top.sls:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- packages
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or much more complicated, using a variety of matchers:
.sp
/srv/pillar/top.sls:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- apache
dev:
\(aqos:Debian\(aq:
\- match: grain
\- vim
test:
\(aq* and not G@os: Debian\(aq:
\- match: compound
\- emacs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is clear to see through these examples how the top file provides users with
power but when used incorrectly it can lead to confusing configurations. This
is why it is important to understand that the top file for pillar is not used
for variable definitions.
.sp
Each SLS file within the \fB/srv/pillar/\fP directory should correspond to the
states which it matches.
.sp
This would mean that the \fBapache\fP pillar file should contain data relevant to
Apache. Structuring files in this way once again ensures modularity, and
creates a consistent understanding throughout our Salt environment. Users can
expect that pillar variables found in an Apache state will live inside of an
Apache pillar:
.sp
\fB/srv/salt/pillar/apache.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
lookup:
name: httpd
config:
tmpl: /etc/httpd/httpd.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
While this pillar file is simple, it shows how a pillar file explicitly
relates to the state it is associated with.
.SS Variable Flexibility
.sp
Salt allows users to define variables in SLS files. When creating a state
variables should provide users with as much flexibility as possible. This
means that variables should be clearly defined and easy to manipulate, and
that sane defaults should exist in the event a variable is not properly
defined. Looking at several examples shows how these different items can
lead to extensive flexibility.
.sp
Although it is possible to set variables locally, this is generally not
preferred:
.sp
\fB/srv/salt/apache/conf.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set name = \(aqhttpd\(aq %}
{% set tmpl = \(aqsalt://apache/files/httpd.conf\(aq %}
include:
\- apache
apache_conf:
file.managed:
\- name: {{ name }}
\- source: {{ tmpl }}
\- template: jinja
\- user: root
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When generating this information it can be easily transitioned to the pillar
where data can be overwritten, modified, and applied to multiple states, or
locations within a single state:
.sp
\fB/srv/pillar/apache.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
lookup:
name: httpd
config:
tmpl: salt://apache/files/httpd.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/apache/conf.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- apache
apache_conf:
file.managed:
\- name: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:name\(aq) }}
\- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
\- template: jinja
\- user: root
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This flexibility provides users with a centralized location to modify
variables, which is extremely important as an environment grows.
.SS Modularity Within States
.sp
Ensuring that states are modular is one of the key concepts to understand
within Salt. When creating a state a user must consider how many times the
state could be re\-used, and what it relies on to operate. Below are several
examples which will iteratively explain how a user can go from a state which
is not very modular to one that is:
.sp
\fB/srv/salt/apache/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
httpd:
pkg.installed: []
service.running:
\- enable: True
/etc/httpd/httpd.conf:
file.managed:
\- source: salt://apache/files/httpd.conf
\- template: jinja
\- watch_in:
\- service: httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The example above is probably the worst\-case scenario when writing a state.
There is a clear lack of focus by naming both the pkg/service, and managed
file directly as the state ID. This would lead to changing multiple requires
within this state, as well as others that may depend upon the state.
.sp
Imagine if a require was used for the \fBhttpd\fP package in another state, and
then suddenly it\(aqs a custom package. Now changes need to be made in multiple
locations which increases the complexity and leads to a more error prone
configuration.
.sp
There is also the issue of having the configuration file located in the init,
as a user would be unable to simply install the service and use the default
conf file.
.sp
Our second revision begins to address the referencing by using \fB\- name\fP, as
opposed to direct ID references:
.sp
\fB/srv/salt/apache/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
pkg.installed:
\- name: httpd
service.running:
\- name: httpd
\- enable: True
apache_conf:
file.managed:
\- name: /etc/httpd/httpd.conf
\- source: salt://apache/files/httpd.conf
\- template: jinja
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above init file is better than our original, yet it has several issues
which lead to a lack of modularity. The first of these problems is the usage
of static values for items such as the name of the service, the name of the
managed file, and the source of the managed file. When these items are hard
coded they become difficult to modify and the opportunity to make mistakes
arises. It also leads to multiple edits that need to occur when changing
these items (imagine if there were dozens of these occurrences throughout the
state!). There is also still the concern of the configuration file data living
in the same state as the service and package.
.sp
In the next example steps will be taken to begin addressing these issues.
Starting with the addition of a map.jinja file (as noted in the
\fIFormula documentation\fP), and
modification of static values:
.sp
\fB/srv/salt/apache/map.jinja\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set apache = salt[\(aqgrains.filter_by\(aq]({
\(aqDebian\(aq: {
\(aqserver\(aq: \(aqapache2\(aq,
\(aqservice\(aq: \(aqapache2\(aq,
\(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq,
},
\(aqRedHat\(aq: {
\(aqserver\(aq: \(aqhttpd\(aq,
\(aqservice\(aq: \(aqhttpd\(aq,
\(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq,
},
}, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
/srv/pillar/apache.sls:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
lookup:
config:
tmpl: salt://apache/files/httpd.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/apache/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% from "apache/map.jinja" import apache with context %}
apache:
pkg.installed:
\- name: {{ apache.server }}
service.running:
\- name: {{ apache.service }}
\- enable: True
apache_conf:
file.managed:
\- name: {{ apache.conf }}
\- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
\- template: jinja
\- user: root
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The changes to this state now allow us to easily identify the location of the
variables, as well as ensuring they are flexible and easy to modify.
While this takes another step in the right direction, it is not yet complete.
Suppose the user did not want to use the provided conf file, or even their own
configuration file, but the default apache conf. With the current state setup
this is not possible. To attain this level of modularity this state will need
to be broken into two states.
.sp
\fB/srv/salt/apache/map.jinja\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set apache = salt[\(aqgrains.filter_by\(aq]({
\(aqDebian\(aq: {
\(aqserver\(aq: \(aqapache2\(aq,
\(aqservice\(aq: \(aqapache2\(aq,
\(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq,
},
\(aqRedHat\(aq: {
\(aqserver\(aq: \(aqhttpd\(aq,
\(aqservice\(aq: \(aqhttpd\(aq,
\(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq,
},
}, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/apache.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apache:
lookup:
config:
tmpl: salt://apache/files/httpd.conf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/apache/init.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% from "apache/map.jinja" import apache with context %}
apache:
pkg.installed:
\- name: {{ apache.server }}
service.running:
\- name: {{ apache.service }}
\- enable: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/apache/conf.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% from "apache/map.jinja" import apache with context %}
include:
\- apache
apache_conf:
file.managed:
\- name: {{ apache.conf }}
\- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
\- template: jinja
\- user: root
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This new structure now allows users to choose whether they only wish to
install the default Apache, or if they wish, overwrite the default package,
service, configuration file location, or the configuration file itself. In
addition to this the data has been broken between multiple files allowing for
users to identify where they need to change the associated data.
.SS Storing Secure Data
.sp
Secure data refers to any information that you would not wish to share with
anyone accessing a server. This could include data such as passwords,
keys, or other information.
.sp
As all data within a state is accessible by EVERY server that is connected
it is important to store secure data within pillar. This will ensure that only
those servers which require this secure data have access to it. In this
example a use can go from an insecure configuration to one which is only
accessible by the appropriate hosts:
.sp
\fB/srv/salt/mysql/testerdb.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
testdb:
mysql_database.present::
\- name: testerdb
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/mysql/user.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- mysql.testerdb
testdb_user:
mysql_user.present:
\- name: frank
\- password: "test3rdb"
\- host: localhost
\- require:
\- sls: mysql.testerdb
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Many users would review this state and see that the password is there in plain
text, which is quite problematic. It results in several issues which may not
be immediately visible.
.sp
The first of these issues is clear to most users \-\- the password being visible
in this state. This means that any minion will have a copy of this, and
therefore the password which is a major security concern as minions may not
be locked down as tightly as the master server.
.sp
The other issue that can be encountered is access by users on the master. If
everyone has access to the states (or their repository), then they are able to
review this password. Keeping your password data accessible by only a few
users is critical for both security and peace of mind.
.sp
There is also the issue of portability. When a state is configured this way
it results in multiple changes needing to be made. This was discussed in the
sections above but it is a critical idea to drive home. If states are not
portable it may result in more work later!
.sp
Fixing this issue is relatively simple, the content just needs to be moved to
the associated pillar:
.sp
\fB/srv/pillar/mysql.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mysql:
lookup:
name: testerdb
password: test3rdb
user: frank
host: localhost
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/mysql/testerdb.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
testdb:
mysql_database.present:
\- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:name\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/mysql/user.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- mysql.testerdb
testdb_user:
mysql_user.present:
\- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:user\(aq) }}
\- password: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:password\(aq) }}
\- host: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:host\(aq) }}
\- require:
\- sls: mysql.testerdb
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now that the database details have been moved to the associated pillar file,
only machines which are targeted via pillar will have access to these details.
Access to users who should not be able to review these details can also be
prevented while ensuring that they are still able to write states which take
advantage of this information.
.SH TROUBLESHOOTING
.sp
The intent of the troubleshooting section is to introduce solutions to a
number of common issues encountered by users and the tools that are available
to aid in developing States and Salt code.
.SS Troubleshooting the Salt Master
.sp
If your Salt master is having issues such as minions not returning data, slow
execution times, or a variety of other issues the
\fBSalt master troubleshooting page\fP contains details on troubleshooting the most
common issues encountered.
.SS Troubleshooting the Salt Minion
.sp
In the event that your Salt minion is having issues a variety of solutions
and suggestions are available at the \fBSalt minion troubleshooting page\fP\&.
.SS Running in the Foreground
.sp
A great deal of information is available via the debug logging system, if you
are having issues with minions connecting or not starting run the minion and/or
master in the foreground:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master \-l debug
salt\-minion \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP,
\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and
run them in the foreground.
.SS What Ports do the Master and Minion Need Open?
.sp
No ports need to be opened up on each minion. For the master, TCP ports 4505
and 4506 need to be open. If you\(aqve put both your Salt master and minion in
debug mode and don\(aqt see an acknowledgment that your minion has connected,
it could very well be a firewall.
.sp
You can check port connectivity from the minion with the nc command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
nc \-v \-z salt.master.ip 4505
nc \-v \-z salt.master.ip 4506
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There is also a \fBfirewall configuration\fP
document that might help as well.
.sp
If you\(aqve enabled the right TCP ports on your operating system or Linux
distribution\(aqs firewall and still aren\(aqt seeing connections, check that no
additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking
Salt.
.SS Using salt\-call
.sp
The \fBsalt\-call\fP command was originally developed for aiding in the development
of new Salt modules. Since then, many applications have been developed for
running any Salt module locally on a minion. These range from the original
intent of salt\-call, development assistance, to gathering more verbose output
from calls like \fBstate.highstate\fP\&.
.sp
When creating your state tree, it is generally recommended to invoke
\fBstate.highstate\fP with \fBsalt\-call\fP\&. This
displays far more information about the highstate execution than calling it
remotely. For even more verbosity, increase the loglevel with the same argument
as \fBsalt\-minion\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-call \-l debug state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The main difference between using \fBsalt\fP and using \fBsalt\-call\fP is that
\fBsalt\-call\fP is run from the minion, and it only runs the selected function on
that minion. By contrast, \fBsalt\fP is run from the master, and requires you to
specify the minions on which to run the command using salt\(aqs \fBtargeting
system\fP\&.
.SS Too many open files
.sp
The salt\-master needs at least 2 sockets per host that connects to it, one for
the Publisher and one for response port. Thus, large installations may, upon
scaling up the number of minions accessing a given master, encounter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38
Too many open files
sock != \-1 (tcp_listener.cpp:335)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The solution to this would be to check the number of files allowed to be
opened by the user running salt\-master (root by default):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[root@salt\-master ~]# ulimit \-n
1024
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And modify that value to be at least equal to the number of minions x 2.
This setting can be changed in limits.conf as the nofile value(s),
and activated upon new a login of the specified user.
.sp
So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum.
.SS Salt Master Stops Responding
.sp
There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the
Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater
than or equal to 2.1.9, you can work around the bug by setting the sysctls
\fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third
field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216.
.sp
You can do it manually with something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# echo 16777216 > /proc/sys/net/core/rmem_max
# echo 16777216 > /proc/sys/net/core/wmem_max
# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem
# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or with the following Salt state:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
net.core.rmem_max:
sysctl:
\- present
\- value: 16777216
net.core.wmem_max:
sysctl:
\- present
\- value: 16777216
net.ipv4.tcp_rmem:
sysctl:
\- present
\- value: 4096 87380 16777216
net.ipv4.tcp_wmem:
sysctl:
\- present
\- value: 4096 87380 16777216
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Salt and SELinux
.sp
Currently there are no SELinux policies for Salt. For the most part Salt runs
without issue when SELinux is running in Enforcing mode. This is because when
the minion executes as a daemon the type context is changed to \fBinitrc_t\fP\&.
The problem with SELinux arises when using salt\-call or running the minion in
the foreground, since the type context stays \fBunconfined_t\fP\&.
.sp
This problem is generally manifest in the rpm install scripts when using the
pkg module. Until a full SELinux Policy is available for Salt the solution
to this issue is to set the execution context of \fBsalt\-call\fP and
\fBsalt\-minion\fP to rpm_exec_t:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# CentOS 5 and RHEL 5:
chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-minion
chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-call
# CentOS 6 and RHEL 6:
chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-minion
chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-call
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This works well, because the \fBrpm_exec_t\fP context has very broad control over
other types.
.SS Red Hat Enterprise Linux 5
.sp
Salt requires Python 2.6 or 2.7. Red Hat Enterprise Linux 5 and its variants
come with Python 2.4 installed by default. When installing on RHEL 5 from the
\fI\%EPEL repository\fP this is handled for you. But, if you run Salt from git, be
advised that its dependencies need to be installed from EPEL and that Salt
needs to be run with the \fBpython26\fP executable.
.SS Common YAML Gotchas
.sp
An extensive list of \fBYAML idiosyncrasies\fP has been compiled.
.SS Live Python Debug Output
.sp
If the minion or master seems to be unresponsive, a SIGUSR1 can be passed to
the processes to display where in the code they are running. If encountering a
situation like this, this debug information can be invaluable. First make
sure the master of minion are running in the foreground:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-master \-l debug
salt\-minion \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then pass the signal to the master or minion when it seems to be unresponsive:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
killall \-SIGUSR1 salt\-master
killall \-SIGUSR1 salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Also under BSD and Mac OS X in addition to SIGUSR1 signal, debug subroutine set
up for SIGINFO which has an advantage of being sent by Ctrl+T shortcut.
.sp
When filing an issue or sending questions to the mailing list for a problem
with an unresponsive daemon this information can be invaluable.
.SS Salt 0.16.x minions cannot communicate with a 0.17.x master
.sp
As of release 0.17.1 you can no longer run different versions of Salt on your
Master and Minion servers. This is due to a protocol change for security
purposes. The Salt team will continue to attempt to ensure versions are as
backwards compatible as possible.
.SS Debugging the Master and Minion
.sp
A list of common \fBmaster\fP and
\fBminion\fP troubleshooting steps provide a
starting point for resolving issues you may encounter.
.SH DEVELOPING SALT
.SS Overview
.sp
In its most typical use, Salt is a software application in which clients,
called "minions" can be commanded and controlled from a central command server
called a "master".
.sp
Commands are normally issued to the minions (via the master) by calling a a
client script simply called, \(aqsalt\(aq.
.sp
Salt features a pluggable transport system to issue commands from a master to
minions. The default transport is ZeroMQ.
.SS Salt Client
.SS Overview
.sp
The salt client is run on the same machine as the Salt Master and communicates
with the salt\-master to issue commands and to receive the results and display
them to the user.
.sp
The primary abstraction for the salt client is called \(aqLocalClient\(aq.
.sp
When LocalClient wants to publish a command to minions, it connects to the
master by issuing a request to the master\(aqs ReqServer (TCP: 4506)
.sp
The LocalClient system listens to responses for its requests by listening to
the master event bus publisher (master_event_pub.ipc).
.SS Salt Master
.SS Overview
.sp
The salt\-master deamon runs on the designated Salt master and performs
functions such as authenticating minions, sending and receiving requests
from connected minions and sending and receiving requests and replies to the
\(aqsalt\(aq CLI.
.SS Moving Pieces
.sp
When a Salt master starts up, a number of processes are started, all of which
are called \(aqsalt\-master\(aq in a process\-list but have various role categories.
.sp
Among those categories are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Publisher
.IP \(bu 2
EventPublisher
.IP \(bu 2
MWorker
.UNINDENT
.UNINDENT
.UNINDENT
.SS Publisher
.sp
The Publisher process is responsible for sending commands over the designated
transport to connected minions. The Publisher is bound to the following:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
TCP: port 4505
.IP \(bu 2
IPC: publish_pull.ipc
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Each salt minion establishes a connection to the master Publisher.
.SS EventPublisher
.sp
The EventPublisher publishes events onto the event bus. It is bound to the
following:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
IPC: master_event_pull.ipc
.IP \(bu 2
IPC: master_event_pub.ipc
.UNINDENT
.UNINDENT
.UNINDENT
.SS MWorker
.sp
Worker processes manage the back\-end operations for the Salt Master.
.sp
The number of workers is equivilient to the number of \(aqworker_threads\(aq
specified in the master configuration and is always at least one.
.sp
Workers are bound to the following:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
IPC: workers.ipc
.UNINDENT
.UNINDENT
.UNINDENT
.SS ReqServer
.sp
The Salt request server takes requests and distributes them to available MWorker
processes for processing. It also receives replies back from minions.
.INDENT 0.0
.TP
.B The ReqServer is bound to the following:
.INDENT 7.0
.IP \(bu 2
TCP: 4506
.IP \(bu 2
IPC: workers.ipc
.UNINDENT
.UNINDENT
.sp
Each salt minion establishes a connection to the master ReqServer.
.SS Job Flow
.sp
The Salt master works by always publishing commands to all connected minions
and the minions decide if the command is meant for them by checking themselves
against the command target.
.sp
The typical lifecycle of a salt job from the perspective of the master
might be as follows:
.INDENT 0.0
.IP 1. 3
A command is issued on the CLI. For example, \(aqsalt my_minion test.ping\(aq.
.UNINDENT
.sp
2) The \(aqsalt\(aq command uses LocalClient to generate a request to the salt master
by connecting to the ReqServer on \fI\%TCP:4506\fP and issuing the job.
.sp
3) The salt\-master ReqServer sees the request and passes it to an available
MWorker over workers.ipc.
.sp
4) A worker picks up the request and handles it. First, it checks to ensure
that the requested user has permissions to issue the command. Then, it sends
the publish command to all connected minions. For the curious, this happens
in ClearFuncs.publish().
.sp
5) The worker announces on the master event bus that it is about to publish
a job to conneceted minions. This happens by placing the event on the master
event bus (master_event_pull.ipc) where the EventPublisher picks it up and
distributes it to all connected event listeners on master_event_pub.ipc.
.sp
6) The message to the minions is encrypted and sent to the Publisher via IPC
on publish_pull.ipc.
.sp
7) Connected minions have a TCP session established with the Publisher on TCP
port 4505 where they await commands. When the Publisher receives the job over
publish_pull, it sends the jobs across the wire to the minions for processing.
.sp
8) After the minions receive the request, they decrypt it and perform any
requested work, if they determine that they are targeted to do so.
.sp
9) When the minion is ready to respond, it publishes the result of its job back
to the master by sending the encrypted result back to the master on TCP 4506
where it is again picked up by the ReqServer and forwarded to an available
MWorker for processing. (Again, this happens by passing this message across
workers.ipc to an available worker.)
.sp
10) When the MWorker receives the job it decrypts it and fires an event onto
the master event bus (master_event_pull.ipc). (Again for the curious, this
happens in AESFuncs._return().
.sp
11) The EventPublisher sees this event and re\-publishes it on the bus to all
connected listeners of the master event bus (on master_event_pub.ipc). This
is where the LocalClient has been waiting, listening to the event bus for
minion replies. It gathers the job and stores the result.
.sp
12) When all targeted minions have replied or the timeout has been exceeded,
the salt client displays the results of the job to the user on the CLI.
.SS Salt Minion
.SS Overview
.sp
The salt\-minion is a single process that sits on machines to be managed by
Salt. It can either operate as a stand\-alone daemon which accepts commands
locally via \(aqsalt\-call\(aq or it can connect back to a master and receive commands
remotely.
.sp
When starting up, salt minions connect _back_ to a master defined in the minion
config file. The connect to two ports on the master:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B TCP: 4505
This is the connection to the master Publisher. It is on this port that
the minion receives jobs from the master.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B TCP: 4506
This is the connection to the master ReqServer. It is on this port that
the minion sends job results back to the master.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Event System
.sp
Similar to the master, a salt\-minion has its own event system that operates
over IPC by default. The minion event system operates on a push/pull system
with IPC files at minion_event_<unique_id>_pub.ipc and
minion_event_<unique_id>_pull.ipc.
.sp
The astute reader might ask why have an event bus at all with a single\-process
daemon. The answer is that the salt\-minion may fork other processes as required
to do the work without blocking the main salt\-minion process and this
necessitates a mechanism by which those processes can communicate with each
other. Secondarily, this provides a bus by which any user with sufficient
permissions can read or write to the bus as a common interface with the salt
minion.
.SS Job Flow
.sp
When a salt minion starts up, it attempts to connect to the Publisher and the
ReqServer on the salt master. It then attempts to authenticate and once the
minion has successfully authenticated, it simply listens for jobs.
.sp
Jobs normally come either come from the \(aqsalt\-call\(aq script run by a local user
on the salt minion or they can come directly from a master.
.SS Master Job Flow
.sp
1) A master publishes a job that is received by a minion as outlined by the
master\(aqs job flow above.
.sp
2) The minion is polling its receive socket that\(aqs connected to the master
Publisher (TCP 4505 on master). When it detects an incoming message, it picks it
up from the socket and decrypts it.
.sp
3) A new minion process or thread is created and provided with the contents of the
decrypted message. The _thread_return() method is provided with the contents of
the received message.
.sp
4) The new minion thread is created. The _thread_return() function starts up
and actually calls out to the requested function contained in the job.
.INDENT 0.0
.IP 5. 3
The requested function runs and returns a result. [Still in thread.]
.UNINDENT
.sp
6) The result of the function that\(aqs run is encrypted and returned to the
master\(aqs ReqServer (TCP 4506 on master). [Still in thread.]
.sp
7) Thread exits. Because the main thread was only blocked for the time that it
took to initialize the worker thread, many other requests could have been
received and processed during this time.
.SS A Note on ClearFuncs vs. AESFuncs
.sp
A common source of confusion is deteremining when messages are passed in the
clear and when they are passed using encryption. There are two rules governing
this behaviour:
.sp
1) ClearFuncs is used for intra\-master communication and during the initial
authentication handshake between a minion and master during the key exhange.
.INDENT 0.0
.IP 2. 3
AESFuncs is used everywhere else.
.UNINDENT
.SS Contributing
.sp
There is a great need for contributions to Salt and patches are welcome! The goal
here is to make contributions clear, make sure there is a trail for where the code
has come from, and most importantly, to give credit where credit is due!
.sp
There are a number of ways to contribute to Salt development.
.sp
For details on how to contribute documentation improvements please review
\fIWriting Salt Documentation\fP\&.
.SS Sending a GitHub pull request
.sp
Sending pull requests on GitHub is the preferred method for receiving
contributions. The workflow advice below mirrors \fI\%GitHub\(aqs own guide\fP and is well worth reading.
.INDENT 0.0
.IP 1. 3
Fork the \fI\%saltstack/salt\fP repository on GitHub.
.IP 2. 3
Make a local clone of your fork.
.IP 3. 3
Create a new branch in your clone.
.sp
A branch should have one purpose. For example, "Fix bug X," or "Add feature
Y." Multiple pull requests should be opened for unrelated changes.
.sp
Choose a name for your branch that describes its purpose.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git checkout \-b fixed\-broken\-thing
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
Make edits and changes locally.
.IP 5. 3
Commit changes to this new branch.
.sp
Edit the necessary files in your Salt clone and remember to add them to
your commit. Write a descriptive commit message.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git add path/to/file1
git add path/to/file2
git commit \-m "Fixed X in file1 and file2"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you get stuck \fI\%there are many introductory Git resources on
help.github.com\fP\&.
.IP 6. 3
Push your locally\-committed changes to your GitHub fork.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git push \-\-set\-upstream origin fixed\-broken\-thing
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 7. 3
Go to your fork on the GitHub website & find your branch.
.sp
GitHub automatically displays a button with the text "Compare & pull
request" for recently pushed branches.
.sp
Otherwise click on the "Branches" tab at the top of your fork. A button
with the text "New pull request" will be beside each branch.
.IP 8. 3
Open a new pull request.
.INDENT 3.0
.IP 1. 3
Click one of the pull request buttons from the previous step. GitHub
will present a form and show a comparison of the changes in your pull
request.
.IP 2. 3
Write a descriptive comment, include links to any project issues
related to the pull request.
.IP 3. 3
Click "Create pull request".
.UNINDENT
.IP 9. 3
The Salt repo managers will be notified of your pull request.
.sp
If a reviewer asks for changes:
.INDENT 3.0
.IP 1. 3
Make the changes in your local clone on the same local branch.
.IP 2. 3
Push the branch to GitHub using the same command as before.
.IP 3. 3
The new commits will be reflected in the pull request automatically.
.IP 4. 3
Feel free to add a comment to the discussion.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Jenkins
.sp
Whenever you make a pull request against the main Salt repository your
changes will be tested on a variety of operating systems and
configurations. On average these tests take 30 minutes to run and once
they are complete a PASS/FAIL message will be added to your pull
request. This message contains a link to \fI\%http://jenkins.saltstack.com\fP
where you can review the test results. This message will also generate an
email which will be sent to the email address associated with your GitHub
account informing you of these results. It should be noted that a test
failure does not necessarily mean there is an issue in the associated pull
request as the entire development branch is tested.
.UNINDENT
.UNINDENT
.SS Which Salt branch?
.sp
GitHub will open pull requests against Salt\(aqs main branch named \fBdevelop\fP by
default. Most contributors can keep the default options. This section is for
advanced contributors.
.sp
Each pull request should address a single concern, as mentioned in the section
above. For example, "Fix bug X," or "Add feature Y." And a pull request should
be opened against the branch that corresponds to that concern.
.SS The current release branch
.sp
The current release branch is the most recent stable release. Pull requests
containing bug fixes should be made against the release branch.
.sp
The branch name will be a date\-based name such as \fB2014.7\fP\&.
.sp
Bug fixes are made on this branch so that minor releases can be cut from this
branch without introducing surprises and new features. This approach maximizes
stability.
.sp
The Salt development team will "merge\-forward" any fixes made on the release
branch to the \fBdevelop\fP branch once the pull request has been accepted. This
keeps the fix in isolation on the release branch and also keeps the \fBdevelop\fP
branch up\-to\-date.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Closing GitHub issues from commits
.sp
This "merge\-forward" strategy requires that \fI\%the magic keywords to close a
GitHub issue\fP appear in the commit
message text directly. Only including the text in a pull request will not
close the issue.
.sp
GitHub will close the referenced issue once the \fIcommit\fP containing the
magic text is merged into the default branch (\fBdevelop\fP). Any magic text
input only into the pull request description will not be seen at the
Git\-level when those commits are merged\-forward. In other words, only the
commits are merged\-forward and not the pull request.
.UNINDENT
.UNINDENT
.SS The \fBdevelop\fP branch
.sp
The \fBdevelop\fP branch is unstable and bleeding\-edge. Pull requests containing
feature additions or non\-bug\-fix changes should be made against the \fBdevelop\fP
branch.
.sp
The Salt development team will back\-port bug fixes made to \fBdevelop\fP to the
current release branch if the contributor cannot create the pull request
against that branch.
.SS Keeping Salt Forks in Sync
.sp
Salt is advancing quickly. It is therefore critical to pull upstream changes
from upstream into your fork on a regular basis. Nothing is worse than putting
hard work into a pull request only to see bunches of merge conflicts because it
has diverged too far from upstream.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fI\%GitHub Fork a Repo Guide\fP
.UNINDENT
.UNINDENT
.sp
The following assumes \fBorigin\fP is the name of your fork and \fBupstream\fP is
the name of the main \fI\%saltstack/salt\fP repository.
.INDENT 0.0
.IP 1. 3
View existing remotes.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git remote \-v
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Add the \fBupstream\fP remote.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
# For ssh github
git remote add upstream git@github.com:saltstack/salt.git
# For https github
git remote add upstream https://github.com/saltstack/salt.git
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Pull upstream changes into your clone.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git fetch upstream
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
Update your copy of the \fBdevelop\fP branch.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git checkout develop
git merge \-\-ff\-only upstream/develop
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If Git complains that a fast\-forward merge is not possible, you have local
commits.
.INDENT 3.0
.IP \(bu 2
Run \fBgit pull \-\-rebase origin develop\fP to rebase your changes on top of
the upstream changes.
.IP \(bu 2
Or, run \fBgit branch <branch\-name>\fP to create a new branch with your
commits. You will then need to reset your \fBdevelop\fP branch before
updating it with the changes from upstream.
.UNINDENT
.sp
If Git complains that local files will be overwritten, you have changes to
files in your working directory. Run \fBgit status\fP to see the files in
question.
.IP 5. 3
Update your fork.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git push origin develop
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 6. 3
Repeat the previous two steps for any other branches you work with, such as
the current release branch.
.UNINDENT
.SS Posting patches to the mailing list
.sp
Patches will also be accepted by email. Format patches using \fI\%git
format\-patch\fP and send them to the \fI\%salt\-users\fP mailing list. The contributor
will then get credit for the patch, and the Salt community will have an archive
of the patch and a place for discussion.
.SS Backporting Pull Requests
.sp
If a bug is fixed on \fBdevelop\fP and the bug is also present on a
currently\-supported release branch it will need to be back\-ported to all
applicable branches.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Most Salt contributors can skip these instructions
.sp
These instructions do not need to be read in order to contribute to the
Salt project! The SaltStack team will back\-port fixes on behalf of
contributors in order to keep the contribution process easy.
.sp
These instructions are intended for frequent Salt contributors, advanced
Git users, SaltStack employees, or independent souls who wish to back\-port
changes themselves.
.UNINDENT
.UNINDENT
.sp
It is often easiest to fix a bug on the oldest supported release branch and
then merge that branch forward into \fBdevelop\fP (as described earlier in this
document). When that is not possible the fix must be back\-ported, or copied,
into any other affected branches.
.sp
These steps assume a pull request \fB#1234\fP has been merged into \fBdevelop\fP\&.
And \fBupstream\fP is the name of the remote pointing to the main Salt repo.
.INDENT 0.0
.IP 1. 3
Identify the oldest supported release branch that is affected by the bug.
.IP 2. 3
Create a new branch for the back\-port by reusing the same branch from the
original pull request.
.sp
Name the branch \fBbp\-<NNNN>\fP and use the number of the original pull
request.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git fetch upstream refs/pull/1234/head:bp\-1234
git checkout bp\-1234
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Find the parent commit of the original pull request.
.sp
The parent commit of the original pull request must be known in order to
rebase onto a release branch. The easiest way to find this is on GitHub.
.sp
Open the original pull request on GitHub and find the first commit in the
list of commits. Select and copy the SHA for that commit. The parent of
that commit can be specified by appending \fB~1\fP to the end.
.IP 4. 3
Rebase the new branch on top of the release branch.
.INDENT 3.0
.IP \(bu 2
\fB<release\-branch>\fP is the branch identified in step #1.
.IP \(bu 2
\fB<orig\-base>\fP is the SHA identified in step #3 \-\- don\(aqt forget to add
\fB~1\fP to the end!
.UNINDENT
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git rebase \-\-onto <release\-branch> <orig\-base> bp\-1234
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note, release branches prior to \fB2014.7\fP will not be able to make use of
rebase and must use cherry\-picking instead.
.IP 5. 3
Push the back\-port branch to GitHub and open a new pull request.
.sp
Opening a pull request for the back\-port allows for the test suite and
normal code\-review process.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
git push \-u origin bp\-1234
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Deprecating Code
.sp
Salt should remain backwards compatible, though sometimes, this backwards
compatibility needs to be broken because a specific feature and/or solution is
no longer necessary or required. At first one might think, let me change this
code, it seems that it\(aqs not used anywhere else so it should be safe to remove.
Then, once there\(aqs a new release, users complain about functionality which was
removed and they where using it, etc. This should, at all costs, be avoided,
and, in these cases, \fIthat\fP specific code should be deprecated.
.sp
Depending on the complexity and usage of a specific piece of code, the
deprecation time frame should be properly evaluated. As an example, a
deprecation warning which is shown for 2 major releases, for example \fI0.17.0\fP
and \fI2014.1.0\fP, gives users enough time to stop using the deprecated code and
adapt to the new one.
.sp
For example, if you\(aqre deprecating the usage of a keyword argument to a
function, that specific keyword argument should remain in place for the full
deprecation time frame and if that keyword argument is used, a deprecation
warning should be shown to the user.
.sp
To help in this deprecation task, salt provides \fBsalt.utils.warn_until\fP\&. The idea behind this helper function is to show the
deprecation warning until salt reaches the provided version. Once that provided
version is equaled \fBsalt.utils.warn_until\fP will
raise a \fI\%RuntimeError\fP making salt stop its execution. This stoppage
is unpleasant and will remind the developer that the deprecation limit has been
reached and that the code can then be safely removed.
.sp
Consider the following example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def some_function(bar=False, foo=None):
if foo is not None:
salt.utils.warn_until(
(0, 18),
\(aqThe \e\(aqfoo\e\(aq argument has been deprecated and its \(aq
\(aqfunctionality removed, as such, its usage is no longer \(aq
\(aqrequired.\(aq
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Consider that the current salt release is \fB0.16.0\fP\&. Whenever \fBfoo\fP is
passed a value different from \fBNone\fP that warning will be shown to the user.
This will happen in versions \fB0.16.2\fP to \fB2014.1.0\fP, after which a
\fI\%RuntimeError\fP will be raised making us aware that the deprecated code
should now be removed.
.SS Dunder Dictionaries
.sp
Salt provides several special "dunder" dictionaries as a convenience for Salt
development. These include \fB__opts__\fP, \fB__context__\fP, \fB__salt__\fP, and
others. This document will describe each dictionary and detail where they exist
and what information and/or functionality they provide.
.SS __opts__
.SS Available in
.INDENT 0.0
.IP \(bu 2
All loader modules
.UNINDENT
.sp
The \fB__opts__\fP dictionary contains all of the options passed in the
configuration file for the master or minion.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In many places in salt, instead of pulling raw data from the __opts__
dict, configuration data should be pulled from the salt \fIget\fP functions
such as config.get, aka \- __salt__[\(aqconfig.get\(aq](\(aqfoo:bar\(aq)
The \fIget\fP functions also allow for dict traversal via the \fI:\fP delimiter.
Consider using get functions whenever using __opts__ or __pillar__ and
__grains__ (when using grains for configuration data)
.UNINDENT
.UNINDENT
.sp
The configuration file data made available in the \fB__opts__\fP dictionary is the
configuration data relative to the running daemon. If the modules are loaded and
executed by the master, then the master configuration data is available, if the
modules are executed by the minion, then the minion configuration is
available. Any additional information passed into the respective configuration
files is made available
.SS __salt__
.SS Available in
.INDENT 0.0
.IP \(bu 2
Execution Modules
.IP \(bu 2
State Modules
.IP \(bu 2
Returners
.UNINDENT
.sp
\fB__salt__\fP contains the execution module functions. This allows for all
functions to be called as they have been set up by the salt loader.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__salt__[\(aqcmd.run\(aq](\(aqfdisk \-l\(aq)
__salt__[\(aqnetwork.ip_addrs\(aq]()
.ft P
.fi
.UNINDENT
.UNINDENT
.SS __grains__
.SS Available in
.INDENT 0.0
.IP \(bu 2
Execution Modules
.IP \(bu 2
State Modules
.IP \(bu 2
Returners
.IP \(bu 2
External Pillar
.UNINDENT
.sp
The \fB__grains__\fP dictionary contains the grains data generated by the minion
that is currently being worked with. In execution modules, state modules and
returners this is the grains of the minion running the calls, when generating
the external pillar the \fB__grains__\fP is the grains data from the minion that
the pillar is being generated for.
.SS __pillar__
.SS Available in
.INDENT 0.0
.IP \(bu 2
Execution Modules
.IP \(bu 2
State Modules
.IP \(bu 2
Returners
.UNINDENT
.sp
The \fB__pillar__\fP dictionary contains the pillar for the respective minion.
.SS __context__
.sp
\fB__context__\fP exists in state modules and execution modules.
.sp
During a state run the \fB__context__\fP dictionary persists across all states
that are run and then is destroyed when the state ends.
.sp
When running an execution module \fB__context__\fP persists across all module
executions until the modules are refreshed; such as when \fBsaltutils.sync_all\fP
or \fBstate.highstate\fP are executed.
.sp
A great place to see how to use \fB__context__\fP is in the cp.py module in
salt/modules/cp.py. The fileclient authenticates with the master when it is
instantiated and then is used to copy files to the minion. Rather than create a
new fileclient for each file that is to be copied down, one instance of the
fileclient is instantiated in the \fB__context__\fP dictionary and is reused for
each file. Here is an example from salt/modules/cp.py:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
if not \(aqcp.fileclient\(aq in __context__:
__context__[\(aqcp.fileclient\(aq] = salt.fileclient.get_file_client(__opts__)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Because __context__ may or may not have been destroyed, always be
sure to check for the existence of the key in __context__ and
generate the key before using it.
.UNINDENT
.UNINDENT
.SS External Pillars
.sp
Salt provides a mechanism for generating pillar data by calling external
pillar interfaces. This document will describe an outline of an ext_pillar
module.
.SS Location
.sp
Salt expects to find your \fBext_pillar\fP module in the same location where it
looks for other python modules. If the \fBextension_modules\fP option in your
Salt master configuration is set, Salt will look for a \fBpillar\fP directory
under there and load all the modules it finds. Otherwise, it will look in
your Python site\-packages \fBsalt/pillar\fP directory.
.SS Configuration
.sp
The external pillars that are called when a minion refreshes its pillars is
controlled by the \fBext_pillar\fP option in the Salt master configuration. You
can pass a single argument, a list of arguments or a dictionary of arguments
to your pillar:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- example_a: some argument
\- example_b:
\- argumentA
\- argumentB
\- example_c:
keyA: valueA
keyB: valueB
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The Module
.SS Imports and Logging
.sp
Import modules your external pillar module needs. You should first include
generic modules that come with stock Python:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import logging
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And then start logging. This is an idiomatic way of setting up logging in Salt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log = logging.getLogger(__name__)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, load modules that are specific to what you are doing. You should catch
import errors and set a flag that the \fB__virtual__\fP function can use later.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
try:
import weird_thing
EXAMPLE_A_LOADED = True
except ImportError:
EXAMPLE_A_LOADED = False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Options
.sp
If you define an \fB__opts__\fP dictionary, it will be merged into the
\fB__opts__\fP dictionary handed to the \fBext_pillar\fP function later. This is a
good place to put default configuration items. The convention is to name
things \fBmodulename.option\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__opts__ = { \(aqexample_a.someconfig\(aq: 137 }
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Initialization
.sp
If you define an \fB__init__\fP function, it will be called with the following
signature:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def __init__( __opts__ ):
# Do init work here
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNote\fP: The \fB__init__\fP function is ran every time a particular minion causes
the external pillar to be called, so don\(aqt put heavy initialization code here.
The \fB__init__\fP functionality is a side\-effect of the Salt loader, so it may
not be as useful in pillars as it is in other Salt items.
.SS __virtual__
.sp
If you define a \fB__virtual__\fP function, you can control whether or not this
module is visible. If it returns \fBFalse\fP then Salt ignores this module. If
it returns a string, then that string will be how Salt identifies this external
pillar in its \fBext_pillar\fP configuration. If you\(aqre not renaming the module,
simply return \fBTrue\fP in the \fB__virtual__\fP function, which is the same as if
this function did not exist, then, the name Salt\(aqs \fBext_pillar\fP will use to
identify this module is its conventional name in Python.
.sp
This is useful to write modules that can be installed on all Salt masters, but
will only be visible if a particular piece of software your module requires is
installed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# This external pillar will be known as \(gaexample_a\(ga
def __virtual__():
if EXAMPLE_A_LOADED:
return True
return False
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# This external pillar will be known as \(gasomething_else\(ga
__virtualname__ = \(aqsomething_else\(aq
def __virtual__():
if EXAMPLE_A_LOADED:
return __virtualname__
return False
.ft P
.fi
.UNINDENT
.UNINDENT
.SS ext_pillar
.sp
This is where the real work of an external pillar is done. If this module is
active and has a function called \fBext_pillar\fP, whenever a minion updates its
pillar this function is called.
.sp
How it is called depends on how it is configured in the Salt master
configuration. The first argument is always the current pillar dictionary, this
contains pillar items that have already been added, starting with the data from
\fBpillar_roots\fP, and then from any already\-ran external pillars.
.sp
Using our example above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar( id, pillar, \(aqsome argument\(aq ) # example_a
ext_pillar( id, pillar, \(aqargumentA\(aq, \(aqargumentB\(aq ) # example_b
ext_pillar( id, pillar, keyA=\(aqvalueA\(aq, keyB=\(aqvalueB\(aq } ) # example_c
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the \fBexample_a\fP case, \fBpillar\fP will contain the items from the
\fBpillar_roots\fP, in \fBexample_b\fP \fBpillar\fP will contain that plus the items
added by \fBexample_a\fP, and in \fBexample_c\fP \fBpillar\fP will contain that plus
the items added by \fBexample_b\fP\&. In all three cases, \fBid\fP will contain the
ID of the minion making the pillar request.
.sp
This function should return a dictionary, the contents of which are merged in
with all of the other pillars and returned to the minion. \fBNote\fP: this function
is called once for each minion that fetches its pillar data.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def ext_pillar( minion_id, pillar, *args, **kwargs ):
my_pillar = {}
# Do stuff
return my_pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You shouldn\(aqt just add items to \fBpillar\fP and return that, since that will
cause Salt to merge data that already exists. Rather, just return the items
you are adding or changing. You could, however, use \fBpillar\fP in your module
to make some decision based on pillar data that already exists.
.sp
This function has access to some useful globals:
.INDENT 0.0
.TP
.B __opts__
A dictionary of mostly Salt configuration options. If you had an
\fB__opts__\fP dictionary defined in your module, those values will be
included.
.TP
.B __salt__
A dictionary of Salt module functions, useful so you don\(aqt have to
duplicate functions that already exist. E.g.
\fB__salt__[\(aqcmd.run\(aq]( \(aqls \-l\(aq )\fP \fBNote\fP, runs on the \fImaster\fP
.TP
.B __grains__
A dictionary of the grains of the minion making this pillar call.
.UNINDENT
.SS Example configuration
.sp
As an example, if you wanted to add external pillar via the \fBcmd_json\fP
external pillar, add something like this to your master config:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- cmd_json: \(aqecho {\e"arg\e":\e"value\e"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reminder
.sp
Just as with traditional pillars, external pillars must be refreshed in order for
minions to see any fresh data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq saltutil.refresh_pillar
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Installing Salt for development
.sp
Clone the repository using:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git clone https://github.com/saltstack/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
tags
.sp
Just cloning the repository is enough to work with Salt and make
contributions. However, fetching additional tags from git is required to
have Salt report the correct version for itself. To do this, first
add the git repository as an upstream source:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git remote add upstream https://github.com/saltstack/salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Fetching tags is done with the git \(aqfetch\(aq utility:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
git fetch \-\-tags upstream
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Create a new \fI\%virtualenv\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
virtualenv /path/to/your/virtualenv
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Arch Linux, where Python 3 is the default installation of Python, use the
\fBvirtualenv2\fP command instead of \fBvirtualenv\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Using system Python modules in the virtualenv
.sp
To use already\-installed python modules in virtualenv (instead of having pip
download and compile new ones), run \fBvirtualenv \-\-system\-site\-packages\fP
Using this method eliminates the requirement to install the salt dependencies
again, although it does assume that the listed modules are all installed in the
system PYTHONPATH at the time of virtualenv creation.
.UNINDENT
.UNINDENT
.sp
Activate the virtualenv:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source /path/to/your/virtualenv/bin/activate
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install Salt (and dependencies) into the virtualenv:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install M2Crypto # Don\(aqt install on Debian/Ubuntu (see below)
pip install pyzmq PyYAML pycrypto msgpack\-python jinja2 psutil
pip install \-e ./salt # the path to the salt git clone from above
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Installing M2Crypto
.sp
\fBswig\fP and \fBlibssl\-dev\fP are required to build M2Crypto. To fix
the error \fBcommand \(aqswig\(aq failed with exit status 1\fP while installing M2Crypto,
try installing it with the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
env SWIG_FEATURES="\-cpperraswarn \-includeall \-D__\(gauname \-m\(ga__ \-I/usr/include/openssl" pip install M2Crypto
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Debian and Ubuntu systems have modified openssl libraries and mandate that
a patched version of M2Crypto be installed. This means that M2Crypto
needs to be installed via apt:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apt\-get install python\-m2crypto
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This also means that pulling in the M2Crypto installed using apt requires using
\fB\-\-system\-site\-packages\fP when creating the virtualenv.
.sp
If you\(aqre using a platform other than Debian or Ubuntu, and you are
installing M2Crypto via pip instead of a system package, then you will also
need the \fBgcc\fP compiler.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Installing psutil
.sp
Python header files are required to build this module, otherwise the pip
install will fail. If your distribution separates binaries and headers into
separate packages, make sure that you have the headers installed. In most
Linux distributions which split the headers into their own package, this
can be done by installing the \fBpython\-dev\fP or \fBpython\-devel\fP package.
For other platforms, the package will likely be similarly named.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Installing dependencies on OS X.
.sp
You can install needed dependencies on OS X using homebrew or macports.
See \fBOS X Installation\fP
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Installing on RedHat\-based Distros
.sp
If installing from pip (or from source using \fBsetup.py install\fP), be
advised that the \fByum\-utils\fP package is needed for Salt to manage
packages on RedHat\-based systems.
.UNINDENT
.UNINDENT
.SS Running a self\-contained development version
.sp
During development it is easiest to be able to run the Salt master and minion
that are installed in the virtualenv you created above, and also to have all
the configuration, log, and cache files contained in the virtualenv as well.
.sp
Copy the master and minion config files into your virtualenv:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mkdir \-p /path/to/your/virtualenv/etc/salt
cp ./salt/conf/master /path/to/your/virtualenv/etc/salt/master
cp ./salt/conf/minion /path/to/your/virtualenv/etc/salt/minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Edit the master config file:
.INDENT 0.0
.IP 1. 3
Uncomment and change the \fBuser: root\fP value to your own user.
.IP 2. 3
Uncomment and change the \fBroot_dir: /\fP value to point to
\fB/path/to/your/virtualenv\fP\&.
.IP 3. 3
If you are running version 0.11.1 or older, uncomment and change the
\fBpidfile: /var/run/salt\-master.pid\fP value to point to
\fB/path/to/your/virtualenv/salt\-master.pid\fP\&.
.IP 4. 3
If you are also running a non\-development version of Salt you will have to
change the \fBpublish_port\fP and \fBret_port\fP values as well.
.UNINDENT
.sp
Edit the minion config file:
.INDENT 0.0
.IP 1. 3
Repeat the edits you made in the master config for the \fBuser\fP and
\fBroot_dir\fP values as well as any port changes.
.IP 2. 3
If you are running version 0.11.1 or older, uncomment and change the
\fBpidfile: /var/run/salt\-minion.pid\fP value to point to
\fB/path/to/your/virtualenv/salt\-minion.pid\fP\&.
.IP 3. 3
Uncomment and change the \fBmaster: salt\fP value to point at \fBlocalhost\fP\&.
.IP 4. 3
Uncomment and change the \fBid:\fP value to something descriptive like
"saltdev". This isn\(aqt strictly necessary but it will serve as a reminder of
which Salt installation you are working with.
.IP 5. 3
If you changed the \fBret_port\fP value in the master config because you are
also running a non\-development version of Salt, then you will have to
change the \fBmaster_port\fP value in the minion config to match.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Using \fIsalt\-call\fP with a \fBStandalone Minion\fP
.sp
If you plan to run \fIsalt\-call\fP with this self\-contained development
environment in a masterless setup, you should invoke \fIsalt\-call\fP with
\fB\-c /path/to/your/virtualenv/etc/salt\fP so that salt can find the minion
config file. Without the \fB\-c\fP option, Salt finds its config files in
\fI/etc/salt\fP\&.
.UNINDENT
.UNINDENT
.sp
Start the master and minion, accept the minion\(aqs key, and verify your local Salt
installation is working:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd /path/to/your/virtualenv
salt\-master \-c ./etc/salt \-d
salt\-minion \-c ./etc/salt \-d
salt\-key \-c ./etc/salt \-L
salt\-key \-c ./etc/salt \-A
salt \-c ./etc/salt \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Running the master and minion in debug mode can be helpful when developing. To
do this, add \fB\-l debug\fP to the calls to \fBsalt\-master\fP and \fBsalt\-minion\fP\&.
If you would like to log to the console instead of to the log file, remove the
\fB\-d\fP\&.
.sp
Once the minion starts, you may see an error like the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" is longer than 107 characters (sizeof(sockaddr_un.sun_path)).
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This means the the path to the socket the minion is using is too long. This is
a system limitation, so the only workaround is to reduce the length of this
path. This can be done in a couple different ways:
.INDENT 0.0
.IP 1. 3
Create your virtualenv in a path that is short enough.
.IP 2. 3
Edit the \fBsock_dir\fP minion config variable and reduce its
length. Remember that this path is relative to the value you set in
\fBroot_dir\fP\&.
.UNINDENT
.sp
\fBNOTE:\fP The socket path is limited to 107 characters on Solaris and Linux,
and 103 characters on BSD\-based systems.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
File descriptor limits
.sp
Ensure that the system open file limit is raised to at least 2047:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# check your current limit
ulimit \-n
# raise the limit. persists only until reboot
# use \(aqlimit descriptors 2047\(aq for c\-shell
ulimit \-n 2047
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To set file descriptors on OSX, refer to the \fBOS X Installation\fP instructions.
.UNINDENT
.UNINDENT
.SS Installing Salt from the Python Package Index
.sp
If you are installing using \fBeasy_install\fP, you will need to define a
\fBUSE_SETUPTOOLS\fP environment variable, otherwise dependencies will not
be installed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
USE_SETUPTOOLS=1 easy_install salt
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Editing and previewing the documentation
.sp
You need \fBsphinx\-build\fP command to build the docs. In Debian/Ubuntu this is
provided in the \fBpython\-sphinx\fP package. Sphinx can also be installed
to a virtualenv using pip:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install Sphinx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Change to salt documentation directory, then:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd doc; make html
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
This will build the HTML docs. Run \fBmake\fP without any arguments to see the
available make targets, which include \fBhtml\fP, \fBman\fP, and
\fBtext\fP\&.
.IP \(bu 2
The docs then are built within the \fBdocs/_build/\fP folder. To update
the docs after making changes, run \fBmake\fP again.
.IP \(bu 2
The docs use \fI\%reStructuredText\fP for markup.
See a live demo at \fI\%http://rst.ninjs.org/\fP\&.
.IP \(bu 2
The help information on each module or state is culled from the python code
that runs for that piece. Find them in \fBsalt/modules/\fP or \fBsalt/states/\fP\&.
.IP \(bu 2
To build the docs on Arch Linux, the \fBpython2\-sphinx\fP package is
required. Additionally, it is necessary to tell \fBmake\fP where to find
the proper \fBsphinx\-build\fP binary, like so:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make SPHINXBUILD=sphinx\-build2 html
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
To build the docs on RHEL/CentOS 6, the \fBpython\-sphinx10\fP package
must be installed from EPEL, and the following make command must be used:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make SPHINXBUILD=sphinx\-1.0\-build html
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once you\(aqve updated the documentation, you can run the following command to
launch a simple Python HTTP server to see your changes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd _build/html; python \-m SimpleHTTPServer
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Running unit and integration tests
.sp
Run the test suite with following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./setup.py test
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See \fBhere\fP for more information regarding the test suite.
.SS Logging Internals
.sp
TODO
.SS Modular Systems
.sp
When first working with Salt, it is not always clear where all of the modular
components are and what they do. Salt comes loaded with more modular systems
than many users are aware of, making Salt very easy to extend in many places.
.sp
The most commonly used modular systems are execution modules and states. But
the modular systems extend well beyond the more easily exposed components
and are often added to Salt to make the complete system more flexible.
.SS Execution Modules
.sp
Execution modules make up the core of the functionality used by Salt to
interact with client systems. The execution modules create the core system
management library used by all Salt systems, including states, which
interact with minion systems.
.sp
Execution modules are completely open ended in their execution. They can
be used to do anything required on a minion, from installing packages to
detecting information about the system. The only restraint in execution
modules is that the defined functions always return a JSON serializable
object.
.sp
For a list of all built in execution modules, click \fBhere\fP
.sp
For information on writing execution modules, see \fBthis page\fP\&.
.SS State Modules
.sp
State modules are used to define the state interfaces used by Salt States.
These modules are restrictive in that they must follow a number of rules to
function properly.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
State modules define the available routines in sls files. If calling
an execution module directly is desired, take a look at the \fImodule\fP
state.
.UNINDENT
.UNINDENT
.SS Auth
.sp
The auth module system allows for external authentication routines to be easily
added into Salt. The \fIauth\fP function needs to be implemented to satisfy the
requirements of an auth module. Use the \fBpam\fP module as an example.
.SS Fileserver
.sp
The fileserver module system is used to create fileserver backends used by the
Salt Master. These modules need to implement the functions used in the
fileserver subsystem. Use the \fBgitfs\fP module as an example.
.SS Grains
.sp
Grain modules define extra routines to populate grains data. All defined
public functions will be executed and MUST return a Python dict object. The
dict keys will be added to the grains made available to the minion.
.SS Output
.sp
The output modules supply the outputter system with routines to display data
in the terminal. These modules are very simple and only require the \fIoutput\fP
function to execute. The default system outputter is the \fBnested\fP module.
.SS Pillar
.sp
Used to define optional external pillar systems. The pillar generated via
the filesystem pillar is passed into external pillars. This is commonly used
as a bridge to database data for pillar, but is also the backend to the libvirt
state used to generate and sign libvirt certificates on the fly.
.SS Renderers
.sp
Renderers are the system used to render sls files into salt highdata for the
state compiler. They can be as simple as the \fBpy\fP renderer and as complex as
\fBstateconf\fP and \fBpydsl\fP\&.
.SS Returners
.sp
Returners are used to send data from minions to external sources, commonly
databases. A full returner will implement all routines to be supported as an
external job cache. Use the \fBredis\fP returner as an example.
.SS Runners
.sp
Runners are purely master\-side execution sequences. These range from simple
reporting to orchestration engines like the overstate.
.SS Tops
.sp
Tops modules are used to convert external data sources into top file data for
the state system.
.SS Wheel
.sp
The wheel system is used to manage master side management routines. These
routines are primarily intended for the API to enable master configuration.
.SS Package Providers
.sp
This page contains guidelines for writing package providers.
.SS Package Functions
.sp
One of the most important features of Salt is package management. There is no
shortage of package managers, so in the interest of providing a consistent
experience in \fBpkg\fP states, there are certain functions
that should be present in a package provider. Note that these are subject to
change as new features are added or existing features are enhanced.
.SS list_pkgs
.sp
This function should declare an empty dict, and then add packages to it by
calling \fBpkg_resource.add_pkg\fP, like
so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__salt__[\(aqpkg_resource.add_pkg\(aq](ret, name, version)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The last thing that should be done before returning is to execute
\fBpkg_resource.sort_pkglist\fP\&. This
function does not presently do anything to the return dict, but will be used in
future versions of Salt.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__salt__[\(aqpkg_resource.sort_pkglist\(aq](ret)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBlist_pkgs\fP returns a dictionary of installed packages, with the keys being
the package names and the values being the version installed. Example return
data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqfoo\(aq: \(aq1.2.3\-4\(aq,
\(aqbar\(aq: \(aq5.6.7\-8\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS latest_version
.sp
Accepts an arbitrary number of arguments. Each argument is a package name. The
return value for a package will be an empty string if the package is not found
or if the package is up\-to\-date. The only case in which a non\-empty string is
returned is if the package is available for new installation (i.e. not already
installed) or if there is an upgrade available.
.sp
If only one argument was passed, this function return a string, otherwise a
dict of name/version pairs is returned.
.sp
This function must also accept \fB**kwargs\fP, in order to receive the
\fBfromrepo\fP and \fBrepo\fP keyword arguments from pkg states. Where supported,
these arguments should be used to find the install/upgrade candidate in the
specified repository. The \fBfromrepo\fP kwarg takes precedence over \fBrepo\fP, so
if both of those kwargs are present, the repository specified in \fBfromrepo\fP
should be used. However, if \fBrepo\fP is used instead of \fBfromrepo\fP, it should
still work, to preserve backwards compatibility with older versions of Salt.
.SS version
.sp
Like \fBlatest_version\fP, accepts an arbitrary number of arguments and
returns a string if a single package name was passed, or a dict of name/value
pairs if more than one was passed. The only difference is that the return
values are the currently\-installed versions of whatever packages are passed. If
the package is not installed, an empty string is returned for that package.
.SS upgrade_available
.sp
Deprecated and destined to be removed. For now, should just do the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
return __salt__[\(aqpkg.latest_version\(aq](name) != \(aq\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS install
.sp
The following arguments are required and should default to \fBNone\fP:
.INDENT 0.0
.IP 1. 3
name (for single\-package pkg states)
.IP 2. 3
pkgs (for multiple\-package pkg states)
.IP 3. 3
sources (for binary package file installation)
.UNINDENT
.sp
The first thing that this function should do is call
\fBpkg_resource.parse_targets\fP
(see below). This function will convert the SLS input into a more easily parsed
data structure.
\fBpkg_resource.parse_targets\fP may
need to be modified to support your new package provider, as it does things
like parsing package metadata which cannot be done for every package management
system.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pkg_params, pkg_type = __salt__[\(aqpkg_resource.parse_targets\(aq](name,
pkgs,
sources)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Two values will be returned to the \fBinstall\fP function. The first of
them will be a dictionary. The keys of this dictionary will be package names,
though the values will differ depending on what kind of installation is being
done:
.INDENT 0.0
.IP \(bu 2
If \fBname\fP was provided (and \fBpkgs\fP was not), then there will
be a single key in the dictionary, and its value will be \fBNone\fP\&. Once the
data has been returned, if the \fBversion\fP keyword argument was
provided, then it should replace the \fBNone\fP value in the dictionary.
.IP \(bu 2
If \fBpkgs\fP was provided, then \fBname\fP is ignored, and the
dictionary will contain one entry for each package in the \fBpkgs\fP
list. The values in the dictionary will be \fBNone\fP if a version was not
specified for the package, and the desired version if specified. See the
\fBMultiple Package Installation Options\fP section of the
\fBpkg.installed\fP state for more info.
.IP \(bu 2
If \fBsources\fP was provided, then \fBname\fP is ignored, and the
dictionary values will be the path/URI for the package.
.UNINDENT
.sp
The second return value will be a string with two possible values:
\fBrepository\fP or \fBfile\fP\&. The \fBinstall\fP function can use this value
(if necessary) to build the proper command to install the targeted package(s).
.sp
Both before and after the installing the target(s), you should run
\fBlist_pkgs\fP to obtain a list of the installed packages. You should then
return the output of \fBsalt.utils.compare_dicts()\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
return salt.utils.compare_dicts(old, new)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS remove
.sp
Removes the passed package and return a list of the packages removed.
.SS Package Repo Functions
.sp
There are some functions provided by \fBpkg\fP which are specific to package
repositories, and not to packages themselves. When writing modules for new
package managers, these functions should be made available as stated below, in
order to provide compatibility with the \fBpkgrepo\fP state.
.sp
All repo functions should accept a basedir option, which defines which
directory repository configuration should be found in. The default for this
is dictated by the repo manager that is being used, and rarely needs to be
changed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
basedir = \(aq/etc/yum.repos.d\(aq
__salt__[\(aqpkg.list_repos\(aq](basedir)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS list_repos
.sp
Lists the repositories that are currently configured on this system.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__salt__[\(aqpkg.list_repos\(aq]()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a dictionary, in the following format:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqreponame\(aq: \(aqconfig_key_1\(aq: \(aqconfig value 1\(aq,
\(aqconfig_key_2\(aq: \(aqconfig value 2\(aq,
\(aqconfig_key_3\(aq: [\(aqlist item 1 (when appropriate)\(aq,
\(aqlist item 2 (when appropriate)]}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS get_repo
.sp
Displays all local configuration for a specific repository.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__salt__[\(aqpkg.get_repo\(aq](repo=\(aqmyrepo\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The information is formatted in much the same way as list_repos, but is
specific to only one repo.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqconfig_key_1\(aq: \(aqconfig value 1\(aq,
\(aqconfig_key_2\(aq: \(aqconfig value 2\(aq,
\(aqconfig_key_3\(aq: [\(aqlist item 1 (when appropriate)\(aq,
\(aqlist item 2 (when appropriate)]}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS del_repo
.sp
Removes the local configuration for a specific repository. Requires a \fIrepo\fP
argument, which must match the locally configured name. This function returns
a string, which informs the user as to whether or not the operation was a
success.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__salt__[\(aqpkg.del_repo\(aq](repo=\(aqmyrepo\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS mod_repo
.sp
Modify the local configuration for one or more option for a configured repo.
This is also the way to create new repository configuration on the local
system; if a repo is specified which does not yet exist, it will be created.
.sp
The options specified for this function are specific to the system; please
refer to the documentation for your specific repo manager for specifics.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
__salt__[\(aqpkg.mod_repo\(aq](repo=\(aqmyrepo\(aq, url=\(aqhttp://myurl.com/repo\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Low\-Package Functions
.sp
In general, the standard package functions as describes above will meet your
needs. These functions use the system\(aqs native repo manager (for instance,
yum or the apt tools). In most cases, the repo manager is actually separate
from the package manager. For instance, yum is usually a front\-end for rpm, and
apt is usually a front\-end for dpkg. When possible, the package functions that
use those package managers directly should do so through the low package
functions.
.sp
It is normal and sane for \fBpkg\fP to make calls to \fBlowpkgs\fP, but \fBlowpkg\fP
must never make calls to \fBpkg\fP\&. This is affects functions which are required
by both \fBpkg\fP and \fBlowpkg\fP, but the technique in \fBpkg\fP is more performant
than what is available to \fBlowpkg\fP\&. When this is the case, the \fBlowpkg\fP
function that requires that technique must still use the \fBlowpkg\fP version.
.SS list_pkgs
.sp
Returns a dict of packages installed, including the package name and version.
Can accept a list of packages; if none are specified, then all installed
packages will be listed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
installed = __salt__[\(aqlowpkg.list_pkgs\(aq](\(aqfoo\(aq, \(aqbar\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqfoo\(aq: \(aq1.2.3\-4\(aq,
\(aqbar\(aq: \(aq5.6.7\-8\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS verify
.sp
Many (but not all) package management systems provide a way to verify that the
files installed by the package manager have or have not changed. This function
accepts a list of packages; if none are specified, all packages will be
included.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
installed = __salt__[\(aqlowpkg.verify\(aq](\(aqhttpd\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aq/etc/httpd/conf/httpd.conf\(aq: {\(aqmismatch\(aq: [\(aqsize\(aq, \(aqmd5sum\(aq, \(aqmtime\(aq],
\(aqtype\(aq: \(aqconfig\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS file_list
.sp
Lists all of the files installed by all packages specified. If not packages are
specified, then all files for all known packages are returned.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
installed = __salt__[\(aqlowpkg.file_list\(aq](\(aqhttpd\(aq, \(aqapache\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function does not return which files belong to which packages; all files
are returned as one giant list (hence the \fIfile_list\fP function name. However,
This information is still returned inside of a dict, so that it can provide
any errors to the user in a sane manner.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqerrors\(aq: [\(aqpackage apache is not installed\(aq],
\(aqfiles\(aq: [\(aq/etc/httpd\(aq,
\(aq/etc/httpd/conf\(aq,
\(aq/etc/httpd/conf.d\(aq,
\(aq...SNIP...\(aq]}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS file_dict
.sp
Lists all of the files installed by all packages specified. If not packages are
specified, then all files for all known packages are returned.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
installed = __salt__[\(aqlowpkg.file_dict\(aq](\(aqhttpd\(aq, \(aqapache\(aq, \(aqkernel\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Unlike \fIfile_list\fP, this function will break down which files belong to which
packages. It will also return errors in the same manner as \fIfile_list\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{\(aqerrors\(aq: [\(aqpackage apache is not installed\(aq],
\(aqpackages\(aq: {\(aqhttpd\(aq: [\(aq/etc/httpd\(aq,
\(aq/etc/httpd/conf\(aq,
\(aq...SNIP...\(aq],
\(aqkernel\(aq: [\(aq/boot/.vmlinuz\-2.6.32\-279.el6.x86_64.hmac\(aq,
\(aq/boot/System.map\-2.6.32\-279.el6.x86_64\(aq,
\(aq...SNIP...\(aq]}}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Community Projects That Use Salt
.sp
Below is a list of repositories that show real world Salt applications that
you can use to get started. Please note that these projects do not adhere to
any standards and express a wide variety of ideas and opinions on how an
action can be completed with Salt.
.sp
\fI\%https://github.com/terminalmage/djangocon2013\-sls\fP
.sp
\fI\%https://github.com/jesusaurus/hpcs\-salt\-state\fP
.sp
\fI\%https://github.com/gravyboat/hungryadmin\-sls\fP
.sp
\fI\%https://github.com/wunki/django\-salted\fP
.SS Salt Topology
.sp
Salt is based on a powerful, asynchronous, network topology using ZeroMQ. Many
ZeroMQ systems are in place to enable communication. The central idea is to
have the fastest communication possible.
.SS Servers
.sp
The Salt Master runs 2 network services. First is the ZeroMQ PUB system. This
service by default runs on port \fB4505\fP and can be configured via the
\fBpublish_port\fP option in the master configuration.
.sp
Second is the ZeroMQ REP system. This is a separate interface used for all
bi\-directional communication with minions. By default this system binds to
port \fB4506\fP and can be configured via the \fBret_port\fP option in the master.
.SS PUB/SUB
.sp
The commands sent out via the salt client are broadcast out to the minions via
ZeroMQ PUB/SUB. This is done by allowing the minions to maintain a connection
back to the Salt Master and then all connections are informed to download the
command data at once. The command data is kept extremely small (usually less
than 1K) so it is not a burden on the network.
.SS Return
.sp
The PUB/SUB system is a one way communication, so once a publish is sent out
the PUB interface on the master has no further communication with the minion.
The minion, after running the command, then sends the command\(aqs return data
back to the master via the \fBret_port\fP\&.
.SS Translating Documentation
.sp
If you wish to help translate the Salt documentation to your language, please
head over to the \fI\%Transifex\fP website and \fI\%signup\fP for an account.
.sp
Once registered, head over to the \fI\%Salt Translation Project\fP, and either
click on \fBRequest Language\fP if you can\(aqt find yours, or, select the language
for which you wish to contribute and click \fBJoin Team\fP\&.
.sp
\fI\%Transifex\fP provides some useful reading resources on their \fI\%support
domain\fP, namely, some useful articles \fI\%directed to translators\fP\&.
.SS Building A Localized Version of the Documentation
.sp
While you\(aqre working on your translation on \fI\%Transifex\fP, you might want to
have a look at how it\(aqs rendering.
.SS Install The Transifex Client
.sp
To interact with the \fI\%Transifex\fP web service you will need to install the
\fI\%transifex\-client\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install transifex\-client
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configure The Transifex Client
.sp
Once installed, you will need to set it up on your computer. We created a
script to help you with that:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.scripts/setup\-transifex\-config
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Download Remote Translations
.sp
There\(aqs a little script which simplifies the download process of the
translations(which isn\(aqt that complicated in the first place).
So, let\(aqs assume you\(aqre translating \fBpt_PT\fP, Portuguese(Portugal). To
download the translations, execute from the \fBdoc/\fP directory of your Salt
checkout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make download\-translations SPHINXLANG=pt_PT
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To download \fBpt_PT\fP, Portuguese(Portugal) and \fBnl\fP, Dutch, you can use the
helper script directly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.scripts/download\-translation\-catalog pt_PT nl
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Build Localized Documentation
.sp
After the download process finishes, which might take a while, the next step is
to build a localized version of the documentation.
Following the \fBpt_PT\fP example above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make html SPHINXLANG=pt_PT
.ft P
.fi
.UNINDENT
.UNINDENT
.SS View Localized Documentation
.sp
Open your browser, point it to the local documentation path and check the
localized output you\(aqve just build.
.SS Running The Tests
.sp
There are requirements, in addition to Salt\(aqs requirements, which
need to be installed in order to run the test suite. Install one of
the lines below, depending on the relevant Python version:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install \-r dev_requirements_python26.txt
pip install \-r dev_requirements_python27.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In Salt 0.17, testing libraries were migrated into their own repo. To install them:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install git+https://github.com/saltstack/salt\-testing.git#egg=SaltTesting
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Failure to install SaltTesting will result in import errors similar to the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ImportError: No module named salttesting
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Once all require requirements are set, use \fBtests/runtests.py\fP to
run all of the tests included in Salt\(aqs test suite. For more information,
see \fB\-\-help\fP\&.
.sp
An alternative way of invoking the test suite is available in \fBsetup.py\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./setup.py test
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instead of running the entire test suite, there are several ways to run only
specific groups of tests or individual tests:
.INDENT 0.0
.IP \(bu 2
Run unit tests only: \fB\&./tests/runtests.py \-\-unit\-tests\fP
.IP \(bu 2
Run unit and integration tests for states: \fB\&./tests/runtests.py \-\-state\fP
.IP \(bu 2
Run integration tests for an individual module: \fB\&./tests/runtests.py \-n integration.modules.virt\fP
.IP \(bu 2
Run unit tests for an individual module: \fB\&./tests/runtests.py \-n unit.modules.virt_test\fP
.IP \(bu 2
Run an individual test by using the class and test name (this example is for the \fBtest_default_kvm_profile\fP test in the
.UNINDENT
.sp
\fBintegration.module.virt\fP): \fB\&./tests/runtests.py \-n ingtegration.module.virt.VirtTest.test_default_kvm_profile\fP
.SS Running Unit Tests Without Integration Test Daemons
.sp
Since the unit tests do not require a master or minion to execute, it is often useful to be able to
run unit tests individually, or as a whole group, without having to start up the integration testing
daemons. Starting up the master, minion, and syndic daemons takes a lot of time before the tests can
even start running and is unnecessary to run unit tests. To run unit tests without invoking the
integration test daemons, simple remove the \fB/tests\fP portion of the \fBruntests.py\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./runtests.py \-\-unit
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All of the other options to run individual tests, entire classes of tests, or entire test modules still
apply.
.SS Running Destructive Integration Tests
.sp
Salt is used to change the settings and behavior of systems. In order to
effectively test Salt\(aqs functionality, some integration tests are written to
make actual changes to the underlying system. These tests are referred to as
"destructive tests". Some examples of destructive tests are changes may be
testing the addition of a user or installing packages. By default,
destructive tests are disabled and will be skipped.
.sp
Generally, destructive tests should clean up after themselves by attempting to
restore the system to its original state. For instance, if a new user is created
during a test, the user should be deleted after the related test(s) have
completed. However, no guarantees are made that test clean\-up will complete
successfully. Therefore, running destructive tests should be done with caution.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Running destructive tests will change the underlying system. Use caution when running destructive tests.
.UNINDENT
.UNINDENT
.sp
To run tests marked as destructive, set the \fB\-\-run\-destructive\fP flag:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./tests/runtests.py \-\-run\-destructive
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Running Cloud Provider Tests
.sp
Salt\(aqs testing suite also includes integration tests to assess the successful
creation and deletion of cloud instances using \fISalt\-Cloud\fP for
providers supported by Salt\-Cloud.
.sp
The cloud provider tests are off by default and run on sample configuration files
provided in \fBtests/integration/files/conf/cloud.providers.d/\fP\&. In order to run
the cloud provider tests, valid credentials, which differ per provider, must be
supplied. Each credential item that must be supplied is indicated by an empty
string value and should be edited by the user before running the tests. For
example, DigitalOcean requires a client key and an api key to operate. Therefore,
the default cloud provider configuration file for DigitalOcean looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
digitalocean\-config:
provider: digital_ocean
client_key: \(aq\(aq
api_key: \(aq\(aq
location: New York 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As indicated by the empty string values, the \fBclient_key\fP and the \fBapi_key\fP
must be provided:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
digitalocean\-config:
provider: digital_ocean
client_key: wFGEwgregeqw3435gDger
api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
location: New York 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
When providing credential information in cloud provider configuration files,
do not include the single quotes.
.UNINDENT
.UNINDENT
.sp
Once all of the valid credentials for the cloud provider have been supplied, the
cloud provider tests can be run by setting the \fB\-\-cloud\-provider\-tests\fP flag:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./tests/runtests.py \-\-cloud\-provider\-tests
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Running The Tests In A Docker Container
.sp
The test suite can be executed under a \fI\%docker\fP container using the
\fB\-\-docked\fP option flag. The \fI\%docker\fP container must be properly configured
on the system invoking the tests and the container must have access to the
internet.
.sp
Here\(aqs a simple usage example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tests/runtests.py \-\-docked=ubuntu\-12.04 \-v
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The full \fI\%docker\fP container repository can also be provided:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tests/runtests.py \-\-docked=salttest/ubuntu\-12.04 \-v
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The SaltStack team is creating some containers which will have the necessary
dependencies pre\-installed. Running the test suite on a container allows
destructive tests to run without making changes to the main system. It also
enables the test suite to run under a different distribution than the one
the main system is currently using.
.sp
The current list of test suite images is on Salt\(aqs \fI\%docker repository\fP\&.
.sp
Custom \fI\%docker\fP containers can be provided by submitting a pull request
against Salt\(aqs \fI\%docker Salt test containers\fP repository.
.SS Automated Test Runs
.sp
SaltStack maintains a Jenkins server to allow for the execution of tests
across supported platforms. The tests executed from Salt\(aqs Jenkins server
create fresh virtual machines for each test run, then execute destructive
tests on the new, clean virtual machine.
.sp
When a pull request is submitted to Salt\(aqs repository on GitHub, Jenkins
runs Salt\(aqs test suite on a couple of virtual machines to gauge the pull
request\(aqs viability to merge into Salt\(aqs develop branch. If these initial
tests pass, the pull request can then merged into Salt\(aqs develop branch
by one of Salt\(aqs core developers, pending their discretion. If the initial
tests fail, core developers may request changes to the pull request. If the
failure is unrelated to the changes in question, core developers may merge
the pull request despite the initial failure.
.sp
Once the pull request is merged into Salt\(aqs develop branch, a new set of
Jenkins virtual machines will begin executing the test suite. The develop
branch tests have many more virtual machines to provide more comprehensive
results.
.sp
There are a few other groups of virtual machines that Jenkins tests against,
including past and current release branches. For a full list of currently
running test environments, go to \fI\%http://jenkins.saltstack.com\fP\&.
.SS Using Salt\-Cloud on Jenkins
.sp
For testing Salt on Jenkins, SaltStack uses \fISalt\-Cloud\fP to
spin up virtual machines. The script using Salt\-Cloud to accomplish this is
open source and can be found here: \fI\%https://github.com/saltstack/salt/blob/develop/tests/jenkins.py\fP
.SS Writing Tests
.sp
Salt uses a test platform to verify functionality of components in a simple
way. Two testing systems exist to enable testing salt functions in somewhat
real environments. The two subsystems available are integration tests and
unit tests.
.sp
Salt uses the python standard library unittest2 system for testing.
.SS Naming Conventions
.sp
Any function in either integration test files or unit test files that is
doing the actual testing, such as functions containing assertions, must
start with \fBtest_\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def test_user_present(self):
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When functions in test files are not prepended with \fBtest_\fP,
the function acts as a normal, helper function and is not run as a test
by the test suite.
.SS Integration Tests
.sp
The integration tests start up a number of salt daemons to test functionality
in a live environment. These daemons include 2 salt masters, 1 syndic, and 2
minions. This allows the syndic interface to be tested and master/minion
communication to be verified. All of the integration tests are executed as
live salt commands sent through the started daemons.
.sp
Integration tests are particularly good at testing modules, states and shell
commands.
.INDENT 0.0
.IP \(bu 2
\fBWriting integration tests\fP
.UNINDENT
.SS Unit Tests
.sp
Direct unit tests are also available. These tests are good for testing internal
functions.
.INDENT 0.0
.IP \(bu 2
\fBWriting unit tests\fP
.UNINDENT
.SS Integration Tests
.sp
The Salt integration tests come with a number of classes and methods which
allow for components to be easily tested. These classes are generally inherited
from and provide specific methods for hooking into the running integration test
environment created by the integration tests.
.sp
It is noteworthy that since integration tests validate against a running
environment that they are generally the preferred means to write tests.
.sp
The integration system is all located under \fBtests/integration\fP in the Salt
source tree. Each directory within \fBtests/integration\fP corresponds to a
directory in Salt\(aqs tree structure. For example, the integration tests for the
\fBtest.py\fP Salt module that is located in \fBsalt/modules\fP should also be
named \fBtest.py\fP and reside in \fBtests/integration/modules\fP\&.
.SS Adding New Directories
.sp
If the corresponding Salt directory does not exist within
\fBtests/integration\fP, the new directory must be created along with the
appropriate test file to maintain Salt\(aqs testing directory structure.
.sp
In order for Salt\(aqs test suite to recognize tests within the newly
created directory, options to run the new integration tests must be added to
\fBtests/runtests.py\fP\&. Examples of the necessary options that must be added
can be found here: \fI\%https://github.com/saltstack/salt/blob/develop/tests/runtests.py\fP\&. The functions that need to be
edited are \fBsetup_additional_options\fP, \fBvalidate_options\fP, and
\fBrun_integration_tests\fP\&.
.SS Integration Classes
.sp
The integration classes are located in \fBtests/integration/__init__.py\fP and
can be extended therein. There are three classes available to extend:
.SS ModuleCase
.sp
Used to define executions run via the master to minions and to call
single modules and states.
.sp
The available methods are as follows:
.INDENT 0.0
.TP
.B run_function:
Run a single salt function and condition the return down to match the
behavior of the raw function call. This will run the command and only
return the results from a single minion to verify.
.TP
.B state_result:
Return the result data from a single state return
.TP
.B run_state:
Run the state.single command and return the state return structure
.UNINDENT
.SS SyndicCase
.sp
Used to execute remote commands via a syndic, only used to verify the
capabilities of the Syndic.
.sp
The available methods are as follows:
.INDENT 0.0
.TP
.B run_function:
Run a single salt function and condition the return down to match the
behavior of the raw function call. This will run the command and only
return the results from a single minion to verify.
.UNINDENT
.SS ShellCase
.sp
Shell out to the scripts which ship with Salt.
.sp
The available methods are as follows:
.INDENT 0.0
.TP
.B run_script:
Execute a salt script with the given argument string
.TP
.B run_salt:
Execute the salt command, pass in the argument string as it would be
passed on the command line.
.TP
.B run_run:
Execute the salt\-run command, pass in the argument string as it would be
passed on the command line.
.TP
.B run_run_plus:
Execute Salt run and the salt run function and return the data from
each in a dict
.TP
.B run_key:
Execute the salt\-key command, pass in the argument string as it would be
passed on the command line.
.TP
.B run_cp:
Execute salt\-cp, pass in the argument string as it would be
passed on the command line.
.TP
.B run_call:
Execute salt\-call, pass in the argument string as it would be
passed on the command line.
.UNINDENT
.SS Examples
.SS Module Example via ModuleCase Class
.sp
Import the integration module, this module is already added to the python path
by the test execution. Inherit from the \fBintegration.ModuleCase\fP class.
.sp
Now the workhorse method \fBrun_function\fP can be used to test a module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import os
import integration
class TestModuleTest(integration.ModuleCase):
\(aq\(aq\(aq
Validate the test module
\(aq\(aq\(aq
def test_ping(self):
\(aq\(aq\(aq
test.ping
\(aq\(aq\(aq
self.assertTrue(self.run_function(\(aqtest.ping\(aq))
def test_echo(self):
\(aq\(aq\(aq
test.echo
\(aq\(aq\(aq
self.assertEqual(self.run_function(\(aqtest.echo\(aq, [\(aqtext\(aq]), \(aqtext\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Shell Example via ShellCase
.sp
Validating the shell commands can be done via shell tests:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import sys
import shutil
import tempfile
import integration
class KeyTest(integration.ShellCase):
\(aq\(aq\(aq
Test salt\-key script
\(aq\(aq\(aq
_call_binary_ = \(aqsalt\-key\(aq
def test_list(self):
\(aq\(aq\(aq
test salt\-key \-L
\(aq\(aq\(aq
data = self.run_key(\(aq\-L\(aq)
expect = [
\(aqUnaccepted Keys:\(aq,
\(aqAccepted Keys:\(aq,
\(aqminion\(aq,
\(aqsub_minion\(aq,
\(aqRejected:\(aq, \(aq\(aq]
self.assertEqual(data, expect)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example verifies that the \fBsalt\-key\fP command executes and returns as
expected by making use of the \fBrun_key\fP method.
.SS Integration Test Files
.sp
Since using Salt largely involves configuring states, editing files, and changing
system data, the integration test suite contains a directory named \fBfiles\fP to
aid in testing functions that require files. Various Salt integration tests use
these example files to test against instead of altering system files and data.
.sp
Each directory within \fBtests/integration/files\fP contain files that accomplish
different tasks, based on the needs of the integration tests using those files.
For example, \fBtests/integration/files/ssh\fP is used to bootstrap the test runner
for salt\-ssh testing, while \fBtests/integration/files/pillar\fP contains files
storing data needed to test various pillar functions.
.sp
The \fBtests/integration/files\fP directory also includes an integration state tree.
The integration state tree can be found at \fBtests/integration/files/file/base\fP\&.
.sp
The following example demonstrates how integration files can be used with ModuleCase
to test states:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import os
import shutil
import integration
HFILE = os.path.join(integration.TMP, \(aqhosts\(aq)
class HostTest(integration.ModuleCase):
\(aq\(aq\(aq
Validate the host state
\(aq\(aq\(aq
def setUp(self):
shutil.copyfile(os.path.join(integration.FILES, \(aqhosts\(aq), HFILE)
super(HostTest, self).setUp()
def tearDown(self):
if os.path.exists(HFILE):
os.remove(HFILE)
super(HostTest, self).tearDown()
def test_present(self):
\(aq\(aq\(aq
host.present
\(aq\(aq\(aq
name = \(aqspam.bacon\(aq
ip = \(aq10.10.10.10\(aq
ret = self.run_state(\(aqhost.present\(aq, name=name, ip=ip)
result = self.state_result(ret)
self.assertTrue(result)
with open(HFILE) as fp_:
output = fp_.read()
self.assertIn(\(aq{0}\et\et{1}\(aq.format(ip, name), output)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To access the integration files, a variable named \fBintegration.FILES\fP
points to the \fBtests/integration/files\fP directory. This is where the referenced
\fBhost.present\fP sls file resides.
.sp
In addition to the static files in the integration state tree, the location
\fBintegration.TMP\fP can also be used to store temporary files that the test system
will clean up when the execution finishes.
.SS Destructive vs Non\-Destructive Tests
.sp
Since Salt is used to change the settings and behavior of systems, one testing
approach is to run tests that make actual changes to the underlying system. This
is where the concept of destructive integration tests comes into play. Tests can
be written to alter the system they are running on. This capability is what fills
in the gap needed to properly test aspects of system management like package
installation.
.sp
Any test that changes the underlying system in any way, such as creating or
deleting users, installing packages, or changing permissions should include the
\fB@destructive\fP decorator to signal system changes and should be written with
care. System changes executed within a destructive test should also be restored
once the related tests have completed. For example, if a new user is created to
test a module, the same user should be removed after the test is completed to
maintain system integrity.
.sp
To write a destructive test, import and use the destructiveTest decorator for
the test method:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import integration
from salttesting.helpers import destructiveTest
class DestructiveExampleModuleTest(integration.ModuleCase):
\(aq\(aq\(aq
Demonstrate a destructive test
\(aq\(aq\(aq
@destructiveTest
@skipIf(os.geteuid() != 0, \(aqyou must be root to run this test\(aq)
def test_user_not_present(self):
\(aq\(aq\(aq
This is a DESTRUCTIVE TEST it creates a new user on the minion.
And then destroys that user.
\(aq\(aq\(aq
ret = self.run_state(\(aquser.present\(aq, name=\(aqsalt_test\(aq)
self.assertSaltTrueReturn(ret)
ret = self.run_state(\(aquser.absent\(aq, name=\(aqsalt_test\(aq)
self.assertSaltTrueReturn(ret)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cloud Provider Tests
.sp
Cloud provider integration tests are used to assess \fISalt\-Cloud\fP\(aqs
ability to create and destroy cloud instances for various supported cloud providers.
Cloud provider tests inherit from the ShellCase Integration Class.
.sp
Any new cloud provider test files should be added to the \fBtests/integration/cloud/providers/\fP
directory. Each cloud provider test file also requires a sample cloud profile and cloud
provider configuration file in the integration test file directory located at
\fBtests/integration/files/conf/cloud.*.d/\fP\&.
.sp
The following is an example of the default profile configuration file for Digital
Ocean, located at: \fBtests/integration/files/conf/cloud.profiles.d/digital_ocean.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
digitalocean\-test:
provider: digitalocean\-config
image: Ubuntu 14.04 x64
size: 512MB
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Each cloud provider requires different configuration credentials. Therefore, sensitive
information such as API keys or passwords should be omitted from the cloud provider
configuration file and replaced with an empty string. The necessary credentials can
be provided by the user by editing the provider configuration file before running the
tests.
.sp
The following is an example of the default provider configuration file for Digital
Ocean, located at: \fBtests/integration/files/conf/cloud.providers.d/digital_ocean.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
digitalocean\-config:
provider: digital_ocean
client_key: \(aq\(aq
api_key: \(aq\(aq
location: New York 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In addition to providing the necessary cloud profile and provider files in the integration
test suite file structure, appropriate checks for if the configuration files exist and
contain valid information are also required in the test class\(aqs \fBsetUp\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class LinodeTest(integration.ShellCase):
\(aq\(aq\(aq
Integration tests for the Linode cloud provider in Salt\-Cloud
\(aq\(aq\(aq
def setUp(self):
\(aq\(aq\(aq
Sets up the test requirements
\(aq\(aq\(aq
super(LinodeTest, self).setUp()
# check if appropriate cloud provider and profile files are present
profile_str = \(aqlinode\-config:\(aq
provider = \(aqlinode\(aq
providers = self.run_cloud(\(aq\-\-list\-providers\(aq)
if profile_str not in providers:
self.skipTest(
\(aqConfiguration file for {0} was not found. Check {0}.conf files \(aq
\(aqin tests/integration/files/conf/cloud.*.d/ to run these tests.\(aq
.format(provider)
)
# check if apikey and password are present
path = os.path.join(integration.FILES,
\(aqconf\(aq,
\(aqcloud.providers.d\(aq,
provider + \(aq.conf\(aq)
config = cloud_providers_config(path)
api = config[\(aqlinode\-config\(aq][\(aqlinode\(aq][\(aqapikey\(aq]
password = config[\(aqlinode\-config\(aq][\(aqlinode\(aq][\(aqpassword\(aq]
if api == \(aq\(aq or password == \(aq\(aq:
self.skipTest(
\(aqAn api key and password must be provided to run these tests. Check \(aq
\(aqtests/integration/files/conf/cloud.providers.d/{0}.conf\(aq.format(
provider
)
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Repeatedly creating and destroying instances on cloud providers can be costly.
Therefore, cloud provider tests are off by default and do not run automatically. To
run the cloud provider tests, the \fB\-\-cloud\-provider\-tests\fP flag must be provided:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./tests/runtests.py \-\-cloud\-provider\-tests
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since cloud provider tests do not run automatically, all provider tests must be
preceded with the \fB@expensiveTest\fP decorator. The expensive test decorator is
necessary because it signals to the test suite that the
\fB\-\-cloud\-provider\-tests\fP flag is required to run the cloud provider tests.
.sp
To write a cloud provider test, import and use the expensiveTest decorator for
the test function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from salttesting.helpers import expensiveTest
@expensiveTest
def test_instance(self):
\(aq\(aq\(aq
Test creating an instance on Linode
\(aq\(aq\(aq
name = \(aqlinode\-testing\(aq
# create the instance
instance = self.run_cloud(\(aq\-p linode\-test {0}\(aq.format(name))
str = \(aq {0}\(aq.format(name)
# check if instance with salt installed returned as expected
try:
self.assertIn(str, instance)
except AssertionError:
self.run_cloud(\(aq\-d {0} \-\-assume\-yes\(aq.format(name))
raise
# delete the instance
delete = self.run_cloud(\(aq\-d {0} \-\-assume\-yes\(aq.format(name))
str = \(aq True\(aq
try:
self.assertIn(str, delete)
except AssertionError:
raise
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Writing Unit Tests
.SS Introduction
.sp
Like many software projects, Salt has two broad\-based testing approaches \-\-
integration testing and unit testing. While integration testing focuses on the
interaction between components in a sandboxed environment, unit testing focuses
on the singular implementation of individual functions.
.SS Preparing to Write a Unit Test
.sp
This guide assumes you\(aqve followed the \fI\%directions for setting up salt testing\fP\&.
.sp
Unit tests should be written to the following specifications:
.INDENT 0.0
.IP \(bu 2
All the tests for a specific module at salt/.../<module>.py need to be
contained in a file called tests/unit/.../<module>_test.py, e.g. the tests
for salt/modules/fib.py need to be contained in a file called
tests/unit/modules/fib_test.py.
.IP \(bu 2
The tests within tests/unit/modules/fib_test.py file must be member functions
of a class which subclasses salttesting.Testcase
.IP \(bu 2
Each external resource used in the code to be tested, such as function calls,
external data either globally available or passed in through the function
arguments, file data, etc. needs to be mocked.
.IP \(bu 2
Each raise and return statement of the code to be tested needs to be
separately and independently tested.
.IP \(bu 2
Test functions should contain only one test and contain all necessary mock
data and mock code for that test.
.IP \(bu 2
Test functions should be named test_<fcn>_<test\-name> where <fcn> is the name
of the function being tested and <test\-name> describes which raise or return
within the function is being tested and whether that raise or return
statement is considered a success or a failure condition.
.UNINDENT
.sp
Most commonly, the following imports are necessary to create a unit test:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Import Salt Testing libs
from salttesting import skipIf, TestCase
from salttesting.helpers import ensure_in_syspath
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you need mock support to your tests, please also import:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from salttesting.mock import NO_MOCK, NO_MOCK_REASON, MagicMock, patch, call
.ft P
.fi
.UNINDENT
.UNINDENT
.SS A Simple Example
.sp
Let\(aqs assume that we\(aqre testing a very basic function in an imaginary Salt
execution module. Given a module called \fBfib.py\fP that has a function called
\(aqcalculate(num_of_results)\(aq, which given a \(aqnum_of_results\(aq, produces a list of
sequential Fibonacci numbers of that length.
.sp
A unit test to test this function might be commonly placed in a file called
\fBtests/unit/modules/fib_test.py\fP\&. The convention is to place unit tests for
Salt execution modules in \fBtest/unit/modules/\fP and to name the tests module
suffixed with \fB_test.py\fP\&.
.sp
Tests are grouped around test cases, which are logically grouped sets of tests
against a piece of functionality in the tested software. Test cases are created
as Python classes in the unit test module. To return to our example, here\(aqs how
we might write the skeleton for testing \fBfib.py\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Import Salt Testing libs
from salttesting import TestCase
# Import Salt execution module to test
from salt.modules import fib
# Create test case class and inherit from Salt\(aqs customized TestCase
class FibTestCase(TestCase):
\(aq\(aq\(aq
This class contains a set of functions that test salt.modules.fib.
\(aq\(aq\(aq
def test_fib(self):
\(aq\(aq\(aq
To create a unit test, we should prefix the name with \(gatest_\(aq so
that it\(aqs recognized by the test runner.
\(aq\(aq\(aq
fib_five = (0, 1, 1, 2, 3)
self.assertEqual(fib.calculate(5), fib_five)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
At this point, the test can now be run, either individually or as a part of a
full run of the test runner. To ease development, a single test can be
executed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tests/runtests.py \-n unit.modules.fib_test
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will produce output indicating the success or failure of the tests in
given test case. For more detailed results, one can also include a flag to
increase verbosity:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
tests/runtests.py \-n unit.modules.fib_test \-v
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To review the results of a particular run, take a note of the log location
given in the output for each test:
.INDENT 0.0
.INDENT 3.5
\fBLogging tests on /var/folders/nl/d809xbq577l3qrbj3ymtpbq80000gn/T/salt\-runtests.log\fP
.UNINDENT
.UNINDENT
.SS Evaluating Truth
.sp
A longer discussion on the types of assertions one can make can be found by
reading \fI\%Python\(aqs documentation on unit testing\fP\&.
.SS Tests Using Mock Objects
.sp
In many cases, the very purpose of a Salt module is to interact with some
external system, whether it be to control a database, manipulate files on a
filesystem or many other examples. In these varied cases, it\(aqs necessary to
design a unit test which can test the function whilst replacing functions which
might actually call out to external systems. One might think of this as
"blocking the exits" for code under tests and redirecting the calls to external
systems with our own code which produces known results during the duration of
the test.
.sp
To achieve this behavior, Salt makes heavy use of the \fI\%MagicMock package\fP\&.
.sp
To understand how one might integrate Mock into writing a unit test for Salt,
let\(aqs imagine a scenario in which we\(aqre testing an execution module that\(aqs
designed to operate on a database. Furthermore, let\(aqs imagine two separate
methods, here presented in pseduo\-code in an imaginary execution module called
\(aqdb.py.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def create_user(username):
qry = \(aqCREATE USER {0}\(aq.format(username)
execute_query(qry)
def execute_query(qry):
# Connect to a database and actually do the query...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here, let\(aqs imagine that we want to create a unit test for the \fIcreate_user\fP
function. In doing so, we want to avoid any calls out to an external system and
so while we are running our unit tests, we want to replace the actual
interaction with a database with a function that can capture the parameters
sent to it and return pre\-defined values. Therefore, our task is clear \-\- to
write a unit test which tests the functionality of \fIcreate_user\fP while also
replacing \(aqexecute_query\(aq with a mocked function.
.sp
To begin, we set up the skeleton of our class much like we did before, but with
additional imports for MagicMock:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Import Salt Testing libs
from salttesting import TestCase
# Import Salt execution module to test
from salt.modules import db
# NEW! \-\- Import Mock libraries
from salttesting.mock import NO_MOCK, NO_MOCK_REASON, MagicMock, patch, call
# Create test case class and inherit from Salt\(aqs customized TestCase
# Skip this test case if we don\(aqt have access to mock!
@skipIf(NO_MOCK, NO_MOCK_REASON)
class DbTestCase(TestCase):
def test_create_user(self):
# First, we replace \(aqexecute_query\(aq with our own mock function
db.execute_query = MagicMock()
# Now that the exits are blocked, we can run the function under test.
db.create_user(\(aqtestuser\(aq)
# We could now query our mock object to see which calls were made
# to it.
## print db.execute_query.mock_calls
\(aq\(aq\(aq
We want to test to ensure that the correct query was formed. This
is a contrived example, just designed to illustrate the concepts at
hand.
We\(aqre going to first construct a call() object that represents the
way we expect our mocked execute_query() function to have been
called. Then, we\(aqll examine the list of calls that were actually
made to to execute_function().
By comparing our expected call to execute_query() with
create_user()\(aqs call to execute_query(), we can determine the
success or failure of our unit test.
\(aq\(aq\(aq
expected_call = call(\(aqCREATE USER testuser\(aq)
# Do the comparison! Will assert False if execute_query() was not
# called with the given call
db.execute_query.assert_has_calls(expected_call)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Modifying \fB__salt__\fP In Place
.sp
At times, it becomes necessary to make modifications to a module\(aqs view of
functions in its own \fB__salt__\fP dictionary. Luckily, this process is quite
easy.
.sp
Below is an example that uses MagicMock\(aqs \fBpatch\fP functionality to insert a
function into \fB__salt__\fP that\(aqs actually a MagicMock instance.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def show_patch(self):
with patch.dict(my_module.__salt__,
{\(aqfunction.to_replace\(aq: MagicMock()}:
# From this scope, carry on with testing, with a modified __salt__!
.ft P
.fi
.UNINDENT
.UNINDENT
.SS A More Complete Example
.sp
Consider the following function from salt/modules/linux_sysctl.py.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def get(name):
\(aq\(aq\(aq
Return a single sysctl parameter for this minion
CLI Example:
.. code\-block:: bash
salt \(aq*\(aq sysctl.get net.ipv4.ip_forward
\(aq\(aq\(aq
cmd = \(aqsysctl \-n {0}\(aq.format(name)
out = __salt__[\(aqcmd.run\(aq](cmd)
return out
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function is very simple, comprising only four source lines of code and
having only one return statement, so we know only one test is needed. There
are also two inputs to the function, the \fBname\fP function argument and the call
to \fB__salt__[\(aqcmd.run\(aq]()\fP, both of which need to be appropriately mocked.
Mocking a function parameter is straightforward, whereas mocking a function
call will require, in this case, the use of MagicMock. For added isolation, we
will also redefine the \fB__salt__\fP dictionary such that it only contains
\fB\(aqcmd.run\(aq\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Import Salt Libs
from salt.modules import linux_sysctl
# Import Salt Testing Libs
from salttesting import skipIf, TestCase
from salttesting.helpers import ensure_in_syspath
from salttesting.mock import (
MagicMock,
patch,
NO_MOCK,
NO_MOCK_REASON
)
ensure_in_syspath(\(aq../../\(aq)
# Globals
linux_sysctl.__salt__ = {}
@skipIf(NO_MOCK, NO_MOCK_REASON)
class LinuxSysctlTestCase(TestCase):
\(aq\(aq\(aq
TestCase for salt.modules.linux_sysctl module
\(aq\(aq\(aq
def test_get(self):
\(aq\(aq\(aq
Tests the return of get function
\(aq\(aq\(aq
mock_cmd = MagicMock(return_value=1)
with patch.dict(linux_sysctl.__salt__, {\(aqcmd.run\(aq: mock_cmd}):
self.assertEqual(linux_sysctl.get(\(aqnet.ipv4.ip_forward\(aq), 1)
if __name__ == \(aq__main__\(aq:
from integration import run_tests
run_tests(LinuxSysctlTestCase, needs_daemon=False)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since \fBget()\fP has only one raise or return statement and that statement is a
success condition, the test function is simply named \fBtest_get()\fP\&. As
described, the single function call parameter, \fBname\fP is mocked with
\fBnet.ipv4.ip_forward\fP and \fB__salt__[\(aqcmd.run\(aq]\fP is replaced by a MagicMock
function object. We are only interested in the return value of
\fB__salt__[\(aqcmd.run\(aq]\fP, which MagicMock allows to be specified via
\fBreturn_value=1\fP\&. Finally, the test itself tests for equality between the
return value of \fBget()\fP and the expected return of \fB1\fP\&. This assertion is
expected to succeed because \fBget()\fP will determine its return value from
\fB__salt__[\(aqcmd.run\(aq]\fP, which we have mocked to return \fB1\fP\&.
.SS A Complex Example
.sp
Now consider the \fBassign()\fP function from the same
salt/modules/linux_sysctl.py source file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def assign(name, value):
\(aq\(aq\(aq
Assign a single sysctl parameter for this minion
CLI Example:
.. code\-block:: bash
salt \(aq*\(aq sysctl.assign net.ipv4.ip_forward 1
\(aq\(aq\(aq
value = str(value)
sysctl_file = \(aq/proc/sys/{0}\(aq.format(name.replace(\(aq.\(aq, \(aq/\(aq))
if not os.path.exists(sysctl_file):
raise CommandExecutionError(\(aqsysctl {0} does not exist\(aq.format(name))
ret = {}
cmd = \(aqsysctl \-w {0}="{1}"\(aq.format(name, value)
data = __salt__[\(aqcmd.run_all\(aq](cmd)
out = data[\(aqstdout\(aq]
err = data[\(aqstderr\(aq]
# Example:
# # sysctl \-w net.ipv4.tcp_rmem="4096 87380 16777216"
# net.ipv4.tcp_rmem = 4096 87380 16777216
regex = re.compile(r\(aq^{0}\es+=\es+{1}$\(aq.format(re.escape(name),
re.escape(value)))
if not regex.match(out) or \(aqInvalid argument\(aq in str(err):
if data[\(aqretcode\(aq] != 0 and err:
error = err
else:
error = out
raise CommandExecutionError(\(aqsysctl \-w failed: {0}\(aq.format(error))
new_name, new_value = out.split(\(aq = \(aq, 1)
ret[new_name] = new_value
return ret
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function contains two raise statements and one return statement, so we
know that we will need (at least) three tests. It has two function arguments
and many references to non\-builtin functions. In the tests below you will see
that MagicMock\(aqs \fBpatch()\fP method may be used as a context manager or as a
decorator.
.sp
There are three test functions, one for each raise and return statement in the
source function. Each function is self\-contained and contains all and only the
mocks and data needed to test the raise or return statement it is concerned
with.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Import Salt Libs
from salt.modules import linux_sysctl
from salt.exceptions import CommandExecutionError
# Import Salt Testing Libs
from salttesting import skipIf, TestCase
from salttesting.helpers import ensure_in_syspath
from salttesting.mock import (
MagicMock,
patch,
NO_MOCK,
NO_MOCK_REASON
)
ensure_in_syspath(\(aq../../\(aq)
# Globals
linux_sysctl.__salt__ = {}
@skipIf(NO_MOCK, NO_MOCK_REASON)
class LinuxSysctlTestCase(TestCase):
\(aq\(aq\(aq
TestCase for salt.modules.linux_sysctl module
\(aq\(aq\(aq
@patch(\(aqos.path.exists\(aq, MagicMock(return_value=False))
def test_assign_proc_sys_failed(self):
\(aq\(aq\(aq
Tests if /proc/sys/<kernel\-subsystem> exists or not
\(aq\(aq\(aq
cmd = {\(aqpid\(aq: 1337, \(aqretcode\(aq: 0, \(aqstderr\(aq: \(aq\(aq,
\(aqstdout\(aq: \(aqnet.ipv4.ip_forward = 1\(aq}
mock_cmd = MagicMock(return_value=cmd)
with patch.dict(linux_sysctl.__salt__, {\(aqcmd.run_all\(aq: mock_cmd}):
self.assertRaises(CommandExecutionError,
linux_sysctl.assign,
\(aqnet.ipv4.ip_forward\(aq, 1)
@patch(\(aqos.path.exists\(aq, MagicMock(return_value=True))
def test_assign_cmd_failed(self):
\(aq\(aq\(aq
Tests if the assignment was successful or not
\(aq\(aq\(aq
cmd = {\(aqpid\(aq: 1337, \(aqretcode\(aq: 0, \(aqstderr\(aq:
\(aqsysctl: setting key "net.ipv4.ip_forward": Invalid argument\(aq,
\(aqstdout\(aq: \(aqnet.ipv4.ip_forward = backward\(aq}
mock_cmd = MagicMock(return_value=cmd)
with patch.dict(linux_sysctl.__salt__, {\(aqcmd.run_all\(aq: mock_cmd}):
self.assertRaises(CommandExecutionError,
linux_sysctl.assign,
\(aqnet.ipv4.ip_forward\(aq, \(aqbackward\(aq)
@patch(\(aqos.path.exists\(aq, MagicMock(return_value=True))
def test_assign_success(self):
\(aq\(aq\(aq
Tests the return of successful assign function
\(aq\(aq\(aq
cmd = {\(aqpid\(aq: 1337, \(aqretcode\(aq: 0, \(aqstderr\(aq: \(aq\(aq,
\(aqstdout\(aq: \(aqnet.ipv4.ip_forward = 1\(aq}
ret = {\(aqnet.ipv4.ip_forward\(aq: \(aq1\(aq}
mock_cmd = MagicMock(return_value=cmd)
with patch.dict(linux_sysctl.__salt__, {\(aqcmd.run_all\(aq: mock_cmd}):
self.assertEqual(linux_sysctl.assign(
\(aqnet.ipv4.ip_forward\(aq, 1), ret)
if __name__ == \(aq__main__\(aq:
from integration import run_tests
run_tests(LinuxSysctlTestCase, needs_daemon=False)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS raet
.sp
# RAET
# Reliable Asynchronous Event Transport Protocol
.SS Protocol
.sp
Layering:
.sp
OSI Layers
.sp
7: Application: Format: Data (Stack to Application interface buffering etc)
6: Presentation: Format: Data (Encrypt\-Decrypt convert to machine independent format)
5: Session: Format: Data (Interhost communications. Authentication. Groups)
4: Transport: Format: Segments (Reliable delivery of Message, Transactions, Segmentation, Error checking)
3: Network: Format: Packets/Datagrams (Addressing Routing)
2: Link: Format: Frames ( Reliable per frame communications connection, Media access controller )
1: Physical: Bits (Transceiver communication connection not reliable)
.sp
Link is hidden from Raet
Network is IP host address and Udp Port
Transport is Raet transactions, service kind, tail error checking,
Could include header signing as part of transport reliable delivery serialization of header
Session is session id key exchange for signing. Grouping is Road (like 852 channel)
Presentation is Encrypt Decrypt body Serialize Deserialize Body
Application is body data dictionary
.sp
Header signing spans both the Transport and Session layers.
.SS Header
.sp
JSON Header (Tradeoff some processing speed for extensibility, ease of use, readability)
.sp
Body initially JSON but support for "packed" binary body
.SS Packet
.sp
Header ASCII Safe JSON
Header termination:
Empty line given by double pair of carriage return linefeed
/r/n/r/n
10 13 10 13
ADAD
1010 1101 1010 1101
.sp
In json carriage return and newline characters cannot appear in a json encoded
string unless they are escaped with backslash, so the 4 byte combination is illegal in valid
json that does not have multi\-byte unicode characters.
.sp
These means the header must be ascii safe so no multibyte utf\-8 strings
allowed in header.
.sp
Following Header Terminator is variable length signature block. This is binary
and the length is provided in the header.
.sp
Following the signature block is the packet body or data.
This may either be JSON or packed binary.
The format is given in the json header
.sp
Finally is an optional tail block for error checking or encryption details
.SS Header Fields
.sp
In UDP header
.sp
sh = source host
sp = source port
dh = destination host
dp = destination port
.sp
In RAET Header
.sp
hk = header kind
hl = header length
.sp
vn = version number
.sp
sd = Source Device ID
dd = Destination Device ID
cf = Corresponder Flag
mf = Multicast Flag
.sp
si = Session ID
ti = Transaction ID
.sp
sk = Service Kind
pk = Packet Kind
bf = Burst Flag (Send all Segments or Ordered packets without interleaved acks)
.sp
oi = Order Index
dt = DateTime Stamp
.sp
sn = Segment Number
sc = Segment Count
.sp
pf = Pending Segment Flag
af = All Flag (Resent all Segments not just one)
.sp
nk = Auth header kind
nl = Auth header length
.sp
bk = body kind
bl = body length
.sp
tk = tail kind
tl = tail length
.INDENT 0.0
.TP
.B fg = flags packed (Flags) Default \(aq00\(aq hex string
2 byte Hex string with bits (0, 0, af, pf, 0, bf, mf, cf)
Zeros are TBD flags
.UNINDENT
.SS Session Bootstrap
.sp
Minion sends packet with SID of Zero with public key of minions Public Private Key pair
Master acks packet with SID of Zero to let minion know it received the request
.sp
Some time later Master sends packet with SID of zero that accepts the Minion
.sp
Minion
.SS Session
.sp
Session is important for security. Want one session opened and then multiple
transactions within session.
.sp
Session ID
SID
sid
.sp
GUID hash to guarantee uniqueness since no guarantee of nonvolatile storage
or require file storage to keep last session ID used.
.SS Service Types or Modular Services
.sp
Four Service Types
.INDENT 0.0
.IP A. 3
One or more maybe (unacknowledged repeat) maybe means no guarantee
.IP B. 3
.INDENT 3.0
.TP
.B Exactly one at most (ack with retries) (duplicate detection idempotent)
at most means fixed number of retries has finite probability of failing
B1) finite retries
B2) infinite retries with exponential back\-off up to a maximum delay
.UNINDENT
.IP C. 3
.INDENT 3.0
.TP
.B Exactly one of sequence at most (sequence numbered)
Receiver requests retry of missing packet with same B1 or B2 retry type
.UNINDENT
.IP D. 3
.INDENT 3.0
.TP
.B End to End (Application layer Request Response)
This is two B sub transactions
.UNINDENT
.UNINDENT
.sp
Initially unicast messaging
Eventually support for Multicast
.sp
The use case for C) is to fragment large packets as once a UDP packet
exceeds the frame size its reliability goes way down
So its more reliable to fragment large packets.
.sp
Better approach might be to have more modularity.
Services Levels
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
.INDENT 3.0
.TP
.B Maybe one or more
.INDENT 7.0
.IP A. 3
.INDENT 3.0
.TP
.B Fire and forget
no transaction either side
.UNINDENT
.IP B. 3
.INDENT 3.0
.TP
.B Repeat, no ack, no dupdet
repeat counter send side,
no transaction on receive side
.UNINDENT
.IP C. 3
.INDENT 3.0
.TP
.B Repeat, no Ack, dupdet
repeat counter send side,
dup detection transaction receive side
.UNINDENT
.UNINDENT
.UNINDENT
.IP 2. 3
.INDENT 3.0
.TP
.B More or Less Once
.INDENT 7.0
.IP A. 3
.INDENT 3.0
.TP
.B retry finite, ack no dupdet
retry timer send side, finite number of retires
ack receive side no dupdet
.UNINDENT
.UNINDENT
.UNINDENT
.IP 3. 3
.INDENT 3.0
.TP
.B At most Once
.INDENT 7.0
.IP A. 3
.INDENT 3.0
.TP
.B retry finite, ack, dupdet
retry timer send side, finite number of retires
ack receive side dupdet
.UNINDENT
.UNINDENT
.UNINDENT
.IP 4. 3
.INDENT 3.0
.TP
.B Exactly once
.INDENT 7.0
.IP A. 3
.INDENT 3.0
.TP
.B ack retry
retry timer send side,
ack and duplicate detection receive side
Infinite retries with exponential backoff
.UNINDENT
.UNINDENT
.UNINDENT
.IP 5. 3
.INDENT 3.0
.TP
.B Sequential sequence number
.INDENT 7.0
.IP A. 3
reorder escrow
.IP B. 3
Segmented packets
.UNINDENT
.UNINDENT
.IP 6. 3
request response to application layer
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Service Features
.INDENT 0.0
.IP 1. 3
repeats
.IP 2. 3
ack retry transaction id
.IP 3. 3
sequence number duplicate detection out of order detection sequencing
.IP 4. 3
rep\-req
.UNINDENT
.sp
Always include transaction id since multiple transactions on same port
So get duplicate detection for free if keep transaction alive but if use
.sp
A) Maybe one or more
B1) At Least One
B2) Exactly One
C) One of sequence
D) End to End
.sp
A) Sender creates transaction id for number of repeats but receiver does not
keep transaction alive
.sp
B1) Sender creates transaction id keeps it for retries.
Receiver keeps it to send ack then kills so retry could be duplicate not detected
.sp
B2) Sender creates transaction id keeps for retries
Receiver keeps tid for acks on any retires so no duplicates.
.sp
C) Sender creates TID and Sequence Number.
Receiver checks for out of order sequence and can request retry.
.sp
D) Application layer sends response. So question is do we keep transaction open
or have response be new transaction. No because then we need a rep\-req ID so
might as well use the same transaction id. Just keep alive until get response.
.sp
Little advantage to B1 vs B2 not having duplicates.
.sp
So 4 service types
.INDENT 0.0
.IP A. 3
Maybe one or more (unacknowledged repeat)
.IP B. 3
Exactly One (At most one) (ack with retry) (duplicate detection idempotent)
.IP C. 3
One of Sequence (sequence numbered)
.IP D. 3
End to End
.UNINDENT
.sp
Also multicast or unicast
.sp
Modular Transaction Table
.INDENT 0.0
.TP
.B Sender Side:
Transaction ID plus transaction source sender or receiver generated transaction id
Repeat Counter
Retry Timer Retry Counter (finite retries)
Redo Timer (infinite redos with exponential backoff)
Sequence number without acks (look for resend requests)
Sequence with ack (wait for ack before sending next in sequence)
Segmentation
.TP
.B Receiver Side:
Nothing just accept packet
Acknowledge (can delete transaction after acknowledge)
No duplicate detection
Transaction timeout (keep transaction until timeout)
Duplicate detection save transaction id duplicate detection timeout
Request resend of missing packet in sequence
Sequence reordering with escrow timeout wait escrow before requesting resend
Unsegmentation (request resends of missing segment)
.UNINDENT
.SS SaltStack Git Policy
.sp
The SaltStack team follows a git policy to maintain stability and consistency
with the repository.
.sp
The git policy has been developed to encourage contributions and make contributing
to Salt as easy as possible. Code contributors to SaltStack projects DO NOT NEED
TO READ THIS DOCUMENT, because all contributions come into SaltStack via a single
gateway to make it as easy as possible for contributors to give us code.
.sp
The primary rule of git management in SaltStack is to make life easy on
contributors and developers to send in code. Simplicity is always a goal!
.SS New Code Entry
.sp
All new SaltStack code is posted to the \fIdevelop\fP branch, which is the single
point of entry. The only exception is when a bugfix to develop cannot be
cleanly merged into a release branch and the bugfix needs to be rewritten for
the release branch.
.SS Release Branching
.sp
SaltStack maintains two types of releases, \fIFeature Releases\fP and
\fIPoint Releases\fP\&. A feature release is managed by incrementing the first or
second release point number, so 0.10.5 \-> 0.11.0 signifies a feature release
and 0.11.0 \-> 0.11.1 signifies a point release, also a hypothetical
0.42.7 \-> 1.0.0 would also signify a feature release.
.SS Feature Release Branching
.sp
Each feature release is maintained in a dedicated git branch derived from the
last applicable release commit on develop. All file changes relevant to the
feature release will be completed in the develop branch prior to the creation
of the feature release branch. The feature release branch will be named after
the relevant numbers to the feature release, which constitute the first two
numbers. This means that the release branch for the 0.11.0 series is named
0.11.
.sp
A feature release branch is created with the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# git checkout \-b 0.11 # From the develop branch
# git push origin 0.11
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Point Releases
.sp
Each point release is derived from its parent release branch. Constructing point
releases is a critical aspect of Salt development and is managed by members of
the core development team. Point releases comprise bug and security fixes which
are cherry picked from develop onto the aforementioned release branch. At the
time when a core developer accepts a pull request a determination needs to be
made if the commits in the pull request need to be backported to the release
branch. Some simple criteria are used to make this determination:
.INDENT 0.0
.IP \(bu 2
Is this commit fixing a bug?
Backport
.IP \(bu 2
Does this commit change or add new features in any way?
Don\(aqt backport
.IP \(bu 2
Is this a PEP8 or code cleanup commit?
Don\(aqt backport
.IP \(bu 2
Does this commit fix a security issue?
Backport
.UNINDENT
.sp
Determining when a point release is going to be made is up to the project
leader (Thomas Hatch). Generally point releases are made every 1\-2 weeks or
if there is a security fix they can be made sooner.
.sp
The point release is only designated by tagging the commit on the release
branch with release number using the existing convention (version 0.11.1 is
tagged with v0.11.1). From the tag point a new source tarball is generated
and published to PyPI, and a release announcement is made.
.SS Salt Conventions
.SS Writing Salt Documentation
.sp
Salt\(aqs documentation is built using the \fI\%Sphinx\fP documentation system. It can
be build in a large variety of output formats including HTML, PDF, ePub, and
manpage.
.sp
All the documentation is contained in the main Salt repository. Speaking
broadly, most of the narrative documentation is contained within the
\fI\%https://github.com/saltstack/salt/blob/develop/doc\fP subdirectory and most of the reference and API documentation is
written inline with Salt\(aqs Python code and extracted using a Sphinx extension.
.SS Style
.sp
The Salt project recommends the \fI\%IEEE style guide\fP as a general reference for
writing guidelines. Those guidelines are not strictly enforced but rather serve
as an excellent resource for technical writing questions. The \fI\%NCBI style
guide\fP is another very approachable resource.
.SS Point\-of\-view
.sp
Use third\-person perspective and avoid "I", "we", "you" forms of address.
Identify the addressee specifically e.g., "users should", "the compiler does",
etc.
.SS Active voice
.sp
Use active voice and present\-tense. Avoid filler words.
.SS Title capitalization
.sp
Document titles and section titles within a page should follow normal sentence
capitalization rules. Words that are capitalized as part of a regular sentence
should be capitalized in a title and otherwise left as lowercase. Punctuation
can be omitted unless it aids the intent of the title (e.g., exclamation points
or question marks).
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
This is a main heading
======================
Paragraph.
This is an exciting sub\-heading!
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Paragraph.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Documenting modules
.sp
Documentation for Salt\(aqs various module types is inline in the code. During the
documentation build process it is extracted and formatted into the final HTML,
PDF, etc format.
.SS Inline documentation
.sp
Python has special multi\-line strings called docstrings as the first element in
a function or class. These strings allow documentation to live alongside the
code and can contain special formatting. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def myfunction(value):
\(aq\(aq\(aq
Upper\-case the given value
Usage:
.. code\-block:: python
val = \(aqa string\(aq
new_val = myfunction(val)
print(new_val) # \(aqA STRING\(aq
:param value: a string
:return: a copy of \(ga\(gavalue\(ga\(ga that has been upper\-cased
\(aq\(aq\(aq
return value.upper()
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Specify a release for additions or changes
.sp
New functions or changes to existing functions should include a marker that
denotes what Salt release will be affected. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def myfunction(value):
\(aq\(aq\(aq
Upper\-case the given value
.. versionadded:: 2014.7.0
<...snip...>
\(aq\(aq\(aq
return value.upper()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For changes to a function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def myfunction(value, strip=False):
\(aq\(aq\(aq
Upper\-case the given value
.. versionchanged:: Boron
Added a flag to also strip whitespace from the string.
<...snip...>
\(aq\(aq\(aq
if strip:
return value.upper().strip()
return value.upper()
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Adding module documentation to the index
.sp
Each module type has an index listing all modules of that type. For example:
\fIall\-salt.modules\fP, \fIall\-salt.states\fP, \fIall\-salt.renderers\fP\&.
New modules must be added to the index manually.
.INDENT 0.0
.IP 1. 3
Edit the file for the module type:
\fI\%execution modules\fP,
\fI\%state modules\fP,
\fI\%renderer modules\fP, etc.
.IP 2. 3
Add the new module to the alphebetized list.
.IP 3. 3
\fI\%Build the documentation\fP which will generate an \fB\&.rst\fP
file for the new module in the same directory as the \fBindex.rst\fP\&.
.IP 4. 3
Commit the changes to \fBindex.rst\fP and the new \fB\&.rst\fP file and send a
pull request.
.UNINDENT
.SS Cross\-references
.sp
The Sphinx documentation system contains a wide variety of cross\-referencing
capabilities.
.SS Glossary entries
.sp
Link to \fI\%glossary entries\fP using the \fI\%term role\fP\&. A
cross\-reference should be added the first time a Salt\-specific term is used in
a document.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A common way to encapsulate master\-side functionality is by writing a
custom :term:\(gaRunner Function\(ga. Custom Runner Functions are easy to write.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Index entries
.sp
Sphinx automatically generates many kind of index entries but it is
occasionally useful to manually add items to the index.
.sp
One method is to use the \fI\%index directive\fP above the document or section that
should appear in the index.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. index:: ! Event, event bus, event system
see: Reactor; Event
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Another method is to use the \fI\%index role\fP inline with the text that should
appear in the index. The index entry is created and the target text is left
otherwise intact.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Information about the :index:\(gaSalt Reactor\(ga
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Paragraph.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Documents and sections
.sp
Each document should contain a unique top\-level label of the form:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. _my\-page:
My page
=======
Paragraph.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Unique labels can be linked using the \fI\%ref role\fP\&. This allows cross\-references
to survive document renames or movement.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
For more information see :ref:\(gamy\-page\(ga.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note, the \fB:doc:\fP role should \fInot\fP be used to link documents together.
.SS Modules
.sp
Cross\-references to Salt modules can be added using Sphinx\(aqs Python domain
roles. For example, to create a link to the \fBtest.ping\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A useful execution module to test active communication with a minion is the
:py:func:\(gatest.ping <salt.modules.test.ping>\(ga function.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt modules can be referenced as well:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
The :py:mod:\(gatest module <salt.modules.test>\(ga contains many useful
functions for inspecting an active Salt connection.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The same syntax works for all modules types:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
One of the workhorse state module functions in Salt is the
:py:func:\(gafile.managed <salt.states.file.managed>\(ga function.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Settings
.sp
Individual settings in the Salt Master or Salt Minion configuration files are
cross\-referenced using two custom roles, \fBconf_master\fP and \fBconf_minion\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
The :conf_minion:\(gaminion ID <id>\(ga setting is a unique identifier for a
single minion.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Building the documentation
.INDENT 0.0
.IP 1. 3
Install Sphinx using a system package manager or pip. The package name is
often of the form \fBpython\-sphinx\fP\&. There are no other dependencies.
.IP 2. 3
Build the documentation using the provided Makefile or \fB\&.bat\fP file on
Windows.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
cd /path/to/salt/doc
make html
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
The generated documentation will be written to the \fBdoc/_build/<format>\fP
directory.
.IP 4. 3
A useful method of viewing the HTML documentation locally is the start
Python\(aqs built\-in HTTP server:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
cd /path/to/salt/doc/_build/html
python \-m SimpleHTTPServer
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then pull up the documentation in a web browser at \fI\%http://localhost:8000/\fP\&.
.UNINDENT
.SS Salt Formulas
.sp
Formulas are pre\-written Salt States. They are as open\-ended as Salt States
themselves and can be used for tasks such as installing a package, configuring
and starting a service, setting up users or permissions, and many other common
tasks.
.sp
All official Salt Formulas are found as separate Git repositories in the
"saltstack\-formulas" organization on GitHub:
.sp
\fI\%https://github.com/saltstack\-formulas\fP
.sp
As a simple example, to install the popular Apache web server (using the normal
defaults for the underlying distro) simply include the
\fI\%apache\-formula\fP from a top file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqweb*\(aq:
\- apache
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Installation
.sp
Each Salt Formula is an individual Git repository designed as a drop\-in
addition to an existing Salt State tree. Formulas can be installed in the
following ways.
.SS Adding a Formula as a GitFS remote
.sp
One design goal of Salt\(aqs GitFS fileserver backend was to facilitate reusable
States. GitFS is a quick and natural way to use Formulas.
.INDENT 0.0
.IP 1. 3
\fIInstall and configure GitFS\fP\&.
.IP 2. 3
Add one or more Formula repository URLs as remotes in the
\fBgitfs_remotes\fP list in the Salt Master configuration file:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
gitfs_remotes:
\- https://github.com/saltstack\-formulas/apache\-formula
\- https://github.com/saltstack\-formulas/memcached\-formula
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBWe strongly recommend forking a formula repository\fP into your own GitHub
account to avoid unexpected changes to your infrastructure.
.sp
Many Salt Formulas are highly active repositories so pull new changes with
care. Plus any additions you make to your fork can be easily sent back
upstream with a quick pull request!
.IP 3. 3
Restart the Salt master.
.UNINDENT
.SS Adding a Formula directory manually
.sp
Formulas are simply directories that can be copied onto the local file system
by using Git to clone the repository or by downloading and expanding a tarball
or zip file of the repository. The directory structure is designed to work with
\fBfile_roots\fP in the Salt master configuration.
.INDENT 0.0
.IP 1. 3
Clone or download the repository into a directory:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
mkdir \-p /srv/formulas
cd /srv/formulas
git clone https://github.com/saltstack\-formulas/apache\-formula.git
# or
mkdir \-p /srv/formulas
cd /srv/formulas
wget https://github.com/saltstack\-formulas/apache\-formula/archive/master.tar.gz
tar xf apache\-formula\-master.tar.gz
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Add the new directory to \fBfile_roots\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
file_roots:
\- /srv/salt
\- /srv/formulas/apache\-formula
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Restart the Salt Master.
.UNINDENT
.SS Usage
.sp
Each Formula is intended to be immediately usable with sane defaults without
any additional configuration. Many formulas are also configurable by including
data in Pillar; see the \fBpillar.example\fP file in each Formula repository
for available options.
.SS Including a Formula in an existing State tree
.sp
Formula may be included in an existing \fBsls\fP file. This is often useful when
a state you are writing needs to \fBrequire\fP or \fBextend\fP a state defined in
the formula.
.sp
Here is an example of a state that uses the \fI\%epel\-formula\fP in a
\fBrequire\fP declaration which directs Salt to not install the \fBpython26\fP
package until after the EPEL repository has also been installed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- epel
python26:
pkg.installed:
\- require:
\- pkg: epel
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Including a Formula from a Top File
.sp
Some Formula perform completely standalone installations that are not
referenced from other state files. It is usually cleanest to include these
Formula directly from a Top File.
.sp
For example the easiest way to set up an OpenStack deployment on a single
machine is to include the \fI\%openstack\-standalone\-formula\fP directly from
a \fBtop.sls\fP file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqmyopenstackmaster\(aq:
\- openstack
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Quickly deploying OpenStack across several dedicated machines could also be
done directly from a Top File and may look something like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aqcontroller\(aq:
\- openstack.horizon
\- openstack.keystone
\(aqhyper\-*\(aq:
\- openstack.nova
\- openstack.glance
\(aqstorage\-*\(aq:
\- openstack.swift
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configuring Formula using Pillar
.sp
Salt Formulas are designed to work out of the box with no additional
configuration. However, many Formula support additional configuration and
customization through \fIPillar\fP\&. Examples of available options can
be found in a file named \fBpillar.example\fP in the root directory of each
Formula repository.
.SS Using Formula with your own states
.sp
Remember that Formula are regular Salt States and can be used with all Salt\(aqs
normal state mechanisms. Formula can be required from other States with
\fIrequisites\-require\fP declarations, they can be modified using \fBextend\fP,
they can made to watch other states with \fIrequisites\-watch\-in\fP\&.
.sp
The following example uses the stock \fI\%apache\-formula\fP alongside a
custom state to create a vhost on a Debian/Ubuntu system and to reload the
Apache service whenever the vhost is changed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Include the stock, upstream apache formula.
include:
\- apache
# Use the watch_in requisite to cause the apache service state to reload
# apache whenever the my\-example\-com\-vhost state changes.
my\-example\-com\-vhost:
file:
\- managed
\- name: /etc/apache2/sites\-available/my\-example\-com
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Don\(aqt be shy to read through the source for each Formula!
.SS Reporting problems & making additions
.sp
Each Formula is a separate repository on GitHub. If you encounter a bug with a
Formula please file an issue in the respective repository! Send fixes and
additions as a pull request. Add tips and tricks to the repository wiki.
.SS Writing Formulas
.sp
Each Formula is a separate repository in the \fI\%saltstack\-formulas\fP organization
on GitHub.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Get involved creating new Formulas
.sp
The best way to create new Formula repositories for now is to create a
repository in your own account on GitHub and notify a SaltStack employee
when it is ready. We will add you to the contributors team on the
\fI\%saltstack\-formulas\fP organization and help you transfer the repository
over. Ping a SaltStack employee on IRC (\fB#salt\fP on Freenode) or send an
email to the \fI\%salt\-users\fP mailing list.
.sp
There are a lot of repositories in that organization! Team members can
manage which repositories they are subscribed to on GitHub\(aqs watching page:
\fI\%https://github.com/watching\fP\&.
.UNINDENT
.UNINDENT
.SS Style
.sp
Maintainability, readability, and reusability are all marks of a good Salt sls
file. This section contains several suggestions and examples.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Deploy the stable master branch unless version overridden by passing
# Pillar at the CLI or via the Reactor.
deploy_myapp:
git.latest:
\- name: git@github.com/myco/myapp.git
\- version: {{ salt.pillar.get(\(aqmyapp:version\(aq, \(aqmaster\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Use a descriptive State ID
.sp
The ID of a state is used as a unique identifier that may be referenced via
other states in \fIrequisites\fP\&. It must be unique across the
whole state tree (\fIit is a key in a dictionary\fP, after
all).
.sp
In addition a state ID should be descriptive and serve as a high\-level hint of
what it will do, or manage, or change. For example, \fBdeploy_webapp\fP, or
\fBapache\fP, or \fBreload_firewall\fP\&.
.SS Use \fBmodule.function\fP notation
.sp
So\-called "short\-declaration" notation is preferred for referencing state
modules and state functions. It provides a consistent pattern of
\fBmodule.function\fP shared between Salt States, the Reactor, Overstate, Salt
Mine, the Scheduler, as well as with the CLI.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Do
apache:
pkg.installed:
\- name: httpd
# Don\(aqt
apache:
pkg:
\- installed
\- name: httpd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt\(aqs state compiler will transform "short\-decs" into the longer format
\fIwhen compiling the human\-friendly highstate structure into the
machine\-friendly lowstate structure\fP\&.
.SS Specify the \fBname\fP parameter
.sp
Use a unique and permanent identifier for the state ID and reserve \fBname\fP for
data with variability.
.sp
The \fIname declaration\fP is a required parameter for all
state functions. The state ID will implicitly be used as \fBname\fP if it is not
explicitly set in the state.
.sp
In many state functions the \fBname\fP parameter is used for data that varies
such as OS\-specific package names, OS\-specific file system paths, repository
addresses, etc. Any time the ID of a state changes all references to that ID
must also be changed. Use a permanent ID when writing a state the first time to
future\-proof that state and allow for easier refactors down the road.
.SS Comment state files
.sp
YAML allows comments at varying indentation levels. It is a good practice to
comment state files. Use vertical whitespace to visually separate different
concepts or actions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Start with a high\-level description of the current sls file.
# Explain the scope of what it will do or manage.
# Comment individual states as necessary.
update_a_config_file:
# Provide details on why an unusual choice was made. For example:
#
# This template is fetched from a third\-party and does not fit our
# company norm of using Jinja. This must be processed using Mako.
file.managed:
\- name: /path/to/file.cfg
\- source: salt://path/to/file.cfg.template
\- template: mako
# Provide a description or explanation that did not fit within the state
# ID. For example:
#
# Update the application\(aqs last\-deployed timestamp.
# This is a workaround until Bob configures Jenkins to automate RPM
# builds of the app.
cmd.run:
# FIXME: Joe needs this to run on Windows by next quarter. Switch these
# from shell commands to Salt\(aqs file.managed and file.replace state
# modules.
\- name: |
touch /path/to/file_last_updated
sed \-e \(aqs/foo/bar/g\(aq /path/to/file_environment
\- onchanges:
\- file: a_config_file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Be careful to use Jinja comments for commenting Jinja code and YAML comments
for commenting YAML code.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# BAD EXAMPLE
# The Jinja in this YAML comment is still executed!
# {% set apache_is_installed = \(aqapache\(aq in salt.pkg.list_pkgs() %}
# GOOD EXAMPLE
# The Jinja in this Jinja comment will not be executed.
{# {% set apache_is_installed = \(aqapache\(aq in salt.pkg.list_pkgs() %} #}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Easy on the Jinja!
.sp
Jinja templating provides vast flexibility and power when building Salt sls
files. It can also create an unmaintainable tangle of logic and data. Speaking
broadly, Jinja is best used when kept apart from the states (as much as is
possible).
.sp
Below are guidelines and examples of how Jinja can be used effectively.
.SS Know the evaluation and execution order
.sp
High\-level knowledge of how Salt states are compiled and run is useful when
writing states.
.sp
The default \fBrenderer\fP setting in Salt is Jinja piped to YAML.
Each is a separate step. Each step is not aware of the previous or following
step. Jinja is not YAML aware, YAML is not Jinja aware; they cannot share
variables or interact.
.INDENT 0.0
.IP \(bu 2
Whatever the Jinja step produces must be valid YAML.
.IP \(bu 2
Whatever the YAML step produces must be a valid \fIhighstate data
structure\fP\&. (This is also true of the final step
for \fIany of the alternate renderers\fP in Salt.)
.IP \(bu 2
Highstate can be thought of as a human\-friendly data structure; easy to write
and easy to read.
.IP \(bu 2
Salt\(aqs state compiler validates the highstate and compiles it to low state.
.IP \(bu 2
Low state can be thought of as a machine\-friendly data structure. It is a
list of dictionaries that each map directly to a function call.
.IP \(bu 2
Salt\(aqs state system finally starts and executes on each "chunk" in the low
state. Remember that requisites are evaluated at runtime.
.IP \(bu 2
The return for each function call is added to the "running" dictionary which
is the final output at the end of the state run.
.UNINDENT
.sp
The full evaluation and execution order:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Jinja \-> YAML \-> Highstate \-> low state \-> execution
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Avoid changing the underlying system with Jinja
.sp
Avoid calling commands from Jinja that change the underlying system. Commands
run via Jinja do not respect Salt\(aqs dry\-run mode (\fBtest=True\fP)! This is
usually in conflict with the idempotent nature of Salt states unless the
command being run is also idempotent.
.SS Inspect the local system
.sp
A common use for Jinja in Salt states is to gather information about the
underlying system. The \fBgrains\fP dictionary available in the Jinja context is
a great example of common data points that Salt itself has already gathered.
Less common values are often found by running commands. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set is_selinux_enabled = salt.cmd.run(\(aqsestatus\(aq) == \(aq1\(aq %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is usually best done with a variable assignment in order to separate the
data from the state that will make use of the data.
.SS Gather external data
.sp
One of the most common uses for Jinja is to pull external data into the state
file. External data can come from anywhere like API calls or database queries,
but it most commonly comes from flat files on the file system or Pillar data
from the Salt Master. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set some_data = salt.pillar.get(\(aqsome_data\(aq, {\(aqsane default\(aq: True}) %}
{# or #}
{% load_json \(aqpath/to/file.json\(aq as some_data %}
{# or #}
{% load_text \(aqpath/to/ssh_key.pub\(aq as ssh_pub_key %}
{# or #}
{% from \(aqpath/to/other_file.jinja\(aq import some_data with context %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is usually best done with a variable assignment in order to separate the
data from the state that will make use of the data.
.SS Light conditionals and looping
.sp
Jinja is extremely powerful for programatically generating Salt states. It is
also easy to overuse. As a rule of thumb, if it is hard to read it will be hard
to maintain!
.sp
Separate Jinja control\-flow statements from the states as much as is possible
to create readable states. Limit Jinja within states to simple variable
lookups.
.sp
Below is a simple example of a readable loop:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% for user in salt.pillar.get(\(aqlist_of_users\(aq, []) %}
{# Ensure unique state IDs when looping. #}
{{ user.name }}\-{{ loop.index }}:
user.present:
\- name: {{ user.name }}
\- shell: {{ user.shell }}
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Avoid putting a Jinja conditionals within Salt states where possible.
Readability suffers and the correct YAML indentation is difficult to see in the
surrounding visual noise. Parameterization (discussed below) and variables are
both useful techniques to avoid this. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{# \-\-\-\- Bad example \-\-\-\- #}
apache:
pkg.installed:
{% if grains.os_family == \(aqRedHat\(aq %}
\- name: httpd
{% elif grains.os_family == \(aqDebian\(aq %}
\- name: apache2
{% endif %}
{# \-\-\-\- Better example \-\-\-\- #}
{% if grains.os_family == \(aqRedHat\(aq %}
{% set name = \(aqhttpd\(aq %}
{% elif grains.os_family == \(aqDebian\(aq %}
{% set name = \(aqapache2\(aq %}
{% endif %}
apache:
pkg.installed:
\- name: {{ name }}
{# \-\-\-\- Good example \-\-\-\- #}
{% set name = {
\(aqRedHat\(aq: \(aqhttpd\(aq,
\(aqDebian\(aq: \(aqapache2\(aq,
}.get(grains.os_family) %}
apache:
pkg.installed:
\- name: {{ name }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Dictionaries are useful to effectively "namespace" a collection of variables.
This is useful with parameterization (discussed below). Dictionaries are also
easily combined and merged. And they can be directly serialized into YAML which
is often easier than trying to create valid YAML through templating. For
example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{# \-\-\-\- Bad example \-\-\-\- #}
haproxy_conf:
file.managed:
\- name: /etc/haproxy/haproxy.cfg
\- template: jinja
{% if \(aqexternal_loadbalancer\(aq in grains.roles %}
\- source: salt://haproxy/external_haproxy.cfg
{% elif \(aqinternal_loadbalancer\(aq in grains.roles %}
\- source: salt://haproxy/internal_haproxy.cfg
{% endif %}
\- context:
{% if \(aqexternal_loadbalancer\(aq in grains.roles %}
ssl_termination: True
{% elif \(aqinternal_loadbalancer\(aq in grains.roles %}
ssl_termination: False
{% endif %}
{# \-\-\-\- Better example \-\-\-\- #}
{% load_yaml as haproxy_defaults %}
common_settings:
bind_port: 80
internal_loadbalancer:
source: salt://haproxy/internal_haproxy.cfg
settings:
bind_port: 8080
ssl_termination: False
external_loadbalancer:
source: salt://haproxy/external_haproxy.cfg
settings:
ssl_termination: True
{% endload %}
{% if \(aqexternal_loadbalancer\(aq in grains.roles %}
{% set haproxy = haproxy_defaults[\(aqexternal_loadbalancer\(aq] %}
{% elif \(aqinternal_loadbalancer\(aq in grains.roles %}
{% set haproxy = haproxy_defaults[\(aqinternal_loadbalancer\(aq] %}
{% endif %}
{% do haproxy.settings.update(haproxy_defaults.common_settings) %}
haproxy_conf:
file.managed:
\- name: /etc/haproxy/haproxy.cfg
\- template: jinja
\- source: {{ haproxy.source }}
\- context: {{ haproxy.settings | yaml() }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There is still room for improvement in the above example. For example,
extracting into an external file or replacing the if\-elif conditional with a
function call to filter the correct data more succinctly. However, the state
itself is simple and legible, the data is separate and also simple and legible.
And those suggested improvements can be made at some future date without
altering the state at all!
.SS Avoid heavy logic and programming
.sp
Jinja is not Python. It was made by Python programmers and shares many
semantics and some syntax but it does not allow for abitrary Python function
calls or Python imports. Jinja is a fast and efficient templating language but
the syntax can be verbose and visually noisy.
.sp
Once Jinja use within an sls file becomes slightly complicated \-\- long chains
of if\-elif\-elif\-else statements, nested conditionals, complicated dictionary
merges, wanting to use sets \-\- instead consider using a different Salt
renderer, such as the Python renderer. As a rule of thumb, if it is hard to
read it will be hard to maintain \-\- switch to a format that is easier to read.
.sp
Using alternate renderers is very simple to do using Salt\(aqs "she\-bang" syntax
at the top of the file. The Python renderer must simply return the correct
\fIhighstate data structure\fP\&. The following
example is a state tree of two sls files, one simple and one complicated.
.sp
\fB/srv/salt/top.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- common_configuration
\- roles_configuration
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/common_configuration.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
common_users:
user.present:
\- names: [larry, curly, moe]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/roles_configuration\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!py
def run():
list_of_roles = set()
# This example has the minion id in the form \(aqweb\-03\-dev\(aq.
# Easily access the grains dictionary:
try:
app, instance_number, environment = __grains__[\(aqid\(aq].split(\(aq\-\(aq)
instance_number = int(instance_number)
except ValueError:
app, instance_number, environment = [\(aqUnknown\(aq, 0, \(aqdev\(aq]
list_of_roles.add(app)
if app == \(aqweb\(aq and environment == \(aqdev\(aq:
list_of_roles.add(\(aqprimary\(aq)
list_of_roles.add(\(aqsecondary\(aq)
elif app == \(aqweb\(aq and environment == \(aqstaging\(aq:
if instance_number == 0:
list_of_roles.add(\(aqprimary\(aq)
else:
list_of_roles.add(\(aqsecondary\(aq)
# Easily cross\-call Salt execution modules:
if __salt__[\(aqmyutils.query_valid_ec2_instance\(aq]():
list_of_roles.add(\(aqis_ec2_instance\(aq)
return {
\(aqset_roles_grains\(aq: {
\(aqgrains.present\(aq: [
{\(aqname\(aq: \(aqroles\(aq},
{\(aqvalue\(aq: list(list_of_roles)},
],
},
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Jinja Macros
.sp
In Salt sls files Jinja macros are useful for one thing and one thing only:
creating mini templates that can be reused and rendered on demand. Do not fall
into the trap of thinking of macros as functions; Jinja is not Python (see
above).
.sp
Macros are useful for creating reusable, parameterized states. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% macro user_state(state_id, user_name, shell=\(aq/bin/bash\(aq, groups=[]) %}
{{ state_id }}:
user.present:
\- name: {{ user_name }}
\- shell: {{ shell }}
\- groups: {{ groups | json() }}
{% endmacro %}
{% for user_info in salt.pillar.get(\(aqmy_users\(aq, []) %}
{{ user_state(\(aquser_number_\(aq ~ loop.index, **user_info) }}
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Macros are also useful for creating one\-off "serializers" that can accept a
data structure and write that out as a domain\-specific configuration file. For
example, the following macro could be used to write a php.ini config file:
.sp
\fB/srv/salt/php.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
php_ini:
file.managed:
\- name: /etc/php.ini
\- source: salt://php.ini.tmpl
\- template: jinja
\- context:
php_ini_settings: {{ salt.pillar.get(\(aqphp_ini\(aq, {}) | json() }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/php.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
PHP:
engine: \(aqOn\(aq
short_open_tag: \(aqOff\(aq
error_reporting: \(aqE_ALL & ~E_DEPRECATED & ~E_STRICT\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/php.ini.tmpl\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% macro php_ini_serializer(data) %}
{% for section_name, name_val_pairs in data.items() %}
[{{ section }}]
{% for name, val in name_val_pairs.items() %}
{{ name }} = "{{ val }}"
{% endfor %}
{% endfor %}
{% endmacro %}
; File managed by Salt at <{{ source }}>.
; Your changes will be overwritten.
{{ php_ini_serializer(php_ini_settings) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Abstracting static defaults into a lookup table
.sp
Separate data that a state uses from the state itself to increases the
flexibility and reusability of a state.
.sp
An obvious and common example of this is platform\-specific package names and
file system paths. Another example is sane defaults for an application, or
common settings within a company or organization. Organizing such data as a
dictionary (aka hash map, lookup table, associative array) often provides a
lightweight namespacing and allows for quick and easy lookups. In addition,
using a dictionary allows for easily merging and overriding static values
within a lookup table with dynamic values fetched from Pillar.
.sp
A strong convention in Salt Formulas is to place platform\-specific data, such
as package names and file system paths, into a file named \fBmap.jinja\fP
that is placed alongside the state files.
.sp
The following is an example from the MySQL Formula.
The \fBgrains.filter_by\fP function
performs a lookup on that table using the \fBos_family\fP grain (by default).
.sp
The result is that the \fBmysql\fP variable is assigned to a \fIsubset\fP of
the lookup table for the current platform. This allows states to reference, for
example, the name of a package without worrying about the underlying OS. The
syntax for referencing a value is a normal dictionary lookup in Jinja, such as
\fB{{ mysql[\(aqservice\(aq] }}\fP or the shorthand \fB{{ mysql.service }}\fP\&.
.sp
\fBmap.jinja\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set mysql = salt[\(aqgrains.filter_by\(aq]({
\(aqDebian\(aq: {
\(aqserver\(aq: \(aqmysql\-server\(aq,
\(aqclient\(aq: \(aqmysql\-client\(aq,
\(aqservice\(aq: \(aqmysql\(aq,
\(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq,
\(aqpython\(aq: \(aqpython\-mysqldb\(aq,
},
\(aqRedHat\(aq: {
\(aqserver\(aq: \(aqmysql\-server\(aq,
\(aqclient\(aq: \(aqmysql\(aq,
\(aqservice\(aq: \(aqmysqld\(aq,
\(aqconfig\(aq: \(aq/etc/my.cnf\(aq,
\(aqpython\(aq: \(aqMySQL\-python\(aq,
},
\(aqGentoo\(aq: {
\(aqserver\(aq: \(aqdev\-db/mysql\(aq,
\(aqmysql\-client\(aq: \(aqdev\-db/mysql\(aq,
\(aqservice\(aq: \(aqmysql\(aq,
\(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq,
\(aqpython\(aq: \(aqdev\-python/mysql\-python\(aq,
},
}, merge=salt[\(aqpillar.get\(aq](\(aqmysql:lookup\(aq)) %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Values defined in the map file can be fetched for the current platform in any
state file using the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% from "mysql/map.jinja" import mysql with context %}
mysql\-server:
pkg.installed:
\- name: {{ mysql.server }}
service.running:
\- name: {{ mysql.service }}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Overriding values in the lookup table
.sp
Allow static values within lookup tables to be overridden. This is a simple
pattern which once again increases flexibility and reusability for state files.
.sp
The \fBmerge\fP argument in \fBfilter_by\fP
specifies the location of a dictionary in Pillar that can be used to override
values returned from the lookup table. If the value exists in Pillar it will
take precedence.
.sp
This is useful when software or configuration files is installed to
non\-standard locations or on unsupported platforms. For example, the following
Pillar would replace the \fBconfig\fP value from the call above.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mysql:
lookup:
config: /usr/local/etc/mysql/my.cnf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBfilter_by\fP function performs a
simple dictionary lookup but also allows for fetching data from Pillar and
overriding data stored in the lookup table. That same workflow can be easily
performed without using \fBfilter_by\fP; other dictionaries besides data from
Pillar can also be used.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set lookup_table = {...} %}
{% do lookup_table.update(salt.pillar.get(\(aqmy:custom:data\(aq)) %}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS When to use lookup tables
.sp
The \fBmap.jinja\fP file is only a convention within Salt Formulas. This greater
pattern is useful for a wide variety of data in a wide variety of workflows.
This pattern is not limited to pulling data from a single file or data source.
This pattern is useful in States, Pillar, the Reactor, and Overstate as well.
.sp
Working with a data structure instead of, say, a config file allows the data to
be cobbled together from multiple sources (local files, remote Pillar, database
queries, etc), combined, overridden, and searched.
.sp
Below are a few examples of what lookup tables may be useful for and how they
may be used and represented.
.SS Platform\-specific information
.sp
An obvious pattern and one used heavily in Salt Formulas is extracting
platform\-specific information such as package names and file system paths in
a file named \fBmap.jinja\fP\&. The pattern is explained in detail above.
.SS Sane defaults
.sp
Application settings can be a good fit for this pattern. Store default
settings along with the states themselves and keep overrides and sensitive
settings in Pillar. Combine both into a single dictionary and then write the
application config or settings file.
.sp
The example below stores most of the Apache Tomcat \fBserver.xml\fP file
alongside the Tomcat states and then allows values to be updated or augmented
via Pillar. (This example uses the BadgerFish format for transforming JSON to
XML.)
.sp
\fB/srv/salt/tomcat/defaults.yaml\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Server:
\(aq@port\(aq: \(aq8005\(aq
\(aq@shutdown\(aq: SHUTDOWN
GlobalNamingResources:
Resource:
\(aq@auth\(aq: Container
\(aq@description\(aq: User database that can be updated and saved
\(aq@factory\(aq: org.apache.catalina.users.MemoryUserDatabaseFactory
\(aq@name\(aq: UserDatabase
\(aq@pathname\(aq: conf/tomcat\-users.xml
\(aq@type\(aq: org.apache.catalina.UserDatabase
# <...snip...>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/pillar/tomcat.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
appX:
server_xml_overrides:
Server:
Service:
\(aq@name\(aq: Catalina
Connector:
\(aq@port\(aq: \(aq8009\(aq
\(aq@protocol\(aq: AJP/1.3
\(aq@redirectPort\(aq: \(aq8443\(aq
# <...snip...>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/tomcat/server_xml.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% load_yaml \(aqtomcat/defaults.yaml\(aq as server_xml_defaults %}
{% set server_xml_final_values = salt.pillar.get(
\(aqappX:server_xml_overrides\(aq,
default=server_xml_defaults,
merge=True)
%}
appX_server_xml:
file.serialize:
\- name: /etc/tomcat/server.xml
\- dataset: {{ server_xml_final_values | json() }}
\- formatter: xml_badgerfish
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBfile.serialize\fP state can provide a
shorthand for creating some files from data structures. There are also many
examples within Salt Formulas of creating one\-off "serializers" (often as Jinja
macros) that reformat a data structure to a specific config file format. For
example,
.nf
\(gaNginx vhosts\(ga__
.fi
or the
.nf
\(gaphp.ini\(ga__
.fi
.sp
__: \fI\%https://github.com/saltstack\-formulas/nginx\-formula/blob/5cad4512/nginx/ng/vhosts_config.sls\fP
__: \fI\%https://github.com/saltstack\-formulas/php\-formula/blob/82e2cd3a/php/ng/files/php.ini\fP
.SS Environment specific information
.sp
A single state can be reused when it is parameterized as described in the
section below, by separating the data the state will use from the state that
performs the work. This can be the difference between deploying \fIApplication X\fP
and \fIApplication Y\fP, or the difference between production and development. For
example:
.sp
\fB/srv/salt/app/deploy.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{# Load the map file. #}
{% load_yaml \(aqapp/defaults.yaml\(aq as app_defaults %}
{# Extract the relevant subset for the app configured on the current
machine (configured via a grain in this example). #}
{% app = app_defaults.get(salt.grains.get(\(aqrole\(aq) %}
{# Allow values from Pillar to (optionally) update values from the lookup
table. #}
{% do app_defaults.update(salt.pillar.get(\(aqmyapp\(aq, {}) %}
deploy_application:
git.latest:
\- name: {{ app.repo_url }}
\- version: {{ app.version }}
\- target: {{ app.deploy_dir }}
myco/myapp/deployed:
event.send:
\- data:
version: {{ app.version }}
\- onchanges:
\- git: deploy_application
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB/srv/salt/app/defaults.yaml\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
appX:
repo_url: git@github.com/myco/appX.git
target: /var/www/appX
version: master
appY:
repo_url: git@github.com/myco/appY.git
target: /var/www/appY
version: v1.2.3.4
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Single\-purpose SLS files
.sp
Each sls file in a Formula should strive to do a single thing. This increases
the reusability of this file by keeping unrelated tasks from getting coupled
together.
.sp
As an example, the base Apache formula should only install the Apache httpd
server and start the httpd service. This is the basic, expected behavior when
installing Apache. It should not perform additional changes such as set the
Apache configuration file or create vhosts.
.sp
If a formula is single\-purpose as in the example above, other formulas, and
also other states can \fBinclude\fP and use that formula with \fIrequisites\fP
without also including undesirable or unintended side\-effects.
.sp
The following is a best\-practice example for a reusable Apache formula. (This
skips platform\-specific options for brevity. See the full
\fI\%apache\-formula\fP for more.)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# apache/init.sls
apache:
pkg.installed:
[...]
service.running:
[...]
# apache/mod_wsgi.sls
include:
\- apache
mod_wsgi:
pkg.installed:
[...]
\- require:
\- pkg: apache
# apache/conf.sls
include:
\- apache
apache_conf:
file.managed:
[...]
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To illustrate a bad example, say the above Apache formula installed Apache and
also created a default vhost. The mod_wsgi state would not be able to include
the Apache formula to create that dependency tree without also installing the
unneeded default vhost.
.sp
\fI\%Formulas should be reusable\fP\&. Avoid coupling
unrelated actions together.
.SS Parameterization
.sp
\fIParameterization is a key feature of Salt Formulas\fP and also for Salt
States. Parameterization allows a single Formula to be reused across many
operating systems; to be reused across production, development, or staging
environments; and to be reused by many people all with varying goals.
.sp
Writing states, specifying ordering and dependencies is the part that takes the
longest to write and to test. Filling those states out with data such as users
or package names or file locations is the easy part. How many users, what those
users are named, or where the files live are all implementation details that
\fBshould be parameterized\fP\&. This separation between a state and the data that
populates a state creates a reusable formula.
.sp
In the example below the data that populates the state can come from anywhere
\-\- it can be hard\-coded at the top of the state, it can come from an external
file, it can come from Pillar, it can come from an execution function call, or
it can come from a database query. The state itself doesn\(aqt change regardless
of where the data comes from. Production data will vary from development data
will vary from data from one company to another, however the state itself stays
the same.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% set user_list = [
{\(aqname\(aq: \(aqlarry\(aq, \(aqshell\(aq: \(aqbash\(aq},
{\(aqname\(aq: \(aqcurly\(aq, \(aqshell\(aq: \(aqbash\(aq},
{\(aqname\(aq: \(aqmoe\(aq, \(aqshell\(aq: \(aqzsh\(aq},
] %}
{# or #}
{% set user_list = salt[\(aqpillar.get\(aq](\(aquser_list\(aq) %}
{# or #}
{% load_json "default_users.json" as user_list %}
{# or #}
{% set user_list = salt[\(aqacme_utils.get_user_list\(aq]() %}
{% for user in list_list %}
{{ user.name }}:
user.present:
\- name: {{ user.name }}
\- shell: {{ user.shell }}
{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configuration
.sp
Formulas should strive to use the defaults of the underlying platform, followed
by defaults from the upstream project, followed by sane defaults for the
formula itself.
.sp
As an example, a formula to install Apache \fBshould not\fP change the default
Apache configuration file installed by the OS package. However, the Apache
formula \fBshould\fP include a state to change or override the default
configuration file.
.SS Pillar overrides
.sp
Pillar lookups must use the safe \fBget()\fP
and must provide a default value. Create local variables using the Jinja
\fBset\fP construct to increase redability and to avoid potentially hundreds or
thousands of function calls across a large state tree.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% from "apache/map.jinja" import apache with context %}
{% set settings = salt[\(aqpillar.get\(aq](\(aqapache\(aq, {}) %}
mod_status:
file.managed:
\- name: {{ apache.conf_dir }}
\- source: {{ settings.get(\(aqmod_status_conf\(aq, \(aqsalt://apache/mod_status.conf\(aq) }}
\- template: {{ settings.get(\(aqtemplate_engine\(aq, \(aqjinja\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Any default values used in the Formula must also be documented in the
\fBpillar.example\fP file in the root of the repository. Comments should be
used liberally to explain the intent of each configuration value. In addition,
users should be able copy\-and\-paste the contents of this file into their own
Pillar to make any desired changes.
.SS Scripting
.sp
Remember that both State files and Pillar files can easily call out to Salt
\fIexecution modules\fP and have access to all the system
grains as well.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{% if \(aq/storage\(aq in salt[\(aqmount.active\(aq]() %}
/usr/local/etc/myfile.conf:
file:
\- symlink
\- target: /storage/myfile.conf
{% endif %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Jinja macros to encapsulate logic or conditionals are discouraged in favor of
\fIwriting custom execution modules\fP in Python.
.SS Repository structure
.sp
A basic Formula repository should have the following layout:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo\-formula
|\-\- foo/
| |\-\- map.jinja
| |\-\- init.sls
| \(ga\-\- bar.sls
|\-\- CHANGELOG.rst
|\-\- LICENSE
|\-\- pillar.example
|\-\- README.rst
\(ga\-\- VERSION
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fI\%template\-formula\fP
.sp
The \fI\%template\-formula\fP repository has a pre\-built layout that
serves as the basic structure for a new formula repository. Just copy the
files from there and edit them.
.UNINDENT
.UNINDENT
.SS \fBREADME.rst\fP
.sp
The README should detail each available \fB\&.sls\fP file by explaining what it
does, whether it has any dependencies on other formulas, whether it has a
target platform, and any other installation or usage instructions or tips.
.sp
A sample skeleton for the \fBREADME.rst\fP file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
===
foo
===
Install and configure the FOO service.
\&.. note::
See the full \(gaSalt Formulas installation and usage instructions
<http://docs.saltstack.com/topics/conventions/formulas.html>\(ga_.
Available states
================
\&.. contents::
:local:
\(ga\(gafoo\(ga\(ga
\-\-\-\-\-\-\-
Install the \(ga\(gafoo\(ga\(ga package and enable the service.
\(ga\(gafoo.bar\(ga\(ga
\-\-\-\-\-\-\-\-\-\-\-
Install the \(ga\(gabar\(ga\(ga package.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fBCHANGELOG.rst\fP
.sp
The \fBCHANGELOG.rst\fP file should detail the individual versions, their
release date and a set of bullet points for each version highlighting the
overall changes in a given version of the formula.
.sp
A sample skeleton for the \fICHANGELOG.rst\fP file:
.sp
\fBCHANGELOG.rst\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo formula
===========
0.0.2 (2013\-01\-01)
\- Re\-organized formula file layout
\- Fixed filename used for upstart logger template
\- Allow for pillar message to have default if none specified
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Versioning
.sp
Formula are versioned according to Semantic Versioning, \fI\%http://semver.org/\fP\&.
.INDENT 0.0
.INDENT 3.5
Given a version number MAJOR.MINOR.PATCH, increment the:
.INDENT 0.0
.IP 1. 3
MAJOR version when you make incompatible API changes,
.IP 2. 3
MINOR version when you add functionality in a backwards\-compatible manner, and
.IP 3. 3
PATCH version when you make backwards\-compatible bug fixes.
.UNINDENT
.sp
Additional labels for pre\-release and build metadata are available as extensions
to the MAJOR.MINOR.PATCH format.
.UNINDENT
.UNINDENT
.sp
Formula versions are tracked using Git tags as well as the \fBVERSION\fP file
in the formula repository. The \fBVERSION\fP file should contain the currently
released version of the particular formula.
.SS Testing Formulas
.sp
A smoke\-test for invalid Jinja, invalid YAML, or an invalid Salt state
structure can be performed by with the \fBstate.show_sls\fP function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.show_sls apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Salt Formulas can then be tested by running each \fB\&.sls\fP file via
\fBstate.sls\fP and checking the output for the
success or failure of each state in the Formula. This should be done for each
supported platform.
.SS SaltStack Packaging Guide
.sp
Since Salt provides a powerful toolkit for system management and automation,
the package can be spit into a number of sub\-tools. While packaging Salt as
a single package containing all components is perfectly acceptable, the split
packages should follow this convention.
.SS Patching Salt For Distributions
.sp
The occasion may arise where Salt source and default configurations may need
to be patched. It is preferable if Salt is only patched to include platform
specific additions or to fix release time bugs. It is preferable that
configuration settings and operations remain in the default state, as changes
here lowers the user experience for users moving across distributions.
.sp
In the event where a packager finds a need to change the default configuration
it is advised to add the files to the master.d or minion.d directories.
.SS Source Files
.sp
Release packages should always be built from the source tarball distributed via
pypi. Release packages should \fINEVER\fP use a git checkout as the source for
distribution.
.SS Single Package
.sp
Shipping Salt as a single package, where the minion, master and all tools are
together is perfectly acceptable and practiced by distributions such as
FreeBSD.
.SS Split Package
.sp
Salt Should always be split in a standard way, with standard dependencies, this lowers
cross distribution confusion about what components are going to be shipped with
specific packages. These packages can be defined from the Salt Source as of
Salt 2014.1.0:
.SS Salt Common
.sp
The \fIsalt\-common\fP or \fIsalt\fP package should contain the files provided by the
salt python package, or all files distributed from the \fBsalt/\fP directory in
the source distribution packages. The documentation contained under the
\fBdoc/\fP directory can be a part of this package but splitting out a doc
package is preferred.
Since salt\-call is the entry point to utilize the libs and is useful for all
salt packages it is included in the salt\-common package.
.SS Name
.INDENT 0.0
.IP \(bu 2
\fIsalt\fP OR \fIsalt\-common\fP
.UNINDENT
.SS Files
.INDENT 0.0
.IP \(bu 2
\fIsalt/*\fP
.IP \(bu 2
\fIman/salt.7\fP
.IP \(bu 2
\fIscripts/salt\-call\fP
.IP \(bu 2
\fItests/*\fP
.IP \(bu 2
\fIman/salt\-call.1\fP
.UNINDENT
.SS Depends
.INDENT 0.0
.IP \(bu 2
\fIPython 2.6\-2.7\fP
.IP \(bu 2
\fIPyYAML\fP
.IP \(bu 2
\fIJinja2\fP
.UNINDENT
.SS Salt Master
.sp
The \fIsalt\-master\fP package contains the applicable scripts, related man
pages and init information for the given platform.
.SS Name
.INDENT 0.0
.IP \(bu 2
\fIsalt\-master\fP
.UNINDENT
.SS Files
.INDENT 0.0
.IP \(bu 2
\fIscripts/salt\-master\fP
.IP \(bu 2
\fIscripts/salt\fP
.IP \(bu 2
\fIscripts/salt\-run\fP
.IP \(bu 2
\fIscripts/salt\-key\fP
.IP \(bu 2
\fIscripts/salt\-cp\fP
.IP \(bu 2
\fIpkg/<master init data>\fP
.IP \(bu 2
\fIman/salt.1\fP
.IP \(bu 2
\fIman/salt\-master.1\fP
.IP \(bu 2
\fIman/salt\-run.1\fP
.IP \(bu 2
\fIman/salt\-key.1\fP
.IP \(bu 2
\fIman/salt\-cp.1\fP
.IP \(bu 2
\fIconf/master\fP
.UNINDENT
.SS Depends
.INDENT 0.0
.IP \(bu 2
\fISalt Common\fP
.IP \(bu 2
\fIZeroMQ\fP >= 3.2
.IP \(bu 2
\fIPyZMQ\fP >= 2.10
.IP \(bu 2
\fIPyCrypto\fP
.IP \(bu 2
\fIM2Crypto\fP
.IP \(bu 2
\fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure)
.UNINDENT
.SS Salt Syndic
.sp
The Salt Syndic package can be rolled completely into the Salt Master package.
Platforms which start services as part of the package deployment need to
maintain a separate \fIsalt\-syndic\fP package (primarily Debian based platforms).
.sp
The Syndic may optionally not depend on the anything more than the Salt Master since
the master will bring in all needed dependencies, but fall back to the platform
specific packaging guidelines.
.SS Name
.INDENT 0.0
.IP \(bu 2
\fIsalt\-syndic\fP
.UNINDENT
.SS Files
.INDENT 0.0
.IP \(bu 2
\fIscripts/salt\-syndic\fP
.IP \(bu 2
\fIpkg/<syndic init data>\fP
.IP \(bu 2
\fIman/salt\-syndic.1\fP
.UNINDENT
.SS Depends
.INDENT 0.0
.IP \(bu 2
\fISalt Common\fP
.IP \(bu 2
\fISalt Master\fP
.IP \(bu 2
\fIZeroMQ\fP >= 3.2
.IP \(bu 2
\fIPyZMQ\fP >= 2.10
.IP \(bu 2
\fIPyCrypto\fP
.IP \(bu 2
\fIM2Crypto\fP
.IP \(bu 2
\fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure)
.UNINDENT
.SS Salt Minion
.sp
The Minion is a standalone package and should not be split beyond the
\fIsalt\-minion\fP and \fIsalt\-common\fP packages.
.SS Name
.INDENT 0.0
.IP \(bu 2
\fIsalt\-minion\fP
.UNINDENT
.SS Files
.INDENT 0.0
.IP \(bu 2
\fIscripts/salt\-minion\fP
.IP \(bu 2
\fIpkg/<minion init data>\fP
.IP \(bu 2
\fIman/salt\-minion.1\fP
.IP \(bu 2
\fIconf/minion\fP
.UNINDENT
.SS Depends
.INDENT 0.0
.IP \(bu 2
\fISalt Common\fP
.IP \(bu 2
\fIZeroMQ\fP >= 3.2
.IP \(bu 2
\fIPyZMQ\fP >= 2.10
.IP \(bu 2
\fIPyCrypto\fP
.IP \(bu 2
\fIM2Crypto\fP
.IP \(bu 2
\fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure)
.UNINDENT
.SS Salt SSH
.sp
Since Salt SSH does not require the same dependencies as the minion and master, it
should be split out.
.SS Name
.INDENT 0.0
.IP \(bu 2
\fIsalt\-ssh\fP
.UNINDENT
.SS Files
.INDENT 0.0
.IP \(bu 2
\fIscripts/salt\-ssh\fP
.IP \(bu 2
\fIman/salt\-ssh.1\fP
.IP \(bu 2
\fIconf/cloud*\fP
.UNINDENT
.SS Depends
.INDENT 0.0
.IP \(bu 2
\fISalt Common\fP
.IP \(bu 2
\fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure)
.UNINDENT
.SS Salt Cloud
.sp
As of Salt 2014.1.0 Salt Cloud is included in the same repo as Salt. This
can be split out into a separate package or it can be included in the
salt\-master package.
.SS Name
.INDENT 0.0
.IP \(bu 2
\fIsalt\-cloud\fP
.UNINDENT
.SS Files
.INDENT 0.0
.IP \(bu 2
\fIscripts/salt\-cloud\fP
.IP \(bu 2
\fIman/salt\-cloud.1\fP
.UNINDENT
.SS Depends
.INDENT 0.0
.IP \(bu 2
\fISalt Common\fP
.IP \(bu 2
\fIapache libcloud\fP >= 0.14.0
.UNINDENT
.SS Salt Doc
.sp
The documentation package is very distribution optional. A completely split
package will split out the documentation, but some platform conventions do not
prefer this.
If the documentation is not split out, it should be included with the
\fISalt Common\fP package.
.SS Name
.INDENT 0.0
.IP \(bu 2
\fIsalt\-doc\fP
.UNINDENT
.SS Files
.INDENT 0.0
.IP \(bu 2
\fIdoc/*\fP
.UNINDENT
.SS Optional Depends
.INDENT 0.0
.IP \(bu 2
\fISalt Common\fP
.IP \(bu 2
\fIPython Sphinx\fP
.IP \(bu 2
\fIMake\fP
.UNINDENT
.SS Salt Release Process
.sp
The goal for Salt projects is to cut a new feature release every four to six
weeks. This document outlines the process for these releases, and the
subsequent bug fix releases which follow.
.SS Feature Release Process
.sp
When a new release is ready to be cut, the person responsible for cutting the
release will follow the following steps (written using the 0.16 release as an
example):
.INDENT 0.0
.IP 1. 3
All open issues on the release milestone should be moved to the next release
milestone. (e.g. from the \fB0.16\fP milestone to the \fB0.17\fP milestone)
.IP 2. 3
Release notes should be created documenting the major new features and
bugfixes in the release.
.IP 3. 3
Create an annotated tag with only the major and minor version numbers,
preceded by the letter \fBv\fP\&. (e.g. \fBv0.16\fP) This tag will reside on the
\fBdevelop\fP branch.
.IP 4. 3
Create a branch for the new release, using only the major and minor version
numbers. (e.g. \fB0.16\fP)
.IP 5. 3
On this new branch, create an annotated tag for the first revision release,
which is generally a release candidate. It should be preceded by the letter
\fBv\fP\&. (e.g. \fBv0.16.0RC\fP)
.IP 6. 3
The release should be packaged from this annotated tag and uploaded to PyPI
as well as the GitHub releases page for this tag.
.IP 7. 3
The packagers should be notified on the \fI\%salt\-packagers\fP mailing list so
they can create packages for all the major operating systems. (note that
release candidates should go in the testing repositories)
.IP 8. 3
After the packagers have been given a few days to compile the packages, the
release is announced on the \fI\%salt\-users\fP mailing list.
.IP 9. 3
Log into RTD and add the new release there. (Have to do it manually)
.UNINDENT
.SS Maintenance and Bugfix Releases
.sp
Once a release has been cut, regular cherry\-picking sessions should begin to
cherry\-pick any bugfixes from the \fBdevelop\fP branch to the release branch
(e.g. \fB0.16\fP). Once major bugs have been fixes and cherry\-picked, a bugfix
release can be cut:
.INDENT 0.0
.IP 1. 3
On the release branch (i.e. \fB0.16\fP), create an annotated tag for the
revision release. It should be preceded by the letter \fBv\fP\&. (e.g.
\fBv0.16.2\fP) Release candidates are unnecessary for bugfix releases.
.IP 2. 3
The release should be packaged from this annotated tag and uploaded to PyPI.
.IP 3. 3
The packagers should be notified on the \fI\%salt\-packagers\fP mailing list so
they can create packages for all the major operating systems.
.IP 4. 3
After the packagers have been given a few days to compile the packages, the
release is announced on the \fI\%salt\-users\fP mailing list.
.UNINDENT
.SS Cherry\-Picking Process for Bugfixes
.sp
Bugfixes should be made on the \fBdevelop\fP branch. If the bug also applies to
the current release branch, then on the pull request against \fBdevelop\fP, the
user should mention \fB@basepi\fP and ask for the pull request to be
cherry\-picked. If it is verified that the fix is a bugfix, then the
\fBBugfix \-\- Cherry\-Pick\fP label will be applied to the pull request. When
those commits are cherry\-picked, the label will be switched to the
\fBBugfix \-\- [Done] Cherry\-Pick\fP label. This allows easy recognition of which
pull requests have been cherry\-picked, and which are still pending to be
cherry\-picked. All cherry\-picked commits will be present in the next release.
.sp
Features will not be cherry\-picked, and will be present in the next feature
release.
.SS Salt Coding Style
.sp
Salt is developed with a certain coding style, while the style is dominantly
PEP 8 it is not completely PEP 8. It is also noteworthy that a few
development techniques are also employed which should be adhered to. In the
end, the code is made to be "Salty".
.sp
Most importantly though, we will accept code that violates the coding style and
KINDLY ask the contributor to fix it, or go ahead and fix the code on behalf of
the contributor. Coding style is NEVER grounds to reject code contributions,
and is never grounds to talk down to another member of the community (There are
no grounds to treat others without respect, especially people working to
improve Salt)!!
.SS Linting
.sp
Most Salt style conventions are codified in Salt\(aqs \fB\&.pylintrc\fP file. This file
is found in the root of the Salt project and can be passed as an argument to the
\fI\%pylint\fP program as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pylint \-\-rcfile=/path/to/salt/.pylintrc salt/dir/to/lint
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Strings
.sp
Salt follows a few rules when formatting strings:
.SS Single Quotes
.sp
In Salt, all strings use single quotes unless there is a good reason not to.
This means that docstrings use single quotes, standard strings use single
quotes etc.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def foo():
\(aq\(aq\(aq
A function that does things
\(aq\(aq\(aq
name = \(aqA name\(aq
return name
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Formatting Strings
.sp
All strings which require formatting should use the \fI\&.format\fP string method:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
data = \(aqsome text\(aq
more = \(aq{0} and then some\(aq.format(data)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Make sure to use indices or identifiers in the format brackets, since empty
brackets are not supported by python 2.6.
.sp
Please do NOT use printf formatting.
.SS Docstring Conventions
.sp
Docstrings should always add a newline, docutils takes care of the new line and
it makes the code cleaner and more vertical:
.sp
\fIGOOD\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def bar():
\(aq\(aq\(aq
Here lies a docstring with a newline after the quotes and is the salty
way to handle it! Vertical code is the way to go!
\(aq\(aq\(aq
return
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fIBAD\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def baz():
\(aq\(aq\(aqThis is not ok!\(aq\(aq\(aq
return
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When adding a new function or state, where possible try to use a
\fBversionadded\fP directive to denote when the function or state was added.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def new_func(msg=\(aq\(aq):
\(aq\(aq\(aq
.. versionadded:: 0.16.0
Prints what was passed to the function.
msg : None
The string to be printed.
\(aq\(aq\(aq
print msg
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you are uncertain what version should be used, either consult a core
developer in IRC or bring this up when opening your
\fBpull request\fP and a core developer will add the proper
version once your pull request has been merged. Bugfixes will be available in a
bugfix release (i.e. 0.17.1, the first bugfix release for 0.17.0), while new
features are held for feature releases, and this will affect what version
number should be used in the \fBversionadded\fP directive.
.sp
Similar to the above, when an existing function or state is modified (for
example, when an argument is added), then under the explanation of that new
argument a \fBversionadded\fP directive should be used to note the version in
which the new argument was added. If an argument\(aqs function changes
significantly, the \fBversionchanged\fP directive can be used to clarify this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def new_func(msg=\(aq\(aq, signature=\(aq\(aq):
\(aq\(aq\(aq
.. versionadded:: 0.16.0
Prints what was passed to the function.
msg : None
The string to be printed. Will be prepended with \(aqGreetings! \(aq.
.. versionchanged:: 0.17.1
signature : None
An optional signature.
.. versionadded 0.17.0
\(aq\(aq\(aq
print \(aqGreetings! {0}\en\en{1}\(aq.format(msg, signature)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Dictionaries
.sp
Dictionaries should be initialized using \fI{}\fP instead of \fIdict()\fP\&.
.sp
See \fI\%here\fP for an in\-depth discussion of this topic.
.SS Imports
.sp
Salt code prefers importing modules and not explicit functions. This is both a
style and functional preference. The functional preference originates around
the fact that the module import system used by pluggable modules will include
callable objects (functions) that exist in the direct module namespace. This
is not only messy, but may unintentionally expose code python libs to the Salt
interface and pose a security problem.
.sp
To say this more directly with an example, this is \fIGOOD\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import os
def minion_path():
path = os.path.join(self.opts[\(aqcachedir\(aq], \(aqminions\(aq)
return path
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This on the other hand is \fIDISCOURAGED\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from os.path import join
def minion_path():
path = join(self.opts[\(aqcachedir\(aq], \(aqminions\(aq)
return path
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The time when this is changed is for importing exceptions, generally directly
importing exceptions is preferred:
.sp
This is a good way to import exceptions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from salt.exceptions import CommandExecutionError
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Absolute Imports
.sp
Although \fI\%absolute imports\fP seems like an awesome idea, please do not use it.
Extra care would be necessary all over salt\(aqs code in order for absolute
imports to work as supposed. Believe it, it has been tried before and, as a
tried example, by renaming \fBsalt.modules.sysmod\fP to \fBsalt.modules.sys\fP, all
other salt modules which needed to import \fI\%sys\fP would have to
also import \fI\%absolute_import\fP, which should be
avoided.
.SS Vertical is Better
.sp
When writing Salt code, vertical code is generally preferred. This is not a hard
rule but more of a guideline. As PEP 8 specifies, Salt code should not exceed 79
characters on a line, but it is preferred to separate code out into more
newlines in some cases for better readability:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import os
os.chmod(
os.path.join(self.opts[\(aqsock_dir\(aq],
\(aqminion_event_pub.ipc\(aq),
448
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where there are more line breaks, this is also apparent when constructing a
function with many arguments, something very common in state functions for
instance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def managed(name,
source=None,
source_hash=\(aq\(aq,
user=None,
group=None,
mode=None,
template=None,
makedirs=False,
context=None,
replace=True,
defaults=None,
env=None,
backup=\(aq\(aq,
**kwargs):
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Making function and class definitions vertical is only required if the
arguments are longer then 80 characters. Otherwise, the formatting is
optional and both are acceptable.
.UNINDENT
.UNINDENT
.SS Line Length
.sp
For function definitions and function calls, Salt adheres to the PEP\-8
specification of at most 80 characters per line.
.sp
Non function definitions or function calls, please adopt a soft limit of 120
characters per line. If breaking the line reduces the code readability, don\(aqt
break it. Still, try to avoid passing that 120 characters limit and remember,
\fBvertical is better... unless it isn\(aqt\fP
.SS Indenting
.sp
Some confusion exists in the python world about indenting things like function
calls, the above examples use 8 spaces when indenting comma\-delimited
constructs.
.sp
The confusion arises because the pep8 program INCORRECTLY flags this as wrong,
where PEP 8, the document, cites only using 4 spaces here as wrong, as it
doesn\(aqt differentiate from a new indent level.
.sp
Right:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def managed(name,
source=None,
source_hash=\(aq\(aq,
user=None)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
WRONG:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def managed(name,
source=None,
source_hash=\(aq\(aq,
user=None)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lining up the indent is also correct:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def managed(name,
source=None,
source_hash=\(aq\(aq,
user=None)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This also applies to function calls and other hanging indents.
.sp
pep8 and Flake8 (and, by extension, the vim plugin Syntastic) will complain
about the double indent for hanging indents. This is a \fI\%known conflict\fP between
pep8 (the script) and the actual PEP 8 standard. It is recommended that this
particular warning be ignored with the following lines in
\fB~/.config/flake8\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[flake8]
ignore = E226,E241,E242,E126
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Make sure your Flake8/pep8 are up to date. The first three errors are ignored
by default and are present here to keep the behavior the same. This will also
work for pep8 without the Flake8 wrapper \-\- just replace all instances of
\(aqflake8\(aq with \(aqpep8\(aq, including the filename.
.SS Code Churn
.sp
Many pull requests have been submitted that only churn code in the name of
PEP 8. Code churn is a leading source of bugs and is strongly discouraged.
While style fixes are encouraged they should be isolated to a single file per
commit, and the changes should be legitimate, if there are any questions about
whether a style change is legitimate please reference this document and the
official PEP 8 (\fI\%http://legacy.python.org/dev/peps/pep\-0008/\fP) document before
changing code. Many claims that a change is PEP 8 have been invalid, please
double check before committing fixes.
.SH RELEASE NOTES
.sp
See the \fBversion numbers\fP page for more
information about the version numbering scheme.
.SS Latest Stable Release
.SS Salt 2014.7.0 Release Notes \- Codename Helium
.sp
This release is the largest Salt release ever, with more features and commits
then any previous release of Salt. Everything from the new RAET transport to
major updates in Salt Cloud and the merging of Salt API into the main project.
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
The Fedora/RHEL/CentOS \fBsalt\-master\fP package has been modified for this
release. The following components of Salt have been broken out and placed
into their own packages:
.INDENT 0.0
.IP \(bu 2
salt\-syndic
.IP \(bu 2
salt\-cloud
.IP \(bu 2
salt\-ssh
.UNINDENT
.sp
When the \fBsalt\-master\fP package is upgraded, these components will be
removed, and they will need to be manually installed.
.UNINDENT
.UNINDENT
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
Compound/pillar matching have been temporarily disabled for the \fBmine\fP
and \fBpublish\fP modules for this release due to the possibility of
inferring pillar data using pillar glob matching. A proper fix is now in
the 2014.7 branch and scheduled for the 2014.7.1 release, and compound
matching and non\-globbing pillar matching will be re\-enabled at that point.
.sp
Compound and pillar matching for normal salt commands are unaffected.
.UNINDENT
.UNINDENT
.SS New Transport!
.SS RAET Transport Option
.sp
This has been a HUGE amount of work, but the beta release of Salt with RAET is
ready to go. RAET is a reliable queuing transport system that has been
developed in partnership with a number of large enterprises to give Salt an
alternative to ZeroMQ and a way to get Salt to scale well beyond tens of
thousands of servers. Unlike ZeroMQ, RAET is completely asynchronous in every
aspect of its operation and has been developed using the flow programming
paradigm. This allows for many new capabilities to be added to Salt in the
upcoming releases.
.sp
Please keep in mind that this is a beta release of RAET and we hope for bugs to
be worked out, performance to be better realized and more in the Lithium
release.
.sp
Simply stated, users running Salt with RAET should expect some hiccups as we
hammer out the update. This is a BETA release of Salt RAET.
.sp
For information about how to use Salt with RAET please see the
\fBtutorial\fP\&.
.SS Salt SSH Enhancements
.sp
Salt SSH has just entered a new league, with substantial updates and
improvements to make salt\-ssh more reliable and easier then ever! From new
features like the ansible roster and fileserver backends to the new pypi
salt\-ssh installer to lowered deps and a swath of bugfixes, salt\-ssh is
basically reborn!
.SS Install salt\-ssh Using pip
.sp
Salt\-ssh is now pip\-installable!
.sp
\fI\%https://pypi.python.org/pypi/salt\-ssh/\fP
.sp
Pip will bring in all of the required deps, and while some deps are compiled,
they all include pure python implementations, meaning that any compile errors
which may be seen can be safely ignored.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install salt\-ssh
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Fileserver Backends
.sp
Salt\-ssh can now use the salt fileserver backend system. This allows for
the gitfs, hgfs, s3, and many more ways to centrally store states to be easily
used with salt\-ssh. This also allows for a distributed team to easily use
a centralized source.
.SS Saltfile Support
.sp
The new saltfile system makes it easy to have a user specific custom extended
configuration.
.SS Ext Pillar
.sp
Salt\-ssh can now use the external pillar system. Making it easier then ever
to use salt\-ssh with teams.
.SS No More sshpass
.sp
Thanks to the enhancements in the salt vt system, salt\-ssh no longer requires
sshpass to send passwords to ssh. This also makes the manipulation of ssh
calls substantially more flexible, allowing for intercepting ssh calls in
a much more fluid way.
.SS Pure Python Shim
.sp
The salt\-ssh call originally used a shell script to discover what version of
python to execute with and determine the state of the ssh code deployment.
This shell script has been replaced with a pure python version making it easy
to increase the capability of the code deployment without causing platform
inconsistency issues with different shell interpreters.
.SS Custom Module Delivery
.sp
Custom modules are now seamlessly delivered. This makes the deployment of
custom grains, states, execution modules and returners a seamless process.
.SS CP Module Support
.sp
Salt\-ssh now makes simple file transfers easier then ever! The \fIcp\fP
module allows for files to be conveniently sent from the salt fileserver
system down to systems.
.SS More Thin Directory Options
.sp
Salt ssh functions by copying a subset of the salt code, or \fIsalt thin\fP down
to the target system. In the past this was always transferred to /tmp/.salt
and cached there for subsequent commands.
.sp
Now, salt thin can be sent to a random directory and removed when the call
is complete with the \fI\-W\fP option. The new \fI\-W\fP option still uses a static
location but will clean up that location when finished.
.sp
The default \fIsalt thin\fP location is now user defined, allowing multiple users
to cleanly access the same systems.
.SS State System Enhancements
.SS New Imperative State Keyword "Listen"
.sp
The new \fBlisten\fP and \fBlisten_in\fP keywords allow for completely imperative
states by calling the \fBmod_watch()\fP routine after all states have run instead
of re\-ordering the states.
.SS Mod Aggregate Runtime Manipulator
.sp
The new \fBmod_aggregate\fP system allows for the state system to rewrite the
state data during execution. This allows for state definitions to be aggregated
dynamically at runtime.
.sp
The best example is found in the \fBpkg\fP state. If
\fBmod_aggregate\fP is turned on, then when the first pkg state is reached, the
state system will scan all of the other running states for pkg states and take
all other packages set for install and install them all at once in the first
pkg state.
.sp
These runtime modifications make it easy to run groups of states together. In
future versions, we hope to fill out the \fBmod_aggregate\fP system to build in
more and more optimizations.
.sp
For more documentation on \fBmod_aggregate\fP, see \fBthe documentation\fP\&.
.SS New Requisites: onchanges and onfail
.sp
The new \fBonchanges\fP and \fBonchanges_in\fP requisites make a state apply only if
there are changes in the required state. This is useful to execute post hooks
after changes occur on a system.
.sp
The other new requisites, \fBonfail\fP and \fBonfail_in\fP, allow for a state to run
in reaction to the failure of another state.
.sp
For more information about these new requisites, see the
\fBrequisites documentation\fP\&.
.SS Global onlyif and unless
.sp
The \fBonlyif\fP and \fBunless\fP options can now be used for any state declaration.
.SS Use \fBnames\fP to expand and override values
.sp
The \fInames declaration\fP in Salt\(aqs state system can now
override or add values to the expanded data structure. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_users:
user.present:
\- names:
\- larry
\- curly
\- moe:
\- shell: /bin/zsh
\- groups:
\- wheel
\- shell: /bin/bash
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Major Features
.SS Scheduler Additions
.sp
The Salt scheduler system has received MAJOR enhancements, allowing for
cron\-like scheduling and much more granular timing routines. See \fBhere\fP for more info.
.SS Red Hat 7 Family Support
.sp
All the needed additions have been made to run Salt on RHEL 7 and derived OSes
like CentOS and Scientific.
.SS Fileserver Backends in salt\-call
.sp
Fileserver backends like gitfs can now be used without a salt master! Just add
the fileserver backend configuration to the minion config and execute
salt\-call. This has been a much\-requested feature and we are happy to finally
bring it to our users.
.SS Amazon Execution Modules
.sp
An entire family of execution modules further enhancing Salt\(aqs Amazon Cloud
support. They include the following:
.INDENT 0.0
.IP \(bu 2
\fBAutoscale Groups\fP (includes \fBstate support\fP) \-\- related: \fBLaunch Control\fP states
.IP \(bu 2
\fBCloud Watch\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBElastic Cache\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBElastic Load Balancer\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBIAM Identity and Access Management\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBRoute53 DNS\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBSecurity Groups\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBSimple Queue Service\fP (includes \fBstate support\fP)
.UNINDENT
.SS LXC Runner Enhancements
.sp
BETA
The Salt LXC management system has received a number of enhancements which make
running an LXC cloud entirely from Salt an easy proposition.
.SS Next Gen Docker Management
.sp
The Docker support in Salt has been increased at least ten fold. The Docker API
is now completely exposed and Salt ships with Docker data tracking systems
which make automating Docker deployments very easy.
.SS Peer System Performance Improvements
.sp
The peer system communication routines have been refined to make the peer
system substantially faster.
.SS SDB
.sp
Encryption at rest for configs
.SS GPG Renderer
.sp
Encrypted pillar at rest
.SS OpenStack Expansion
.sp
Lots of new OpenStack stuff
.SS Queues System
.sp
Ran change external queue systems into Salt events
.SS Multi Master Failover Additions
.sp
Connecting to multiple masters is more dynamic then ever
.SS Chef Execution Module
.sp
Managing Chef with Salt just got even easier!
.SS salt\-api Project Merge
.sp
The \fBsalt\-api\fP project has been merged into Salt core and is now available as
part of the regular \fBsalt\-master\fP package install. No API changes were made,
the \fBsalt\-api\fP script and init scripts remain intact.
.sp
\fBsalt\-api\fP has always provided Yet Another Pluggable Interface to Salt (TM)
in the form of "netapi" modules. These are modules that bind to a port and
start a service. Like many of Salt\(aqs other module types, netapi modules often
have library and configuration dependencies. See the documentation for each
module for instructions.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIThe full list of netapi modules.\fP
.UNINDENT
.UNINDENT
.SS Synchronous and Asynchronous Execution of Runner and Wheel Modules
.sp
\fBsalt.runner.RunnerClient\fP and \fBsalt.wheel.WheelClient\fP
have both gained complimentary \fBcmd_sync\fP and \fBcmd_async\fP methods allowing
for synchronous and asynchronous execution of any Runner or Wheel module
function, all protected using Salt\(aqs \fIexternal authentication\fP
system. \fBsalt\-api\fP benefits from this addition as well.
.SS \fBrest_cherrypy\fP Additions
.sp
The \fBrest_cherrypy\fP netapi module
provides the main REST API for Salt.
.SS Web Hooks
.sp
This release of course includes the Web Hook additions from the most recent
\fBsalt\-api\fP release, which allows external services to signal actions within a
Salt infrastructure. External services such as Amazon SNS, Travis\-CI, or
GitHub, as well as internal services that cannot or should not run a Salt
minion daemon can be used as first\-class components in Salt\(aqs rich
orchestration capabilities.
.sp
The raw HTTP request body is now available in the event data. This is sometimes
required information for checking an HMAC signature in order to verify a HTTP
request. As an example, Amazon or GitHub requests are signed this way.
.SS Generating and Accepting Minion Keys
.sp
The
.nf
:py:method:\(ga/key <salt.netapi.rest_cherrypy.app.Keys.POST>\(ga
.fi
convenience URL
generates a public and private key for a minion, automatically pre\-accepts the
public key on the Salt Master, and returns both keys as a tarball for download.
.sp
This allows for easily bootstrapping the key on a new minion with a single HTTP
call, such as with a Kickstart script, all using regular shell tools.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-sS http://salt\-api.example.com:8000/keys \e
\-d mid=jerry \e
\-d username=kickstart \e
\-d password=kickstart \e
\-d eauth=pam \e
\-o jerry\-salt\-keys.tar
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Fileserver Backend Enhancements
.sp
All of the fileserver backends have been overhauled to be faster, lighter and
more reliable. The VCS backends (\fBgitfs\fP,
\fBhgfs\fP, and \fBsvnfs\fP)
have also received a \fBlot\fP of new features.
.sp
Additionally, most config parameters for the VCS backends can now be configured
on a per\-remote basis, allowing for global config parameters to be overridden
for a specific gitfs/hgfs/svnfs remote.
.SS New \fBgitfs\fP Features
.SS Pygit2 and Dulwich
.sp
In addition to supporting GitPython, support for \fI\%pygit2\fP (0.20.3 and newer) and
\fI\%dulwich\fP have been added. Provided a compatible version of \fI\%pygit2\fP is
installed, it will now be the default provider. The config parameter
\fBgitfs_provider\fP has been added to allow one to choose a specific
provider for gitfs.
.SS Mountpoints
.sp
Prior to this release, to serve a file from gitfs at a salt fileserver URL of
\fBsalt://foo/bar/baz.txt\fP, it was necessary to ensure that the parent
directories existed in the repository. A new config parameter
\fBgitfs_mountpoint\fP allows gitfs remotes to be exposed starting at
a user\-defined \fBsalt://\fP URL.
.SS Environment Whitelisting/Blacklisting
.sp
By default, gitfs will expose all branches and tags as Salt fileserver
environments. Two new config parameters, \fBgitfs_env_whitelist\fP and
\fBgitfs_env_blacklist\fP, allow more control over which branches and
tags are exposed. More detailed information on how these two options work can
be found in the \fIGitfs Walkthrough\fP\&.
.SS Expanded Authentication Support
.sp
As of \fI\%pygit2\fP 0.20.3, both http(s) and SSH key authentication are supported,
and Salt now also supports both authentication methods when using \fI\%pygit2\fP\&. Keep
in mind that \fI\%pygit2\fP 0.20.3 is not yet available on many platforms, so those
who had been using authenticated git repositories with a passphraseless key
should stick to GitPython if a new enough \fI\%pygit2\fP is not yet available for the
platform on which the master is running.
.sp
A full explanation of how to use authentication can be found in the \fIGitfs
Walkthrough\fP\&.
.SS New \fBhgfs\fP Features
.SS Mountpoints
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameter is called
\fBhgfs_mountpoint\fP\&.
.SS Environment Whitelisting/Blacklisting
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameters are called
\fBhgfs_env_whitelist\fP and \fBhgfs_env_blacklist\fP\&.
.SS New \fBsvnfs\fP Features
.SS Mountpoints
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameter is called
\fBsvnfs_mountpoint\fP\&.
.SS Environment Whitelisting/Blacklisting
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameters are called
\fBsvnfs_env_whitelist\fP and \fBsvnfs_env_blacklist\fP\&.
.SS Configurable Trunk/Branches/Tags Paths
.sp
Prior to this release, the paths where trunk, branches, and tags were located
could only be in directores named "trunk", "branches", and "tags" directly
under the root of the repository. Three new config parameters
(\fBsvnfs_trunk\fP, \fBsvnfs_branches\fP, and
\fBsvnfs_tags\fP) allow SVN repositories which are laid out
differently to be used with svnfs.
.SS New \fBminionfs\fP Features
.SS Mountpoint
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameter is called
\fBminionfs_mountpoint\fP\&. The one major difference is that, as
minionfs doesn\(aqt use multiple remotes (it just serves up files pushed to the
master using \fBcp.push\fP) there is no such thing as a
per\-remote configuration for \fBminionfs_mountpoint\fP\&.
.SS Changing the Saltenv from Which Files are Served
.sp
A new config parameter (\fBminionfs_env\fP) allows minionfs files to
be served from a Salt fileserver environment other than \fBbase\fP\&.
.SS Minion Whitelisting/Blacklisting
.sp
By default, minionfs will expose the pushed files from all minions. Two new
config parameters, \fBminionfs_whitelist\fP and
\fBminionfs_blacklist\fP, allow minionfs to be restricted to serve
files from only the desired minions.
.SS Pyobjects Renderer
.sp
Salt now ships with with the \fBPyobjects Renderer\fP that allows for construction of States using pure
Python with an idiomatic object interface.
.SS New Modules
.sp
In addition to the Amazon modules mentioned above, there are also several other
new execution modules:
.INDENT 0.0
.IP \(bu 2
\fBOracle\fP
.IP \(bu 2
\fBRandom\fP
.IP \(bu 2
\fBRedis\fP
.IP \(bu 2
\fBAmazon Simple Queue Service\fP
.IP \(bu 2
\fBBlock Device Management\fP
.IP \(bu 2
\fBCoreOS etcd\fP
.IP \(bu 2
\fBGenesis\fP
.IP \(bu 2
\fBInfluxDB\fP
.IP \(bu 2
\fBServer Density\fP
.IP \(bu 2
\fBTwilio Notifications\fP
.IP \(bu 2
\fBVarnish\fP
.IP \(bu 2
\fBZNC IRC Bouncer\fP
.IP \(bu 2
\fBSMTP\fP
.UNINDENT
.SS New Runners
.INDENT 0.0
.IP \(bu 2
\fBMap/Reduce Style\fP
.IP \(bu 2
\fBQueue\fP
.UNINDENT
.SS New External Pillars
.INDENT 0.0
.IP \(bu 2
\fBCoreOS etcd\fP
.UNINDENT
.SS New Salt\-Cloud Providers
.INDENT 0.0
.IP \(bu 2
\fBAliyun ECS Cloud\fP
.IP \(bu 2
\fBLXC Containers\fP
.IP \(bu 2
\fBProxmox (OpenVZ containers & KVM)\fP
.UNINDENT
.SS Salt Call Change
.sp
When used with a returner, salt\-call now contacts a master if \fB\-\-local\fP
is not specicified.
.SS Deprecations
.SS \fBsalt.modules.virtualenv_mod\fP
.INDENT 0.0
.IP \(bu 2
Removed deprecated \fBmemoize\fP function from \fBsalt/utils/__init__.py\fP (deprecated)
.IP \(bu 2
Removed deprecated \fBno_site_packages\fP argument from \fBcreate\fP function (deprecated)
.IP \(bu 2
Removed deprecated \fBcheck_dns\fP argument from \fBminion_config\fP and \fBapply_minion_config\fP functions (deprecated)
.IP \(bu 2
Removed deprecated \fBOutputOptionsWithTextMixIn\fP class from \fBsalt/utils/parsers.py\fP (deprecated)
.IP \(bu 2
Removed the following deprecated functions from \fBsalt/modules/ps.py\fP:
\- \fBphysical_memory_usage\fP (deprecated)
\- \fBvirtual_memory_usage\fP (deprecated)
\- \fBcached_physical_memory\fP (deprecated)
\- \fBphysical_memory_buffers\fP (deprecated)
.IP \(bu 2
Removed deprecated cloud arguments from \fBcloud_config\fP function in \fBsalt/config.py\fP:
\- \fBvm_config\fP (deprecated)
\- \fBvm_config_path\fP (deprecated)
.IP \(bu 2
Removed deprecated \fBlibcloud_version\fP function from \fBsalt/cloud/libcloudfuncs.py\fP (deprecated)
.IP \(bu 2
Removed deprecated \fBCloudConfigMixIn\fP class from \fBsalt/utils/parsers.py\fP (deprecated)
.UNINDENT
.SS Previous Releases
.SS Salt 2014.7.0 Release Notes \- Codename Helium
.sp
This release is the largest Salt release ever, with more features and commits
then any previous release of Salt. Everything from the new RAET transport to
major updates in Salt Cloud and the merging of Salt API into the main project.
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
The Fedora/RHEL/CentOS \fBsalt\-master\fP package has been modified for this
release. The following components of Salt have been broken out and placed
into their own packages:
.INDENT 0.0
.IP \(bu 2
salt\-syndic
.IP \(bu 2
salt\-cloud
.IP \(bu 2
salt\-ssh
.UNINDENT
.sp
When the \fBsalt\-master\fP package is upgraded, these components will be
removed, and they will need to be manually installed.
.UNINDENT
.UNINDENT
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
Compound/pillar matching have been temporarily disabled for the \fBmine\fP
and \fBpublish\fP modules for this release due to the possibility of
inferring pillar data using pillar glob matching. A proper fix is now in
the 2014.7 branch and scheduled for the 2014.7.1 release, and compound
matching and non\-globbing pillar matching will be re\-enabled at that point.
.sp
Compound and pillar matching for normal salt commands are unaffected.
.UNINDENT
.UNINDENT
.SS New Transport!
.SS RAET Transport Option
.sp
This has been a HUGE amount of work, but the beta release of Salt with RAET is
ready to go. RAET is a reliable queuing transport system that has been
developed in partnership with a number of large enterprises to give Salt an
alternative to ZeroMQ and a way to get Salt to scale well beyond tens of
thousands of servers. Unlike ZeroMQ, RAET is completely asynchronous in every
aspect of its operation and has been developed using the flow programming
paradigm. This allows for many new capabilities to be added to Salt in the
upcoming releases.
.sp
Please keep in mind that this is a beta release of RAET and we hope for bugs to
be worked out, performance to be better realized and more in the Lithium
release.
.sp
Simply stated, users running Salt with RAET should expect some hiccups as we
hammer out the update. This is a BETA release of Salt RAET.
.sp
For information about how to use Salt with RAET please see the
\fBtutorial\fP\&.
.SS Salt SSH Enhancements
.sp
Salt SSH has just entered a new league, with substantial updates and
improvements to make salt\-ssh more reliable and easier then ever! From new
features like the ansible roster and fileserver backends to the new pypi
salt\-ssh installer to lowered deps and a swath of bugfixes, salt\-ssh is
basically reborn!
.SS Install salt\-ssh Using pip
.sp
Salt\-ssh is now pip\-installable!
.sp
\fI\%https://pypi.python.org/pypi/salt\-ssh/\fP
.sp
Pip will bring in all of the required deps, and while some deps are compiled,
they all include pure python implementations, meaning that any compile errors
which may be seen can be safely ignored.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install salt\-ssh
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Fileserver Backends
.sp
Salt\-ssh can now use the salt fileserver backend system. This allows for
the gitfs, hgfs, s3, and many more ways to centrally store states to be easily
used with salt\-ssh. This also allows for a distributed team to easily use
a centralized source.
.SS Saltfile Support
.sp
The new saltfile system makes it easy to have a user specific custom extended
configuration.
.SS Ext Pillar
.sp
Salt\-ssh can now use the external pillar system. Making it easier then ever
to use salt\-ssh with teams.
.SS No More sshpass
.sp
Thanks to the enhancements in the salt vt system, salt\-ssh no longer requires
sshpass to send passwords to ssh. This also makes the manipulation of ssh
calls substantially more flexible, allowing for intercepting ssh calls in
a much more fluid way.
.SS Pure Python Shim
.sp
The salt\-ssh call originally used a shell script to discover what version of
python to execute with and determine the state of the ssh code deployment.
This shell script has been replaced with a pure python version making it easy
to increase the capability of the code deployment without causing platform
inconsistency issues with different shell interpreters.
.SS Custom Module Delivery
.sp
Custom modules are now seamlessly delivered. This makes the deployment of
custom grains, states, execution modules and returners a seamless process.
.SS CP Module Support
.sp
Salt\-ssh now makes simple file transfers easier then ever! The \fIcp\fP
module allows for files to be conveniently sent from the salt fileserver
system down to systems.
.SS More Thin Directory Options
.sp
Salt ssh functions by copying a subset of the salt code, or \fIsalt thin\fP down
to the target system. In the past this was always transferred to /tmp/.salt
and cached there for subsequent commands.
.sp
Now, salt thin can be sent to a random directory and removed when the call
is complete with the \fI\-W\fP option. The new \fI\-W\fP option still uses a static
location but will clean up that location when finished.
.sp
The default \fIsalt thin\fP location is now user defined, allowing multiple users
to cleanly access the same systems.
.SS State System Enhancements
.SS New Imperative State Keyword "Listen"
.sp
The new \fBlisten\fP and \fBlisten_in\fP keywords allow for completely imperative
states by calling the \fBmod_watch()\fP routine after all states have run instead
of re\-ordering the states.
.SS Mod Aggregate Runtime Manipulator
.sp
The new \fBmod_aggregate\fP system allows for the state system to rewrite the
state data during execution. This allows for state definitions to be aggregated
dynamically at runtime.
.sp
The best example is found in the \fBpkg\fP state. If
\fBmod_aggregate\fP is turned on, then when the first pkg state is reached, the
state system will scan all of the other running states for pkg states and take
all other packages set for install and install them all at once in the first
pkg state.
.sp
These runtime modifications make it easy to run groups of states together. In
future versions, we hope to fill out the \fBmod_aggregate\fP system to build in
more and more optimizations.
.sp
For more documentation on \fBmod_aggregate\fP, see \fBthe documentation\fP\&.
.SS New Requisites: onchanges and onfail
.sp
The new \fBonchanges\fP and \fBonchanges_in\fP requisites make a state apply only if
there are changes in the required state. This is useful to execute post hooks
after changes occur on a system.
.sp
The other new requisites, \fBonfail\fP and \fBonfail_in\fP, allow for a state to run
in reaction to the failure of another state.
.sp
For more information about these new requisites, see the
\fBrequisites documentation\fP\&.
.SS Global onlyif and unless
.sp
The \fBonlyif\fP and \fBunless\fP options can now be used for any state declaration.
.SS Use \fBnames\fP to expand and override values
.sp
The \fInames declaration\fP in Salt\(aqs state system can now
override or add values to the expanded data structure. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_users:
user.present:
\- names:
\- larry
\- curly
\- moe:
\- shell: /bin/zsh
\- groups:
\- wheel
\- shell: /bin/bash
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Major Features
.SS Scheduler Additions
.sp
The Salt scheduler system has received MAJOR enhancements, allowing for
cron\-like scheduling and much more granular timing routines. See \fBhere\fP for more info.
.SS Red Hat 7 Family Support
.sp
All the needed additions have been made to run Salt on RHEL 7 and derived OSes
like CentOS and Scientific.
.SS Fileserver Backends in salt\-call
.sp
Fileserver backends like gitfs can now be used without a salt master! Just add
the fileserver backend configuration to the minion config and execute
salt\-call. This has been a much\-requested feature and we are happy to finally
bring it to our users.
.SS Amazon Execution Modules
.sp
An entire family of execution modules further enhancing Salt\(aqs Amazon Cloud
support. They include the following:
.INDENT 0.0
.IP \(bu 2
\fBAutoscale Groups\fP (includes \fBstate support\fP) \-\- related: \fBLaunch Control\fP states
.IP \(bu 2
\fBCloud Watch\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBElastic Cache\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBElastic Load Balancer\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBIAM Identity and Access Management\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBRoute53 DNS\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBSecurity Groups\fP (includes \fBstate support\fP)
.IP \(bu 2
\fBSimple Queue Service\fP (includes \fBstate support\fP)
.UNINDENT
.SS LXC Runner Enhancements
.sp
BETA
The Salt LXC management system has received a number of enhancements which make
running an LXC cloud entirely from Salt an easy proposition.
.SS Next Gen Docker Management
.sp
The Docker support in Salt has been increased at least ten fold. The Docker API
is now completely exposed and Salt ships with Docker data tracking systems
which make automating Docker deployments very easy.
.SS Peer System Performance Improvements
.sp
The peer system communication routines have been refined to make the peer
system substantially faster.
.SS SDB
.sp
Encryption at rest for configs
.SS GPG Renderer
.sp
Encrypted pillar at rest
.SS OpenStack Expansion
.sp
Lots of new OpenStack stuff
.SS Queues System
.sp
Ran change external queue systems into Salt events
.SS Multi Master Failover Additions
.sp
Connecting to multiple masters is more dynamic then ever
.SS Chef Execution Module
.sp
Managing Chef with Salt just got even easier!
.SS salt\-api Project Merge
.sp
The \fBsalt\-api\fP project has been merged into Salt core and is now available as
part of the regular \fBsalt\-master\fP package install. No API changes were made,
the \fBsalt\-api\fP script and init scripts remain intact.
.sp
\fBsalt\-api\fP has always provided Yet Another Pluggable Interface to Salt (TM)
in the form of "netapi" modules. These are modules that bind to a port and
start a service. Like many of Salt\(aqs other module types, netapi modules often
have library and configuration dependencies. See the documentation for each
module for instructions.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fIThe full list of netapi modules.\fP
.UNINDENT
.UNINDENT
.SS Synchronous and Asynchronous Execution of Runner and Wheel Modules
.sp
\fBsalt.runner.RunnerClient\fP and \fBsalt.wheel.WheelClient\fP
have both gained complimentary \fBcmd_sync\fP and \fBcmd_async\fP methods allowing
for synchronous and asynchronous execution of any Runner or Wheel module
function, all protected using Salt\(aqs \fIexternal authentication\fP
system. \fBsalt\-api\fP benefits from this addition as well.
.SS \fBrest_cherrypy\fP Additions
.sp
The \fBrest_cherrypy\fP netapi module
provides the main REST API for Salt.
.SS Web Hooks
.sp
This release of course includes the Web Hook additions from the most recent
\fBsalt\-api\fP release, which allows external services to signal actions within a
Salt infrastructure. External services such as Amazon SNS, Travis\-CI, or
GitHub, as well as internal services that cannot or should not run a Salt
minion daemon can be used as first\-class components in Salt\(aqs rich
orchestration capabilities.
.sp
The raw HTTP request body is now available in the event data. This is sometimes
required information for checking an HMAC signature in order to verify a HTTP
request. As an example, Amazon or GitHub requests are signed this way.
.SS Generating and Accepting Minion Keys
.sp
The
.nf
:py:method:\(ga/key <salt.netapi.rest_cherrypy.app.Keys.POST>\(ga
.fi
convenience URL
generates a public and private key for a minion, automatically pre\-accepts the
public key on the Salt Master, and returns both keys as a tarball for download.
.sp
This allows for easily bootstrapping the key on a new minion with a single HTTP
call, such as with a Kickstart script, all using regular shell tools.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
curl \-sS http://salt\-api.example.com:8000/keys \e
\-d mid=jerry \e
\-d username=kickstart \e
\-d password=kickstart \e
\-d eauth=pam \e
\-o jerry\-salt\-keys.tar
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Fileserver Backend Enhancements
.sp
All of the fileserver backends have been overhauled to be faster, lighter and
more reliable. The VCS backends (\fBgitfs\fP,
\fBhgfs\fP, and \fBsvnfs\fP)
have also received a \fBlot\fP of new features.
.sp
Additionally, most config parameters for the VCS backends can now be configured
on a per\-remote basis, allowing for global config parameters to be overridden
for a specific gitfs/hgfs/svnfs remote.
.SS New \fBgitfs\fP Features
.SS Pygit2 and Dulwich
.sp
In addition to supporting GitPython, support for \fI\%pygit2\fP (0.20.3 and newer) and
\fI\%dulwich\fP have been added. Provided a compatible version of \fI\%pygit2\fP is
installed, it will now be the default provider. The config parameter
\fBgitfs_provider\fP has been added to allow one to choose a specific
provider for gitfs.
.SS Mountpoints
.sp
Prior to this release, to serve a file from gitfs at a salt fileserver URL of
\fBsalt://foo/bar/baz.txt\fP, it was necessary to ensure that the parent
directories existed in the repository. A new config parameter
\fBgitfs_mountpoint\fP allows gitfs remotes to be exposed starting at
a user\-defined \fBsalt://\fP URL.
.SS Environment Whitelisting/Blacklisting
.sp
By default, gitfs will expose all branches and tags as Salt fileserver
environments. Two new config parameters, \fBgitfs_env_whitelist\fP and
\fBgitfs_env_blacklist\fP, allow more control over which branches and
tags are exposed. More detailed information on how these two options work can
be found in the \fIGitfs Walkthrough\fP\&.
.SS Expanded Authentication Support
.sp
As of \fI\%pygit2\fP 0.20.3, both http(s) and SSH key authentication are supported,
and Salt now also supports both authentication methods when using \fI\%pygit2\fP\&. Keep
in mind that \fI\%pygit2\fP 0.20.3 is not yet available on many platforms, so those
who had been using authenticated git repositories with a passphraseless key
should stick to GitPython if a new enough \fI\%pygit2\fP is not yet available for the
platform on which the master is running.
.sp
A full explanation of how to use authentication can be found in the \fIGitfs
Walkthrough\fP\&.
.SS New \fBhgfs\fP Features
.SS Mountpoints
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameter is called
\fBhgfs_mountpoint\fP\&.
.SS Environment Whitelisting/Blacklisting
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameters are called
\fBhgfs_env_whitelist\fP and \fBhgfs_env_blacklist\fP\&.
.SS New \fBsvnfs\fP Features
.SS Mountpoints
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameter is called
\fBsvnfs_mountpoint\fP\&.
.SS Environment Whitelisting/Blacklisting
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameters are called
\fBsvnfs_env_whitelist\fP and \fBsvnfs_env_blacklist\fP\&.
.SS Configurable Trunk/Branches/Tags Paths
.sp
Prior to this release, the paths where trunk, branches, and tags were located
could only be in directores named "trunk", "branches", and "tags" directly
under the root of the repository. Three new config parameters
(\fBsvnfs_trunk\fP, \fBsvnfs_branches\fP, and
\fBsvnfs_tags\fP) allow SVN repositories which are laid out
differently to be used with svnfs.
.SS New \fBminionfs\fP Features
.SS Mountpoint
.sp
This feature works exactly like its \fI\%gitfs counterpart\fP\&. The new config parameter is called
\fBminionfs_mountpoint\fP\&. The one major difference is that, as
minionfs doesn\(aqt use multiple remotes (it just serves up files pushed to the
master using \fBcp.push\fP) there is no such thing as a
per\-remote configuration for \fBminionfs_mountpoint\fP\&.
.SS Changing the Saltenv from Which Files are Served
.sp
A new config parameter (\fBminionfs_env\fP) allows minionfs files to
be served from a Salt fileserver environment other than \fBbase\fP\&.
.SS Minion Whitelisting/Blacklisting
.sp
By default, minionfs will expose the pushed files from all minions. Two new
config parameters, \fBminionfs_whitelist\fP and
\fBminionfs_blacklist\fP, allow minionfs to be restricted to serve
files from only the desired minions.
.SS Pyobjects Renderer
.sp
Salt now ships with with the \fBPyobjects Renderer\fP that allows for construction of States using pure
Python with an idiomatic object interface.
.SS New Modules
.sp
In addition to the Amazon modules mentioned above, there are also several other
new execution modules:
.INDENT 0.0
.IP \(bu 2
\fBOracle\fP
.IP \(bu 2
\fBRandom\fP
.IP \(bu 2
\fBRedis\fP
.IP \(bu 2
\fBAmazon Simple Queue Service\fP
.IP \(bu 2
\fBBlock Device Management\fP
.IP \(bu 2
\fBCoreOS etcd\fP
.IP \(bu 2
\fBGenesis\fP
.IP \(bu 2
\fBInfluxDB\fP
.IP \(bu 2
\fBServer Density\fP
.IP \(bu 2
\fBTwilio Notifications\fP
.IP \(bu 2
\fBVarnish\fP
.IP \(bu 2
\fBZNC IRC Bouncer\fP
.IP \(bu 2
\fBSMTP\fP
.UNINDENT
.SS New Runners
.INDENT 0.0
.IP \(bu 2
\fBMap/Reduce Style\fP
.IP \(bu 2
\fBQueue\fP
.UNINDENT
.SS New External Pillars
.INDENT 0.0
.IP \(bu 2
\fBCoreOS etcd\fP
.UNINDENT
.SS New Salt\-Cloud Providers
.INDENT 0.0
.IP \(bu 2
\fBAliyun ECS Cloud\fP
.IP \(bu 2
\fBLXC Containers\fP
.IP \(bu 2
\fBProxmox (OpenVZ containers & KVM)\fP
.UNINDENT
.SS Salt Call Change
.sp
When used with a returner, salt\-call now contacts a master if \fB\-\-local\fP
is not specicified.
.SS Deprecations
.SS \fBsalt.modules.virtualenv_mod\fP
.INDENT 0.0
.IP \(bu 2
Removed deprecated \fBmemoize\fP function from \fBsalt/utils/__init__.py\fP (deprecated)
.IP \(bu 2
Removed deprecated \fBno_site_packages\fP argument from \fBcreate\fP function (deprecated)
.IP \(bu 2
Removed deprecated \fBcheck_dns\fP argument from \fBminion_config\fP and \fBapply_minion_config\fP functions (deprecated)
.IP \(bu 2
Removed deprecated \fBOutputOptionsWithTextMixIn\fP class from \fBsalt/utils/parsers.py\fP (deprecated)
.IP \(bu 2
Removed the following deprecated functions from \fBsalt/modules/ps.py\fP:
\- \fBphysical_memory_usage\fP (deprecated)
\- \fBvirtual_memory_usage\fP (deprecated)
\- \fBcached_physical_memory\fP (deprecated)
\- \fBphysical_memory_buffers\fP (deprecated)
.IP \(bu 2
Removed deprecated cloud arguments from \fBcloud_config\fP function in \fBsalt/config.py\fP:
\- \fBvm_config\fP (deprecated)
\- \fBvm_config_path\fP (deprecated)
.IP \(bu 2
Removed deprecated \fBlibcloud_version\fP function from \fBsalt/cloud/libcloudfuncs.py\fP (deprecated)
.IP \(bu 2
Removed deprecated \fBCloudConfigMixIn\fP class from \fBsalt/utils/parsers.py\fP (deprecated)
.UNINDENT
.SS Salt 2014.1.0 Release Notes \- Codename Hydrogen
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Due to a change in master to minion communication, 2014.1.0 minions are not
compatible with older\-version masters. Please upgrade masters first.
More info on backwards\-compatibility policy \fBhere\fP, under the "Upgrading Salt" subheading.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
A change in the grammar in the state compiler makes \fBmodule.run\fP in
requisites illegal syntax. Its use is replaced simply with the word
\fBmodule\fP\&. In other words you will need to change requisites like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
require:
module.run: some_module_name
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
require:
module: some_module_name
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is a breaking change. We apologize for the inconvenience, we needed to
do this to remove some ambiguity in parsing requisites.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B release
2014\-02\-24
.UNINDENT
.sp
The 2014.1.0 release of Salt is a major release which not only increases
stability but also brings new capabilities in virtualization, cloud
integration, and more. This release brings a great focus on the expansion of
testing making roughly double the coverage in the Salt tests, and comes with
many new features.
.sp
2014.1.0 is the first release to follow the new date\-based release naming
system. See the \fBversion numbers\fP
page for more details.
.SS Major Features
.SS Salt Cloud Merged into Salt
.sp
Salt Cloud is a tool for provisioning salted minions across various cloud
providers. Prior to this release, Salt Cloud was a separate project but this
marks its full integration with the Salt distribution. A Getting Started guide
and additional documentation for Salt Cloud can be found \fBhere\fP:
.SS Google Compute Engine
.sp
Alongside Salt Cloud comes new support for the Google Compute Engine. Salt Stack
can now deploy and control GCE virtual machines and the application stacks that
they run.
.sp
For more information on Salt Stack and GCE, please see \fI\%this blog post\fP\&.
.sp
Documentation for Salt and GCE can be found \fBhere\fP\&.
.SS Salt Virt
.sp
Salt Virt is a cloud controller that supports virtual machine deployment,
inspection, migration and integration with many aspects of Salt.
.sp
Salt Virt has undergone a major overhaul with this release and now supports
many more features and includes a number of critical improvements.
.SS Docker Integration
.sp
Salt now ships with \fBstates\fP and an \fBexecution
module\fP to manage Docker containers.
.SS Substantial Testing Expansion
.sp
Salt continues to increase its unit/regression test coverage. This release
includes over 300 new tests.
.SS BSD Package Management
.sp
BSD package management has been entirely rewritten. FreeBSD 9 and older now
default to using pkg_add, while FreeBSD 10 and newer will use pkgng. FreeBSD 9
can be forced to use pkgng, however, by specifying the following option in the
minion config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
providers:
pkg: pkgng
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In addition, support for installing software from the ports tree has been
added. See the documentation for the ports \fBstate\fP and
\fBexecution module\fP for more information.
.SS Network Management for Debian/Ubuntu
.sp
Initial support for management of network interfaces on Debian\-based distros
has been added. See the documentation for the \fBnetwork state\fP and the \fBdebian_ip\fP for
more information.
.SS IPv6 Support for iptables State/Module
.sp
The iptables \fBstate\fP and \fBmodule\fP now have IPv6 support. A new parameter \fBfamily\fP has
been added to the states and execution functions, to distinguish between IPv4
and IPv6. The default value for this parameter is \fBipv4\fP, specifying \fBipv6\fP
will use ip6tables to manage firewall rules.
.SS GitFS Improvements
.sp
Several performance improvements have been made to the \fBGit fileserver
backend\fP\&. Additionally, file states can now use any
any SHA1 commit hash as a fileserver environment:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/httpd/httpd.conf:
file.managed:
\- source: salt://webserver/files/httpd.conf
\- saltenv: 45af879
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This applies to the functions in the \fBcp module\fP as
well:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cp.get_file salt://readme.txt /tmp/readme.txt saltenv=45af879
.ft P
.fi
.UNINDENT
.UNINDENT
.SS MinionFS
.sp
This new fileserver backend allows files which have been pushed from the minion
to the master (using \fBcp.push\fP) to be served up
from the salt fileserver. The path for these files takes the following format:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt://minion\-id/path/to/file
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBminion\-id\fP is the id of the "source" minion, the one from which the files
were pushed to the master. \fB/path/to/file\fP is the full path of the file.
.sp
The \fBMinionFS Walkthrough\fP contains a more
thorough example of how to use this backend.
.SS saltenv
.sp
To distinguish between fileserver environments and execution functions which
deal with environment variables, fileserver environments are now specified
using the \fBsaltenv\fP parameter. \fBenv\fP will continue to work, but is
deprecated and will be removed in a future release.
.SS Grains Caching
.sp
A caching layer has been added to the Grains system, which can help speed up
minion startup. Disabled by default, it can be enabled by setting the minion
config option \fBgrains_cache\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
grains_cache: True
# Seconds before grains cache is considered to be stale.
grains_cache_expiration: 300
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If set to \fBTrue\fP, the grains loader will read from/write to a
msgpack\-serialized file containing the grains data.
.sp
Additional command\-line parameters have been added to salt\-call, mainly for
testing purposes:
.INDENT 0.0
.IP \(bu 2
\fB\-\-skip\-grains\fP will completely bypass the grains loader when salt\-call is
invoked.
.IP \(bu 2
\fB\-\-refresh\-grains\-cache\fP will force the grains loader to bypass the grains
cache and refresh the grains, writing a new grains cache file.
.UNINDENT
.SS Improved Command Logging Control
.sp
When using the \fBcmd module\fP, either on the CLI or
when developing Salt execution modules, a new keyword argument
\fBoutput_loglevel\fP allows for greater control over how (or even if) the
command and its output are logged. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq cmd.run \(aqtail /var/log/messages\(aq output_loglevel=debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The package management modules (\fBapt\fP, \fByumpkg\fP, etc.) have been updated to
log the copious output generated from these commands at loglevel \fBdebug\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
To keep a command from being logged, \fBoutput_loglevel=quiet\fP can be used.
.sp
Prior to this release, this could be done using \fBquiet=True\fP\&. This
argument is still supported, but will be removed in a future Salt release.
.UNINDENT
.UNINDENT
.SS PagerDuty Support
.sp
Initial support for firing events via \fI\%PagerDuty\fP has been added. See the
documentation for the \fBpagerduty\fP module.
.SS Virtual Terminal
.sp
Sometimes the subprocess module is not good enough, and, in fact, not even
\fBaskpass\fP is. This virtual terminal is still in it\(aqs infant childhood, needs
quite some love, and was originally created to replace \fBaskpass\fP, but, while
developing it, it immediately proved that it could do so much more. It\(aqs
currently used by salt\-cloud when bootstrapping salt on clouds which require
the use of a password.
.SS Proxy Minions
.sp
Initial basic support for Proxy Minions is in this release. Documentation can
be found \fBhere\fP\&.
.sp
Proxy minions are a developing feature in Salt that enables control of devices
that cannot run a minion. Examples include network gear like switches and
routers that run a proprietary OS but offer an API, or "dumb" devices that just
don\(aqt have the horsepower or ability to handle a Python VM.
.sp
Proxy minions can be difficult to write, so a simple REST\-based example proxy
is included. A Python bottle\-based webserver can be found at
\fI\%https://github.com/cro/salt\-proxy\-rest\fP as an endpoint for this proxy.
.sp
This is an ALPHA\-quality feature. There are a number of issues with it
currently, mostly centering around process control, logging, and inability to
work in a masterless configuration.
.SS Additional Bugfixes (Release Candidate Period)
.sp
Below are many of the fixes that were implemented in salt during the release
candidate phase.
.INDENT 0.0
.IP \(bu 2
Fix mount.mounted leaving conflicting entries in fstab (\fI\%issue 7079\fP)
.IP \(bu 2
Fix mysql returner serialization to use json (\fI\%issue 9590\fP)
.IP \(bu 2
Fix \fBZMQError: Operation cannot be accomplished in current state\fP errors (\fI\%issue 6306\fP)
.IP \(bu 2
Rbenv and ruby improvements
.IP \(bu 2
Fix quoting issues with mysql port (\fI\%issue 9568\fP)
.IP \(bu 2
Update mount module/state to support multiple swap partitions (\fI\%issue 9520\fP)
.IP \(bu 2
Fix \fBarchive\fP state to work with \fBbsdtar\fP
.IP \(bu 2
Clarify logs for minion ID caching
.IP \(bu 2
Add numeric revision support to git state (\fI\%issue 9718\fP)
.IP \(bu 2
Update \fBmaster_uri\fP with \fBmaster_ip\fP (\fI\%issue 9694\fP)
.IP \(bu 2
Add comment to Debian \fBmod_repo\fP (\fI\%issue 9923\fP)
.IP \(bu 2
Fix potential undefined loop variable in rabbitmq state (\fI\%issue 8703\fP)
.IP \(bu 2
Fix for salt\-virt runner to delete key on VM deletion
.IP \(bu 2
Fix for \fBsalt\-run \-d\fP to limit results to specific runner or function (\fI\%issue 9975\fP)
.IP \(bu 2
Add tracebacks to jinja renderer when applicable (\fI\%issue 10010\fP)
.IP \(bu 2
Fix parsing in monit module (\fI\%issue 10041\fP)
.IP \(bu 2
Fix highstate output from syndic minions (\fI\%issue 9732\fP)
.IP \(bu 2
Quiet logging when dealing with passwords/hashes (\fI\%issue 10000\fP)
.IP \(bu 2
Fix for multiple remotes in git_pillar (\fI\%issue 9932\fP)
.IP \(bu 2
Fix npm installed command (\fI\%issue 10109\fP)
.IP \(bu 2
Add safeguards for utf8 errors in zcbuildout module
.IP \(bu 2
Fix compound commands (\fI\%issue 9746\fP)
.IP \(bu 2
Add systemd notification when master is started
.IP \(bu 2
Many doc improvements
.UNINDENT
.SS Salt 2014.1.1 Release Notes
.INDENT 0.0
.TP
.B release
2014\-03\-18
.UNINDENT
.sp
Version 2014.1.1 is a bugfix release for \fB2014.1.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Various doc fixes, including up\-to\-date Salt Cloud installation documentation.
.IP \(bu 2
Renamed state.sls runner to state.orchestrate, to reduce confusion with the \fBstate.sls\fP execution function
.IP \(bu 2
Fix various bugs in the \fBdig\fP module (\fI\%issue 10367\fP)
.IP \(bu 2
Add retry for query on certain EC2 status codes (\fI\%issue 10154\fP)
.IP \(bu 2
Fix various bugs in mongodb_user state module (\fI\%issue 10430\fP)
.IP \(bu 2
Fix permissions on \fB~/.salt_token\fP (\fI\%issue 10422\fP)
.IP \(bu 2
Add PyObjects support
.IP \(bu 2
Fix launchctl module crash with missing files
.IP \(bu 2
Fix \fBsaltutil.find_job\fP for Windows (\fI\%issue 10581\fP)
.IP \(bu 2
Fix OS detection for OpenSolaris (\fI\%issue 10601\fP)
.IP \(bu 2
Fix broken salt\-ssh key_deploy
.IP \(bu 2
Add support for multiline cron comments (\fI\%issue 10721\fP)
.IP \(bu 2
Fix timezone module for Arch (\fI\%issue 10789\fP)
.IP \(bu 2
Fix symlink support for \fBfile.recurse\fP (\fI\%issue 10809\fP)
.IP \(bu 2
Fix multi\-master bugs (\fI\%issue 10732\fP and \fI\%issue 10969\fP)
.IP \(bu 2
Fix file.patch to error when source file is unavailable (\fI\%issue 10380\fP)
.IP \(bu 2
Fix pkg to handle packages set as \fBpurge\fP in \fBpkg.installed\fP (\fI\%issue 10719\fP)
.IP \(bu 2
Add \fBzmqversion\fP grain
.IP \(bu 2
Fix highstate summary for masterless minions (\fI\%issue 10945\fP)
.IP \(bu 2
Fix \fBsaltutil.find_job\fP for 2014.1 masters talking to 0.17 minions (\fI\%issue 11020\fP)
.IP \(bu 2
Fix \fBfile.recurse\fP states with trailing slashes in source (\fI\%issue 11002\fP)
.IP \(bu 2
Fix \fBpkg states\fP to allow \fBpkgname.x86_64\fP (\fI\%issue 7306\fP)
.IP \(bu 2
Make \fBiptables states\fP set a default table for flush (\fI\%issue 11037\fP)
.IP \(bu 2
Added iptables \fB\-\-reject\-with\fP after final iptables call in \fBiptables states\fP (issue:\fI10757\fP)
.IP \(bu 2
Fix improper passing of “family” in \fBiptables states\fP (\fI\%issue 10774\fP)
.IP \(bu 2
Fix traceback in \fBiptables.insert\fP states (\fI\%issue 10988\fP)
.IP \(bu 2
Fix zombie processes (\fI\%issue 10867\fP and others)
.IP \(bu 2
Fix batch mode to obey \fB\-\-return\fP settings (\fI\%issue 9146\fP)
.IP \(bu 2
Fix localclient issue that was causing batch mode breakage (\fI\%issue 11094\fP, \fI\%issue 10470\fP, and others)
.IP \(bu 2
Multiple salt\-ssh fixes
.IP \(bu 2
FreeBSD: look in /usr/local/etc/salt for configuration by default, if installed using \fBpip \-\-editable\fP\&.
.IP \(bu 2
Add a \fBskip_suggestions\fP parameter to pkg.installed states which allows pre\-flight check to be skipped (\fI\%issue 11106\fP)
.IP \(bu 2
Fixed tag\-based gitfs fileserver environments regression (\fI\%issue 10956\fP)
.IP \(bu 2
Yum: fix cache of available pkgs not cleared when repos are changed (\fI\%issue 11001\fP)
.IP \(bu 2
Yum: fix for plugin\-provided repositories (i.e. RHN/Spacewalk) (\fI\%issue 11145\fP)
.IP \(bu 2
Fix regression in \fBchocolatey.bootstrap\fP (\fI\%issue 10541\fP)
.IP \(bu 2
Fix fail on unknown target in \fBjobs runner\fP (\fI\%issue 11151\fP)
.IP \(bu 2
Don’t log errors for commands which are expected to sometimes exit with non\-zero exit status (\fI\%issue 11154\fP, \fI\%issue 11090\fP)
.IP \(bu 2
Fix \fBtest=True\fP CLI override of config option (\fI\%issue 10877\fP)
.IP \(bu 2
Log sysctl key listing at loglevel TRACE (\fI\%issue 10931\fP)
.UNINDENT
.SS Salt 2014.1.10 Release Notes
.INDENT 0.0
.TP
.B release
2014\-08\-01
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Version 2014.1.9 contained a regression which caused inaccurate Salt version
detection, and thus was never packaged for general release. This version
contains the version detection fix, but is otherwise identical to 2014.1.9.
.UNINDENT
.UNINDENT
.sp
Version 2014.1.10 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Ensure salt\-ssh will not continue if permissions on a temporary directory are
not correct.
.IP \(bu 2
Use the bootstrap script distributed with Salt instead of relying on an
external resource
.IP \(bu 2
Remove unused testing code
.IP \(bu 2
Ensure salt states are placed into the \fB\&.salt\fP directory in salt\-ssh
.IP \(bu 2
Use a randomized path for temporary files in a salt\-cloud deployment
.IP \(bu 2
Clean any stale directories to ensure a fresh copy of salt\-ssh during a
deployment
.UNINDENT
.sp
Salt 2014.1.10 fixes security issues documented by CVE\-2014\-3563: "Insecure
tmp\-file creation in seed.py, salt\-ssh, and salt\-cloud." Upgrading is
recommended.
.SS Salt 2014.1.11 Release Notes
.INDENT 0.0
.TP
.B release
2014\-08\-29
.UNINDENT
.sp
Version 2014.1.11 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Fix for minion_id with byte\-order mark (BOM) (\fI\%issue 12296\fP)
.IP \(bu 2
Fix \fBrunas\fP deprecation in \fBat\fP module
.IP \(bu 2
Fix trailing slash befhavior for \fBfile.makedirs_\fP (\fI\%issue 14019\fP)
.IP \(bu 2
Fix chocolatey path (\fI\%issue 13870\fP)
.IP \(bu 2
Fix git_pillar infinite loop issues (\fI\%issue 14671\fP)
.IP \(bu 2
Fix json outputter \fBnull\fP case
.IP \(bu 2
Fix for minion error if one of multiple masters are down (\fI\%issue 14099\fP)
.UNINDENT
.SS Salt 2014.1.12 Release Notes
.INDENT 0.0
.TP
.B release
2014\-10\-08
.UNINDENT
.sp
Version 2014.1.12 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Fix \fBscp_file\fP always failing (which broke salt\-cloud) (\fI\%issue 16437\fP)
.IP \(bu 2
Fix regression in pillar in masterless (\fI\%issue 16210\fP, \fI\%issue 16416\fP,
\fI\%issue 16428\fP)
.UNINDENT
.SS Salt 2014.1.13 Release Notes
.INDENT 0.0
.TP
.B release
2014\-10\-14
.UNINDENT
.sp
Version 2014.1.13 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Fix \fBsftp_file\fP by checking the exit status code of scp (which broke salt\-cloud) (\fI\%issue 16599\fP)
.UNINDENT
.SS Salt 2014.1.2 Release Notes
.INDENT 0.0
.TP
.B release
2014\-04\-15
.UNINDENT
.sp
Version 2014.1.2 is another bugfix release for \fB2014.1.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Fix username detection when su\(aqed to root on FreeBSD (\fI\%issue 11628\fP)
.IP \(bu 2
Fix minionfs backend for file.recurse states
.IP \(bu 2
Fix 32\-bit packages of different arches than the CPU arch, on 32\-bit
RHEL/CentOS (\fI\%issue 11822\fP)
.IP \(bu 2
Fix bug with specifying alternate home dir on user creation (FreeBSD)
(\fI\%issue 11790\fP)
.IP \(bu 2
Don’t reload \fBsite\fP module on module refresh for MacOS
.IP \(bu 2
Fix regression with running execution functions in Pillar SLS
(\fI\%issue 11453\fP)
.IP \(bu 2
Fix some modules missing from Windows installer
.IP \(bu 2
Don’t log an error for yum commands that return nonzero exit status on
non\-failure (\fI\%issue 11645\fP)
.IP \(bu 2
Fix bug in rabbitmq state (\fI\%issue 8703\fP)
.IP \(bu 2
Fix missing ssh config options (\fI\%issue 10604\fP)
.IP \(bu 2
Fix top.sls ordering (\fI\%issue 10810\fP and \fI\%issue 11691\fP)
.IP \(bu 2
Fix \fBsalt\-key \-\-list all\fP (\fI\%issue 10982\fP)
.IP \(bu 2
Fix win_servermanager install/remove function (\fI\%issue 11038\fP)
.IP \(bu 2
Fix interaction with tokens when running commands as root (\fI\%issue 11223\fP)
.IP \(bu 2
Fix overstate bug with \fBfind_job\fP and \fB**kwargs\fP (\fI\%issue 10503\fP)
.IP \(bu 2
Fix \fBsaltenv\fP for \fBaptpkg.mod_repo\fP from \fBpkgrepo\fP state
.IP \(bu 2
Fix environment issue causing file caching problems (\fI\%issue 11189\fP)
.IP \(bu 2
Fix bug in \fB__parse_key\fP in registry state (\fI\%issue 11408\fP)
.IP \(bu 2
Add minion auth retry on rejection (\fI\%issue 10763\fP)
.IP \(bu 2
Fix publish_session updating the encryption key (\fI\%issue 11493\fP)
.IP \(bu 2
Fix for bad \fBAssertionError\fP raised by GitPython (\fI\%issue 11473\fP)
.IP \(bu 2
Fix \fBdebian_ip\fP to allow disabling and enabling networking on Ubuntu (\fI\%issue 11164\fP)
.IP \(bu 2
Fix potential memory leak caused by saved (and unused) events (\fI\%issue 11582\fP)
.IP \(bu 2
Fix exception handling in the MySQL module (\fI\%issue 11616\fP)
.IP \(bu 2
Fix environment\-related error (\fI\%issue 11534\fP)
.IP \(bu 2
Include \fBpsutil\fP on Windows
.IP \(bu 2
Add \fBfile.replace\fP and \fBfile.search\fP to Windows (\fI\%issue 11471\fP)
.IP \(bu 2
Add additional \fBfile\fP module helpers to Windows (\fI\%issue 11235\fP)
.IP \(bu 2
Add \fBpid\fP to netstat output on Windows (\fI\%issue 10782\fP)
.IP \(bu 2
Fix Windows not caching new versions of installers in winrepo (\fI\%issue 10597\fP)
.IP \(bu 2
Fix hardcoded md5 hashing
.IP \(bu 2
Fix kwargs in salt\-ssh (\fI\%issue 11609\fP)
.IP \(bu 2
Fix file backup timestamps (\fI\%issue 11745\fP)
.IP \(bu 2
Fix stacktrace on \fBsys.doc\fP with invalid eauth (\fI\%issue 11293\fP)
.IP \(bu 2
Fix \fBgit.latest\fP with \fBtest=True\fP (\fI\%issue 11595\fP)
.IP \(bu 2
Fix \fBfile.check_perms\fP hardcoded \fBfollow_symlinks\fP (\fI\%issue 11387\fP)
.IP \(bu 2
Fix certain \fBpkg\fP states for RHEL5/Cent5 machines (\fI\%issue 11719\fP)
.UNINDENT
.SS Salt 2014.1.3 Release Notes
.INDENT 0.0
.TP
.B release
2014\-04\-15
.UNINDENT
.sp
Version 2014.1.3 is another bugfix release for \fB2014.1.0\fP\&. It was created as a hotfix for a regression
found in 2014.1.2, which was not distributed. The only change made was as
follows:
.INDENT 0.0
.IP \(bu 2
Fix regression that caused \fBsaltutil.find_job\fP to fail, causing premature
terminations of salt CLI commands.
.UNINDENT
.sp
Changes in the not\-distributed 2014.1.2, also included in 2014.1.3:
.INDENT 0.0
.IP \(bu 2
Fix username detection when su\(aqed to root on FreeBSD (\fI\%issue 11628\fP)
.IP \(bu 2
Fix minionfs backend for file.recurse states
.IP \(bu 2
Fix 32\-bit packages of different arches than the CPU arch, on 32\-bit
RHEL/CentOS (\fI\%issue 11822\fP)
.IP \(bu 2
Fix bug with specifying alternate home dir on user creation (FreeBSD)
(\fI\%issue 11790\fP)
.IP \(bu 2
Don’t reload \fBsite\fP module on module refresh for MacOS
.IP \(bu 2
Fix regression with running execution functions in Pillar SLS
(\fI\%issue 11453\fP)
.IP \(bu 2
Fix some modules missing from Windows installer
.IP \(bu 2
Don’t log an error for yum commands that return nonzero exit status on
non\-failure (\fI\%issue 11645\fP)
.IP \(bu 2
Fix bug in rabbitmq state (\fI\%issue 8703\fP)
.IP \(bu 2
Fix missing ssh config options (\fI\%issue 10604\fP)
.IP \(bu 2
Fix top.sls ordering (\fI\%issue 10810\fP and \fI\%issue 11691\fP)
.IP \(bu 2
Fix \fBsalt\-key \-\-list all\fP (\fI\%issue 10982\fP)
.IP \(bu 2
Fix win_servermanager install/remove function (\fI\%issue 11038\fP)
.IP \(bu 2
Fix interaction with tokens when running commands as root (\fI\%issue 11223\fP)
.IP \(bu 2
Fix overstate bug with \fBfind_job\fP and \fB**kwargs\fP (\fI\%issue 10503\fP)
.IP \(bu 2
Fix \fBsaltenv\fP for \fBaptpkg.mod_repo\fP from \fBpkgrepo\fP state
.IP \(bu 2
Fix environment issue causing file caching problems (\fI\%issue 11189\fP)
.IP \(bu 2
Fix bug in \fB__parse_key\fP in registry state (\fI\%issue 11408\fP)
.IP \(bu 2
Add minion auth retry on rejection (\fI\%issue 10763\fP)
.IP \(bu 2
Fix publish_session updating the encryption key (\fI\%issue 11493\fP)
.IP \(bu 2
Fix for bad \fBAssertionError\fP raised by GitPython (\fI\%issue 11473\fP)
.IP \(bu 2
Fix \fBdebian_ip\fP to allow disabling and enabling networking on Ubuntu (\fI\%issue 11164\fP)
.IP \(bu 2
Fix potential memory leak caused by saved (and unused) events (\fI\%issue 11582\fP)
.IP \(bu 2
Fix exception handling in the MySQL module (\fI\%issue 11616\fP)
.IP \(bu 2
Fix environment\-related error (\fI\%issue 11534\fP)
.IP \(bu 2
Include \fBpsutil\fP on Windows
.IP \(bu 2
Add \fBfile.replace\fP and \fBfile.search\fP to Windows (\fI\%issue 11471\fP)
.IP \(bu 2
Add additional \fBfile\fP module helpers to Windows (\fI\%issue 11235\fP)
.IP \(bu 2
Add \fBpid\fP to netstat output on Windows (\fI\%issue 10782\fP)
.IP \(bu 2
Fix Windows not caching new versions of installers in winrepo (\fI\%issue 10597\fP)
.IP \(bu 2
Fix hardcoded md5 hashing
.IP \(bu 2
Fix kwargs in salt\-ssh (\fI\%issue 11609\fP)
.IP \(bu 2
Fix file backup timestamps (\fI\%issue 11745\fP)
.IP \(bu 2
Fix stacktrace on \fBsys.doc\fP with invalid eauth (\fI\%issue 11293\fP)
.IP \(bu 2
Fix \fBgit.latest\fP with \fBtest=True\fP (\fI\%issue 11595\fP)
.IP \(bu 2
Fix \fBfile.check_perms\fP hardcoded \fBfollow_symlinks\fP (\fI\%issue 11387\fP)
.IP \(bu 2
Fix certain \fBpkg\fP states for RHEL5/Cent5 machines (\fI\%issue 11719\fP)
.UNINDENT
.SS Salt 2014.1.4 Release Notes
.INDENT 0.0
.TP
.B release
2014\-05\-05
.UNINDENT
.sp
Version 2014.1.4 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Fix setup.py dependency issue (\fI\%issue 12031\fP)
.IP \(bu 2
Fix handling for IOErrors under certain circumstances (\fI\%issue 11783\fP and
\fI\%issue 11853\fP)
.IP \(bu 2
Fix fatal exception when \fB/proc/1/cgroup\fP is not readable (\fI\%issue 11619\fP)
.IP \(bu 2
Fix os grains for OpenSolaris (\fI\%issue 11907\fP)
.IP \(bu 2
Fix \fBlvs.zero\fP module argument pass\-through (\fI\%issue 9001\fP)
.IP \(bu 2
Fix bug in \fBdebian_ip\fP interaction with \fBnetwork.system\fP state (\fI\%issue 11164\fP)
.IP \(bu 2
Remove bad binary package verification code (\fI\%issue 12177\fP)
.IP \(bu 2
Fix traceback in solaris package installation (\fI\%issue 12237\fP)
.IP \(bu 2
Fix \fBfile.directory\fP state symlink handling
(\fI\%issue 12209\fP)
.IP \(bu 2
Remove \fBexternal_ip\fP grain
.IP \(bu 2
Fix \fBfile.managed\fP makedirs issues
(\fI\%issue 10446\fP)
.IP \(bu 2
Fix hang on non\-existent Windows drive letter for \fBfile\fP module (\fI\%issue 9880\fP)
.IP \(bu 2
Fix salt minion caching all users on the server (\fI\%issue 9743\fP)
.IP \(bu 2
Add strftime formatting for \fBps.boot_time\fP
(\fI\%issue 12428\fP)
.UNINDENT
.SS Salt 2014.1.5 Release Notes
.INDENT 0.0
.TP
.B release
2014\-06\-11
.UNINDENT
.sp
Version 2014.1.5 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Add function for finding cached job on the minion
.IP \(bu 2
Fix iptables save file location for Debian (\fI\%issue 11730\fP)
.IP \(bu 2
Fix for minion caching jobs when master is down
.IP \(bu 2
Bump default \fBsyndic_wait\fP to 5 to fix syndic\-related problems
(\fI\%issue 12262\fP)
.IP \(bu 2
Add OpenBSD, FreeBSD, and NetBSD support for \fBnetwork.netstat\fP
(\fI\%issue 12121\fP)
.IP \(bu 2
Fix false positive error in logs for \fBmakeconf\fP state (\fI\%issue 9762\fP)
.IP \(bu 2
Fix for yum \fBfromrepo\fP package installs when repo is disabled by default
(\fI\%issue 12466\fP)
.IP \(bu 2
Fix for extra blank lines in \fBfile.blockreplace\fP (\fI\%issue 12422\fP)
.IP \(bu 2
Fix grain detection for OpenVZ guests (\fI\%issue 11877\fP)
.IP \(bu 2
Fix \fBget_dns_servers\fP function for Windows \fBwin_dns_client\fP
.IP \(bu 2
Use system locale for ports package installations
.IP \(bu 2
Use correct stop/restart procedure for Debian networking in \fBdebian_ip\fP
(\fI\%issue 12614\fP)
.IP \(bu 2
Fix for \fBcmd_iter\fP/\fBcmd_iter_no_block\fP blocking issues (\fI\%issue 12617\fP)
.IP \(bu 2
Fix traceback when syncing custom types (\fI\%issue 12883\fP)
.IP \(bu 2
Fix cleaning directory symlinks in \fBfile.directory\fP
.IP \(bu 2
Add performance optimizations for \fBsaltutil.sync_all\fP and
\fBstate.highstate\fP
.IP \(bu 2
Fix possible error in \fBsaltutil.running\fP
.IP \(bu 2
Fix for kmod modules with dashes (\fI\%issue 13239\fP)
.IP \(bu 2
Fix possible race condition for Windows minions in state module reloading
(\fI\%issue 12370\fP)
.IP \(bu 2
Fix bug with roster for \fBpasswd\fP option that is loaded as a non\-string object
(\fI\%issue 13249\fP)
.IP \(bu 2
Keep duplicate version numbers from showing up in \fBpkg.list_pkgs\fP output
.IP \(bu 2
Fixes for Jinja renderer, timezone \fBmodule\fP/\fBstate\fP (\fI\%issue 12724\fP)
.IP \(bu 2
Fix timedatectl parsing for systemd>=210 (\fI\%issue 12728\fP)
.IP \(bu 2
Fix \fBsaltenv\fP being written to YUM repo config files (\fI\%issue 12887\fP)
.IP \(bu 2
Removed the deprecated external nodes classifier (originally accessible by
setting a value for external_nodes in the master configuration file). Note
that this functionality has been marked deprecated for some time and was
replaced by the more general \fBmaster tops\fP
system.
.IP \(bu 2
More robust escaping of ldap filter strings.
.IP \(bu 2
Fix trailing slash in \fBgitfs_root\fP causing files not to be
available (\fI\%issue 13185\fP)
.UNINDENT
.SS Salt 2014.1.6 Release Notes
.INDENT 0.0
.TP
.B release
2014\-07\-08
.UNINDENT
.sp
Version 2014.1.6 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Fix extra \fBiptables \-\-help\fP output (Sorry!) (\fI\%issue 13648\fP,
\fI\%issue 13507\fP, \fI\%issue 13527\fP, \fI\%issue 13607\fP)
.IP \(bu 2
Fix \fBmount.active\fP for Solaris
.IP \(bu 2
Fix support for \fBallow\-hotplug\fP statement in debian_ip network module
.IP \(bu 2
Add sqlite3 to esky builds
.IP \(bu 2
Fix \fBjobs.active\fP output (\fI\%issue 9526\fP)
.IP \(bu 2
Fix the \fBvirtual\fP grain for Xen (\fI\%issue 13534\fP)
.IP \(bu 2
Fix eauth for batch mode (\fI\%issue 9605\fP)
.IP \(bu 2
Fix force\-related issues with \fBtomcat\fP support (\fI\%issue 12889\fP)
.IP \(bu 2
Fix KeyError when cloud mapping
.IP \(bu 2
Fix salt\-minion restart loop in Windows (\fI\%issue 12086\fP)
.IP \(bu 2
Fix detection of \fBservice\fP virtual module on Fedora minions
.IP \(bu 2
Fix traceback with missing ipv4 grain (\fI\%issue 13838\fP)
.IP \(bu 2
Fix issue in roots backend with invalid data in mtime_map (\fI\%issue 13836\fP)
.IP \(bu 2
Fix traceback in \fBjobs.active\fP (\fI\%issue 11151\fP)
.IP \(bu 2
Fix \fBmaster_tops\fP and \fB_ext_nodes\fP issue (\fI\%issue 13535\fP, \fI\%issue 13673\fP)
.UNINDENT
.SS Salt 2014.1.7 Release Notes
.INDENT 0.0
.TP
.B release
2014\-07\-09
.UNINDENT
.sp
Version 2014.1.7 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Fix batch mode regression (\fI\%issue 14046\fP)
.UNINDENT
.sp
This release was a hotfix release for the regression listed above which was
present in the 2014.1.6 release. The changes included in 2014.1.6 are listed
below:
.INDENT 0.0
.IP \(bu 2
Fix extra \fBiptables \-\-help\fP output (Sorry!) (\fI\%issue 13648\fP,
\fI\%issue 13507\fP, \fI\%issue 13527\fP, \fI\%issue 13607\fP)
.IP \(bu 2
Fix \fBmount.active\fP for Solaris
.IP \(bu 2
Fix support for \fBallow\-hotplug\fP statement in debian_ip network module
.IP \(bu 2
Add sqlite3 to esky builds
.IP \(bu 2
Fix \fBjobs.active\fP output (\fI\%issue 9526\fP)
.IP \(bu 2
Fix the \fBvirtual\fP grain for Xen (\fI\%issue 13534\fP)
.IP \(bu 2
Fix eauth for batch mode (\fI\%issue 9605\fP)
.IP \(bu 2
Fix force\-related issues with \fBtomcat\fP support (\fI\%issue 12889\fP)
.IP \(bu 2
Fix KeyError when cloud mapping
.IP \(bu 2
Fix salt\-minion restart loop in Windows (\fI\%issue 12086\fP)
.IP \(bu 2
Fix detection of \fBservice\fP virtual module on Fedora minions
.IP \(bu 2
Fix traceback with missing ipv4 grain (\fI\%issue 13838\fP)
.IP \(bu 2
Fix issue in roots backend with invalid data in mtime_map (\fI\%issue 13836\fP)
.IP \(bu 2
Fix traceback in \fBjobs.active\fP (\fI\%issue 11151\fP)
.IP \(bu 2
Fix \fBmaster_tops\fP and \fB_ext_nodes\fP issue (\fI\%issue 13535\fP, \fI\%issue 13673\fP)
.UNINDENT
.SS Salt 2014.1.8 Release Notes
.INDENT 0.0
.TP
.B release
2014\-07\-30
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This release contained a regression which caused inaccurate Salt version
detection, and thus was never packaged for general release. Please use
version 2014.1.10 instead.
.UNINDENT
.UNINDENT
.sp
Version 2014.1.8 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Ensure salt\-ssh will not continue if permissions on a temporary directory are
not correct.
.IP \(bu 2
Use the bootstrap script distributed with Salt instead of relying on an
external resource
.IP \(bu 2
Remove unused testing code
.IP \(bu 2
Ensure salt states are placed into the \fB\&.salt\fP directory in salt\-ssh
.IP \(bu 2
Use a randomized path for temporary files in a salt\-cloud deployment
.IP \(bu 2
Clean any stale directories to ensure a fresh copy of salt\-ssh during a
deployment
.UNINDENT
.SS Salt 2014.1.9 Release Notes
.INDENT 0.0
.TP
.B release
2014\-07\-31
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This release contained a regression which caused inaccurate Salt version
detection, and thus was never packaged for general release. Please use
version 2014.1.10 instead.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Version 2014.1.8 contained a regression which caused inaccurate Salt version
detection, and thus was never packaged for general release. This version
contains the version detection fix, but is otherwise identical to 2014.1.8.
.UNINDENT
.UNINDENT
.sp
Version 2014.1.9 is another bugfix release for \fB2014.1.0\fP\&. Changes include:
.INDENT 0.0
.IP \(bu 2
Ensure salt\-ssh will not continue if permissions on a temporary directory are
not correct.
.IP \(bu 2
Use the bootstrap script distributed with Salt instead of relying on an
external resource
.IP \(bu 2
Remove unused testing code
.IP \(bu 2
Ensure salt states are placed into the \fB\&.salt\fP directory in salt\-ssh
.IP \(bu 2
Use a randomized path for temporary files in a salt\-cloud deployment
.IP \(bu 2
Clean any stale directories to ensure a fresh copy of salt\-ssh during a
deployment
.UNINDENT
.SS Salt 0.10.0 Release Notes
.INDENT 0.0
.TP
.B release
2012\-06\-16
.UNINDENT
.sp
0.10.0 has arrived! This release comes with MANY bug fixes, and new
capabilities which greatly enhance performance and reliability. This
release is primarily a bug fix release with many new tests and many repaired
bugs. This release also introduces a few new key features which were brought
in primarily to repair bugs and some limitations found in some of the
components of the original architecture.
.SS Major Features
.SS Event System
.sp
The Salt Master now comes equipped with a new event system. This event system
has replaced some of the back end of the Salt client and offers the beginning of
a system which will make plugging external applications into Salt. The event
system relies on a local ZeroMQ publish socket and other processes can connect
to this socket and listen for events. The new events can be easily managed via
Salt\(aqs event library.
.SS Unprivileged User Updates
.sp
Some enhancements have been added to Salt for running as a user other than
root. These new additions should make switching the user that the Salt Master
is running as very painless, simply change the \fBuser\fP option in the master
configuration and restart the master, Salt will take care of all of the
particulars for you.
.SS Peer Runner Execution
.sp
Salt has long had the peer communication system used to allow minions to send
commands via the salt master. 0.10.0 adds a new capability here, now the
master can be configured to allow for minions to execute Salt runners via
the \fBpeer_run\fP option in the salt master configuration.
.SS YAML Parsing Updates
.sp
In the past the YAML parser for sls files would return the incorrect numbers
when the file mode was set with a preceding 0. The YAML parser used in Salt
has been modified to no longer convert these number into octal but to keep
them as the correct value so that sls files can be a little cleaner to write.
.SS State Call Data Files
.sp
It was requested that the minion keep a local cache of the most recent executed
state run. This has been added and now with state runs the data is stored in a
msgpack file in the minion\(aqs cachedir.
.SS Turning Off the Job Cache
.sp
A new option has been added to the master configuration file. In previous
releases the Salt client would look over the Salt job cache to read in
the minion return data. With the addition of the event system the Salt client
can now watch for events directly from the master worker processes.
.sp
This means that the job cache is no longer a hard requirement. Keep in mind
though, that turning off the job cache means that historic job execution data
cannot be retrieved.
.SS Test Updates
.SS Minion Swarms Are Faster
.sp
To continue our efforts with testing Salt\(aqs ability to scale the minionswarm
script has been updated. The minionswarm can now start up minions much faster
than it could before and comes with a new feature allowing modules to be
disabled, thus lowering the minion\(aqs footprint when making a swarm. These new
updates have allows us to test
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# python minionswarm.py \-m 20 \-\-master salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Many Fixes
.sp
To get a good idea for the number of bugfixes this release offers take a look
at the closed tickets for 0.10.0, this is a very substantial update:
.sp
\fI\%https://github.com/saltstack/salt/issues?milestone=12&state=closed\fP
.SS Master and Minion Stability Fixes
.sp
As Salt deployments grow new ways to break Salt are discovered. 0.10.0 comes
with a number of fixes for the minions and master greatly improving Salt
stability.
.SS Salt 0.10.1 Release Notes
.INDENT 0.0
.TP
.B release
2012\-06\-19
.UNINDENT
.SS Salt 0.10.2 Release Notes
.INDENT 0.0
.TP
.B release
2012\-07\-30
.UNINDENT
.sp
0.10.2 is out! This release comes with enhancements to the pillar interface,
cleaner ways to access the salt\-call capabilities in the API, minion data
caching and the event system has been added to salt minions.
.sp
There have also been updates to the ZeroMQ functions, many more tests
(thanks to sponsors, the code sprint and many contributors) and a swath
of bug fixes.
.SS Major Features
.SS Ext Pillar Modules
.sp
The ranks of available Salt modules directories sees a new member in 0.10.2.
With the popularity of pillar a higher demand has arisen for \fBext_pillar\fP
interfaces to be more like regular Salt module additions. Now ext_pillar
interfaces can be added in the same way as other modules, just drop it into
the pillar directory in the salt source.
.SS Minion Events
.sp
In 0.10.0 an event system was added to the Salt master. 0.10.2 adds the event
system to the minions as well. Now event can be published on a local minion
as well.
.sp
The minions can also send events back up to the master. This means that Salt is
able to communicate individual events from the minions back up to the Master
which are not associated with command.
.SS Minion Data Caching
.sp
When pillar was introduced the landscape for available data was greatly
enhanced. The minion\(aqs began sending grain data back to the master on a
regular basis.
.sp
The new config option on the master called \fBminion_data_cache\fP instructs the
Salt master to maintain a cache of the minion\(aqs grains and pillar data in the
cachedir. This option is turned off by default to avoid hitting the disk more,
but when enabled the cache is used to make grain matching from the salt command
more powerful, since the minions that will match can be predetermined.
.SS Backup Files
.sp
By default all files replaced by the file.managed and file.recurse states we
simply deleted. 0.10.2 adds a new option. By setting the backup option to
\fBminion\fP the files are backed up before they are replaced.
.sp
The backed up files are located in the cachedir under the file_backup
directory. On a default system this will be at:
\fB/var/cache/salt/file_backup\fP
.SS Configuration files
.sp
\fBsalt\-master\fP and \fBsalt\-minion\fP automatically load additional configuration
files from \fBmaster.d/*.conf\fP respective \fBminion.d/*.conf\fP where
\fBmaster.d\fP/\fBminion.d\fP is a directory in the same directory as the main
configuration file.
.SS Salt Key Verification
.sp
A number of users complained that they had inadvertently deleted the wrong salt
authentication keys. 0.10.2 now displays what keys are going to be deleted
and verifies that they are the keys that are intended for deletion.
.SS Key auto\-signing
.sp
If \fBautosign_file\fP is specified in the configuration file incoming keys
will be compared to the list of keynames in \fBautosign_file\fP\&. Regular
expressions as well as globbing is supported.
.sp
The file must only be writable by the user otherwise the file will be
ignored. To relax the permission and allow group write access set the
\fBpermissive_pki_access\fP option.
.SS Module changes
.SS Improved OpenBSD support
.sp
New modules for managing services and packages were provided by Joshua
Elsasser to further improve the support for OpenBSD.
.sp
Existing modules like the \fIdisk\fP module were also improved to support
OpenBSD.
.SS SQL Modules
.sp
The MySQL and PostgreSQL modules have both received a number of additions thanks
to the work of Avi Marcus and Roman Imankulov.
.SS ZFS Support on FreeBSD
.sp
A new ZFS module has been added by Kurtis Velarde for FreeBSD supporting
various ZFS operations like creating, extending or removing zpools.
.SS Augeas
.sp
A new Augeas module by Ulrich Dangel for editing and verifying config files.
.SS Native Debian Service module
.sp
The support for the Debian was further improved with an new service module
for Debian by Ahmad Khayyat supporting \fIdisable\fP and \fIenable\fP\&.
.SS Cassandra
.sp
Cassandra support has been added by Adam Garside. Currently only
status and diagnostic information are supported.
.SS Networking
.sp
The networking support for \fIRHEL\fP has been improved and supports bonding
support as well as zeroconf configuration.
.SS Monit
.sp
Basic monit support by Kurtis Velarde to control services via monit.
.SS nzbget
.sp
Basic support for controlling nzbget by Joseph Hall
.SS Bluetooth
.sp
Baisc \fBbluez\fP support for managing and controlling Bluetooth devices.
Supports scanning as well as pairing/unpairing by Joseph Hall.
.SS Test Updates
.SS Consistency Testing
.sp
Another testing script has been added. A bug was found in pillar when many
minions generated pillar data at the same time. The new \fBconsist.py\fP script
is the tests directory was created to reproduce bugs where data should always
be consistent.
.SS Many Fixes
.sp
To get a good idea for the number of bugfixes this release offers take a look
at the closed tickets for 0.10.2, this is a very substantial update:
.sp
\fI\%https://github.com/saltstack/salt/issues?milestone=24&page=1&state=closed\fP
.SS Master and Minion Stability Fixes
.sp
As Salt deployments grow new ways to break Salt are discovered. 0.10.2 comes
with a number of fixes for the minions and master greatly improving Salt
stability.
.SS Salt 0.10.3 Release Notes
.INDENT 0.0
.TP
.B release
2012\-09\-30
.UNINDENT
.sp
The latest taste of Salt has come, this release has many fixes and feature
additions. Modifications have been made to make ZeroMQ connections more
reliable, the beginning of the ACL system is in place, a new command line
parsing system has been added, dynamic module distribution has become more
environment aware, the new \fImaster_finger\fP option and many more!
.SS Major Features
.SS ACL System
.sp
The new ACL system has been introduced. The ACL system allows for system users
other than root to execute salt commands. Users can be allowed to execute
specific commands in the same way that minions are opened up to the peer
system.
.sp
The configuration value to open up the ACL system is called \fBclient_acl\fP
and is configured like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
client_acl:
fred:
\- test..*
\- pkg.list_pkgs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where \fIfred\fP is allowed access to functions in the test module and to the
\fBpkg.list_pkgs\fP function.
.SS Master Finger Option
.sp
The \fImaster_finger\fP option has been added to improve the security of minion
provisioning. The \fImaster_finger\fP option allows for the fingerprint of the
master public key to be set in the configuration file to double verify that the
master is valid. This option was added in response to a motivation to
pre\-authenticate the master when provisioning new minions to help prevent
man in the middle attacks in some situations.
.SS Salt Key Fingerprint Generation
.sp
The ability to generate fingerprints of keys used by Salt has been added to
\fBsalt\-key\fP\&. The new option \fIfinger\fP accepts the name of the key to generate
and display a fingerprint for.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-key \-F master
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will display the fingerprints for the master public and private keys.
.SS Parsing System
.sp
Pedro Algavio, aka s0undt3ch, has added a substantial update to the command
line parsing system that makes the help message output much cleaner and easier
to search through. Salt parsers now have \fI\-\-versions\-report\fP besides usual
\fI\-\-version\fP info which you can provide when reporting any issues found.
.SS Key Generation
.sp
We have reduced the requirements needed for \fIsalt\-key\fP to generate minion keys.
You\(aqre no longer required to have salt configured and it\(aqs common directories
created just to generate keys. This might prove useful if you\(aqre batch creating
keys to pre\-load on minions.
.SS Startup States
.sp
A few configuration options have been added which allow for states to be run
when the minion daemon starts. This can be a great advantage when deploying
with Salt because the minion can apply states right when it first runs. To
use startup states set the \fBstartup_states\fP configuration option on the
minion to \fIhighstate\fP\&.
.SS New Exclude Declaration
.sp
Some users have asked about adding the ability to ensure that other sls files
or ids are excluded from a state run. The exclude statement will delete all of
the data loaded from the specified sls file or will delete the specified id:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
exclude:
\- sls: http
\- id: /etc/vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Max Open Files
.sp
While we\(aqre currently unable to properly handle ZeroMQ\(aqs abort signals when the
max open files is reached, due to the way that\(aqs handled on ZeroMQ\(aqs, we have
minimized the chances of this happening without at least warning the user.
.SS More State Output Options
.sp
Some major changes have been made to the state output system. In the past state
return data was printed in a very verbose fashion and only states that failed
or made changes were printed by default. Now two options can be passed to the
master and minion configuration files to change the behavior of the state
output. State output can be set to verbose (default) or non\-verbose with the
\fBstate_verbose\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_verbose: False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is noteworthy that the state_verbose option used to be set to \fIFalse\fP by
default but has been changed to \fITrue\fP by default in 0.10.3 due to many
requests for the change.
.sp
Te next option to be aware of new and called \fBstate_output\fP\&. This option
allows for the state output to be set to \fIfull\fP (default) or \fIterse\fP\&.
.sp
The \fIfull\fP output is the standard state output, but the new \fIterse\fP output
will print only one line per state making the output much easier to follow when
executing a large state system.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
state_output: terse
.ft P
.fi
.UNINDENT
.UNINDENT
.SS \fIstate.file.append\fP Improvements
.sp
The salt state \fIfile.append()\fP tries \fInot\fP to append existing text. Previously
the matching check was being made line by line. While this kind of check might
be enough for most cases, if the text being appended was multi\-line, the check
would not work properly. This issue is now properly handled, the match is done
as a whole ignoring any white space addition or removal except inside commas.
For those thinking that, in order to properly match over multiple lines, salt
will load the whole file into memory, that\(aqs not true. For most cases this is
not important but an erroneous order to read a 4GB file, if not properly
handled, like salt does, could make salt chew that amount of memory. Salt has
a buffered file reader which will keep in memory a maximum of 256KB and
iterates over the file in chunks of 32KB to test for the match, more than
enough, if not, explain your usage on a ticket. With this change, also
\fIsalt.modules.file.contains()\fP, \fIsalt.modules.file.contains_regex()\fP,
\fIsalt.modules.file.contains_glob()\fP and \fIsalt.utils.find\fP now do the searching
and/or matching using the buffered chunks approach explained above.
.sp
Two new keyword arguments were also added, \fImakedirs\fP and \fIsource\fP\&.
The first, \fImakedirs\fP will create the necessary directories in order to append
to the specified file, of course, it only applies if we\(aqre trying to append to
a non\-existing file on a non\-existing directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/tmp/salttest/file\-append\-makedirs:
file.append:
text: foo
makedirs: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The second, \fIsource\fP, allows one to append the contents of a file instead of
specifying the text.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/tmp/salttest/file\-append\-source:
file.append:
\- source: salt://testfile
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Security Fix
.sp
A timing vulnerability was uncovered in the code which decrypts the AES
messages sent over the network. This has been fixed and upgrading is
strongly recommended.
.SS Salt 0.10.4 Release Notes
.INDENT 0.0
.TP
.B release
2012\-10\-23
.UNINDENT
.sp
Salt 0.10.4 is a monumental release for the Salt team, with two new module
systems, many additions to allow granular access to Salt, improved platform
support and much more.
.sp
This release is also exciting because we have been able to shorten the release
cycle back to under a month. We are working hard to keep up the aggressive pace
and look forward to having releases happen more frequently!
.sp
This release also includes a serious security fix and all users are very
strongly recommended to upgrade. As usual, upgrade the master first, and then
the minion to ensure that the process is smooth.
.SS Major Features
.SS External Authentication System
.sp
The new external authentication system allows for Salt to pass through
authentication to any authentication system to determine if a user has
permission to execute a Salt command. The Unix PAM system is the first
supported system with more to come!
.sp
The external authentication system allows for specific users to be granted
access to execute specific functions on specific minions. Access is configured
in the master configuration file, and uses the new access control system:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
external_auth:
pam:
thatch:
\- \(aqweb*\(aq:
\- test.*
\- network.*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The configuration above allows the user \fIthatch\fP to execute functions in the
test and network modules on minions that match the web* target.
.SS Access Control System
.sp
All Salt systems can now be configured to grant access to non\-administrative
users in a granular way. The old configuration continues to work. Specific
functions can be opened up to specific minions from specific users in the case
of external auth and client ACLs, and for specific minions in the case of the
peer system.
.sp
Access controls are configured like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
client_acl:
fred:
\- web\e*:
\- pkg.list_pkgs
\- test.*
\- apache.*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Target by Network
.sp
A new matcher has been added to the system which allows for minions to be
targeted by network. This new matcher can be called with the \fI\-S\fP flag on the
command line and is available in all places that the matcher system is
available. Using it is simple:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt \-S \(aq192.168.1.0/24\(aq test.ping
$ salt \-S \(aq192.168.1.100\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Nodegroup Nesting
.sp
Previously a nodegroup was limited by not being able to include another
nodegroup, this restraint has been lifted and now nodegroups will be expanded
within other nodegroups with the \fIN@\fP classifier.
.SS Salt Key Delete by Glob
.sp
The ability to delete minion keys by glob has been added to \fBsalt\-key\fP\&. To
delete all minion keys whose minion name starts with \(aqweb\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-key \-d \(aqweb*\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Master Tops System
.sp
The \fIexternal_nodes\fP system has been upgraded to allow for modular subsystems
to be used to generate the top file data for a highstate run.
.sp
The \fIexternal_nodes\fP option still works but will be deprecated in the future in
favor of the new \fImaster_tops\fP option.
.sp
Example of using \fImaster_tops\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master_tops:
ext_nodes: cobbler\-external\-nodes
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Next Level Solaris Support
.sp
A lot of work has been put into improved Solaris support by Romeo Theriault.
Packaging modules (pkgadd/pkgrm and pkgutil) and states, cron support and user
and group management have all been added and improved upon. These additions
along with SMF (Service Management Facility) service support and improved
Solaris grain detection in 0.10.3 add up to Salt becoming a great tool
to manage Solaris servers with.
.SS Security
.sp
A vulnerability in the security handshake was found and has been repaired, old
minions should be able to connect to a new master, so as usual, the master
should be updated first and then the minions.
.SS Pillar Updates
.sp
The pillar communication has been updated to add some extra levels of
verification so that the intended minion is the only one allowed to gather the
data. Once all minions and the master are updated to salt 0.10.4 please
activate pillar \fI2\fP by changing the \fIpillar_version\fP in the master config to
\fI2\fP\&. This will be set to \fI2\fP by default in a future release.
.SS Salt 0.10.5 Release Notes
.INDENT 0.0
.TP
.B release
2012\-11\-15
.UNINDENT
.sp
Salt 0.10.5 is ready, and comes with some great new features. A few more
interfaces have been modularized, like the outputter system. The job cache
system has been made more powerful and can now store and retrieve jobs archived
in external databases. The returner system has been extended to allow minions
to easily retrieve data from a returner interface.
.sp
As usual, this is an exciting release, with many noteworthy additions!
.SS Major Features
.SS External Job Cache
.sp
The external job cache is a system which allows for a returner interface to
also act as a job cache. This system is intended to allow users to store
job information in a central location for longer periods of time and to make
the act of looking up information from jobs executed on other minions easier.
.sp
Currently the external job cache is supported via the mongo and redis
returners:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_job_cache: redis
redis.host: salt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once the external job cache is turned on the new \fIret\fP module can be used on
the minions to retrieve return information from the job cache. This can be a
great way for minions to respond and react to other minions.
.SS OpenStack Additions
.sp
OpenStack integration with Salt has been moving forward at a blistering pace.
The new \fInova\fP, \fIglance\fP and \fIkeystone\fP modules represent the beginning of
ongoing OpenStack integration.
.sp
The Salt team has had many conversations with core OpenStack developers and
is working on linking to OpenStack in powerful new ways.
.SS Wheel System
.sp
A new API was added to the Salt Master which allows the master to be managed
via an external API. This new system allows Salt API to easily hook into the
Salt Master and manage configs, modify the state tree, manage the pillar and
more. The main motivation for the wheel system is to enable features needed
in the upcoming web UI so users can manage the master just as easily as they
manage minions.
.sp
The wheel system has also been hooked into the external auth system. This
allows specific users to have granular access to manage components of the
Salt Master.
.SS Render Pipes
.sp
Jack Kuan has added a substantial new feature. The render pipes system allows
Salt to treat the render system like unix pipes. This new system enables sls
files to be passed through specific render engines. While the default renderer
is still recommended, different engines can now be more easily merged. So to
pipe the output of Mako used in YAML use this shebang line:
.sp
#!mako|yaml
.SS Salt Key Overhaul
.sp
The Salt Key system was originally developed as only a CLI interface, but as
time went on it was pressed into becoming a clumsy API. This release marks a
complete overhaul of Salt Key. Salt Key has been rewritten to function purely
from an API and to use the outputter system. The benefit here is that the
outputter system works much more cleanly with Salt Key now, and the internals
of Salt Key can be used much more cleanly.
.SS Modular Outputters
.sp
The outputter system is now loaded in a modular way. This means that output
systems can be more easily added by dropping a python file down on the master
that contains the function \fIoutput\fP\&.
.SS Gzip from Fileserver
.sp
Gzip compression has been added as an option to the cp.get_file and cp.get_dir
commands. This will make file transfers more efficient and faster, especially
over slower network links.
.SS Unified Module Configuration
.sp
In past releases of Salt, the minions needed to be configured for certain
modules to function. This was difficult because it required pre\-configuring the
minions. 0.10.5 changes this by making all module configs on minions search the
master config file for values.
.sp
Now if a single database server is needed, then it can be defined in the master
config and all minions will become aware of the configuration value.
.SS Salt Call Enhancements
.sp
The \fBsalt\-call\fP command has been updated in a few ways. Now, \fBsalt\-call\fP
can take the \-\-return option to send the data to a returner. Also,
\fBsalt\-call\fP now reports executions in the minion proc system, this allows the
master to be aware of the operation salt\-call is running.
.SS Death to pub_refresh and sub_timeout
.sp
The old configuration values \fIpub_refresh\fP and \fIsub_timeout\fP have been removed.
These options were in place to alleviate problems found in earlier versions of
ZeroMQ which have since been fixed. The continued use of these options has
proven to cause problems with message passing and have been completely removed.
.SS Git Revision Versions
.sp
When running Salt directly from git (for testing or development, of course)
it has been difficult to know exactly what code is being executed. The new
versioning system will detect the git revision when building and how many
commits have been made since the last release. A release from git will look
like this:
.sp
0.10.4\-736\-gec74d69
.SS Svn Module Addition
.sp
Anthony Cornehl (twinshadow) contributed a module that adds Subversion support
to Salt. This great addition helps round out Salt\(aqs VCS support.
.SS Noteworthy Changes
.SS Arch Linux Defaults to Systemd
.sp
Arch Linux recently changed to use systemd by default and discontinued support
for init scripts. Salt has followed suit and defaults to systemd now for
managing services in Arch.
.SS Salt, Salt Cloud and Openstack
.sp
With the releases of Salt 0.10.5 and Salt Cloud 0.8.2, OpenStack becomes the
first (non\-OS) piece of software to include support both on the user level
(with Salt Cloud) and the admin level (with Salt). We are excited to continue
to extend support of other platforms at this level.
.SS Salt 0.11.0 Release Notes
.INDENT 0.0
.TP
.B release
2012\-12\-14
.UNINDENT
.sp
Salt 0.11.0 is here, with some highly sought after and exciting features.
These features include the new overstate system, the reactor system, a new
state run scope component called __context__, the beginning of the search
system (still needs a great deal of work), multiple package states, the MySQL
returner and a better system to arbitrarily reference outputters.
.sp
It is also noteworthy that we are changing how we mark release numbers. For the
life of the project we have been pushing every release with features and fixes
as point releases. We will now be releasing point releases for only bug fixes
on a more regular basis and major feature releases on a slightly less regular
basis. This means that the next release will be a bugfix only release with a
version number of 0.11.1. The next feature release will be named 0.12.0 and
will mark the end of life for the 0.11 series.
.SS Major Features
.SS OverState
.sp
The overstate system is a simple way to manage rolling state executions across
many minions. The overstate allows for a state to depend on the successful
completion of another state.
.SS Reactor System
.sp
The new reactor system allows for a reactive logic engine to be created which
can respond to events within a salted environment. The reactor system uses sls
files to match events fired on the master with actions, enabling Salt
to react to problems in an infrastructure.
.sp
Your load\-balanced group of webservers is under extra load? Spin up a new VM
and add it to the group. Your fileserver is filling up? Send a notification to
your sysadmin on call. The possibilities are endless!
.SS Module Context
.sp
A new component has been added to the module loader system. The module context
is a data structure that can hold objects for a given scope within the module.
.sp
This allows for components that are initialized to be stored in a persistent
context which can greatly speed up ongoing connections. Right now the best
example can be found in the \fIcp\fP execution module.
.SS Multiple Package Management
.sp
A long desired feature has been added to package management. By definition Salt
States have always installed packages one at a time. On most platforms this is
not the fastest way to install packages. Erik Johnson, aka terminalmage, has
modified the package modules for many providers and added new capabilities to
install groups of packages. These package groups can be defined as a list of
packages available in repository servers:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python_pkgs:
pkg.installed:
\- pkgs:
\- python\-mako
\- whoosh
\- python\-git
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or specify based on the location of specific packages:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python_pkgs:
pkg.installed:
\- sources:
\- python\-mako: http://some\-rpms.org/python\-mako.rpm
\- whoosh: salt://whoosh/whoosh.rpm
\- python\-git: ftp://companyserver.net/python\-git.rpm
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Search System
.sp
The bones to the search system have been added. This is a very basic interface
that allows for search backends to be added as search modules. The first
supported search module is the whoosh search backend. Right now only the basic
paths for the search system are in place, making this very experimental.
Further development will involve improving the search routines and index
routines for whoosh and other search backends.
.sp
The search system has been made to allow for searching through all of the state
and pillar files, configuration files and all return data from minion
executions.
.SS Notable Changes
.sp
All previous versions of Salt have shared many directories between the master
and minion. The default locations for keys, cached data and sockets has been
shared by master and minion. This has created serious problems with running a
master and a minion on the same systems. 0.11.0 changes the defaults to be
separate directories. Salt will also attempt to migrate all of the old key data
into the correct new directories, but if it is not successful it may need to be
done manually. If your keys exhibit issues after updating make sure that they
have been moved from \fB/etc/salt/pki\fP to \fB/etc/salt/pki/{master,minion}\fP\&.
.sp
The old setup will look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/pki
|\-\- master.pem
|\-\- master.pub
|\-\- minions
| \(ga\-\- ragnarok.saltstack.net
|\-\- minions_pre
|\-\- minion.pem
|\-\- minion.pub
|\-\- minion_master.pub
|\-\- minions_pre
\(ga\-\- minions_rejected
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With the accepted minion keys in \fB/etc/salt/pki/minions\fP, the new setup
places the accepted minion keys in \fB/etc/salt/pki/master/minions\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/salt/pki
|\-\- master
| |\-\- master.pem
| |\-\- master.pub
| |\-\- minions
| | \(ga\-\- ragnarok.saltstack.net
| |\-\- minions_pre
| \(ga\-\- minions_rejected
|\-\- minion
| |\-\- minion.pem
| |\-\- minion.pub
| \(ga\-\- minion_master.pub
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Salt 0.11.1 Release Notes
.INDENT 0.0
.TP
.B release
2012\-12\-19
.UNINDENT
.SS Salt 0.12.0 Release Notes
.INDENT 0.0
.TP
.B release
2013\-01\-15
.UNINDENT
.sp
Another feature release of Salt is here! Some exciting additions are included
with more ways to make salt modular and even easier management of the salt
file server.
.SS Major Features
.SS Modular Fileserver Backend
.sp
The new modular fileserver backend allows for any external system to be used as
a salt file server. The main benefit here is that it is now possible to tell
the master to directly use a git remote location, or many git remote locations,
automatically mapping git branches and tags to salt environments.
.SS Windows is First Class!
.sp
A new Salt Windows installer is now available! Much work has been put in to
improve Windows support. With this much easier method of getting Salt on your
Windows machines, we hope even more development and progress will occur. Please
file bug reports on the Salt GitHub repo issue tracker so we can continue
improving.
.sp
One thing that is missing on Windows that Salt uses extensively is a software
package manager and a software package repository. The Salt pkg state allows
sys admins to install software across their infrastructure and across operating
systems. Software on Windows can now be managed in the same way. The SaltStack
team built a package manager that interfaces with the standard Salt pkg module
to allow for installing and removing software on Windows. In addition, a
software package repository has been built on top of the Salt fileserver. A
small YAML file provides the information necessary for the package manager to
install and remove software.
.sp
An interesting feature of the new Salt Windows software package repository is
that one or more remote git repositories can supplement the master\(aqs local
repository. The repository can point to software on the master\(aqs fileserver or
on an HTTP, HTTPS, or ftp server.
.SS New Default Outputter
.sp
Salt displays data to the terminal via the outputter system. For a long time
the default outputter for Salt has been the python pretty print library. While
this has been a generally reasonable outputter, it did have many failings. The
new default outputter is called "nested", it recursively scans return data
structures and prints them out cleanly.
.sp
If the result of the new nested outputter is not desired any other outputter
can be used via the \-\-out option, or the output option can be set in the master
and minion configs to change the default outputter.
.SS Internal Scheduler
.sp
The internal Salt scheduler is a new capability which allows for functions to
be executed at given intervals on the minion, and for runners to be executed
at given intervals on the master. The scheduler allows for sequences
such as executing state runs (locally on the minion or remotely via an
overstate) or continually gathering system data to be run at given intervals.
.sp
The configuration is simple, add the schedule option to the master or minion
config and specify jobs to run, this in the master config will execute the
state.over runner every 60 minutes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
overstate:
function: state.over
minutes: 60
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example for the minion configuration will execute a highstate every 30
minutes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule:
highstate:
function: state.highstate
minutes: 30
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Optional DSL for SLS Formulas
.sp
Jack Kuan, our renderer expert, has created something that is astonishing.
Salt, now comes with an optional Python based DSL, this is a very powerful
interface that makes writing SLS files in pure python easier than it was
with the raw py renderer. As usual this can be used with the renderer shebang
line, so a single sls can be written with the DSL if pure python power is
needed while keeping other sls files simple with YAML.
.SS Set Grains Remotely
.sp
A new execution function and state module have been added that allows for
grains to be set on the minion. Now grains can be set via a remote execution or
via states. Use the \fIgrains.present\fP state or the \fIgrains.setval\fP execution
functions.
.SS Gentoo Additions
.sp
Major additions to Gentoo specific components have been made. The encompasses
executions modules and states ranging from supporting the make.conf file to
tools like layman.
.SS Salt 0.12.1 Release Notes
.INDENT 0.0
.TP
.B release
2013\-01\-21
.UNINDENT
.SS Salt 0.13.0 Release Notes
.INDENT 0.0
.TP
.B release
2013\-02\-12
.UNINDENT
.sp
The lucky number 13 has turned the corner! From CLI notifications when quitting
a salt command, to substantial improvements on Windows, Salt 0.13.0 has
arrived!
.SS Major Features
.SS Improved file.recurse Performance
.sp
The file.recurse system has been deployed and used in a vast array of
situations. Fixes to the file state and module have led towards opening up
new ways of running file.recurse to make it faster. Now the file.recurse
state will download fewer files and will run substantially faster.
.SS Windows Improvements
.sp
Minion stability on Windows has improved. Many file operations, including
file.recurse, have been fixed and improved. The network module works better, to
include network.interfaces. Both 32bit and 64bit installers are now available.
.SS Nodegroup Targeting in Peer System
.sp
In the past, nodegroups were not available for targeting via the peer system.
This has been fixed, allowing the new nodegroup expr_form argument for the
publish.publish function:
.INDENT 0.0
.INDENT 3.5
salt\-call publish.publish group1 test.ping expr_form=nodegroup
.UNINDENT
.UNINDENT
.SS Blacklist Additions
.sp
Additions allowing more granular blacklisting are available in 0.13.0. The
ability to blacklist users and functions in client_acl have been added, as
well as the ability to exclude state formulas from the command line.
.SS Command Line Pillar Embedding
.sp
Pillar data can now be embedded on the command line when calling \fBstate.sls\fP
and \fBstate.highstate\fP\&. This allows for on the fly changes or settings to
pillar and makes parameterizing state formulas even easier. This is done via
the keyword argument:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate pillar=\(aq{"cheese": "spam"}\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above example will extend the existing pillar to hold the \fBcheese\fP key
with a value of \fBspam\fP\&. If the \fBcheese\fP key is already specified in the
minion\(aqs pillar then it will be overwritten.
.SS CLI Notifications
.sp
In the past hitting ctrl\-C and quitting from the \fBsalt\fP command would just
drop to a shell prompt, this caused confusion with users who expected the
remote executions to also quit. Now a message is displayed showing what
command can be used to track the execution and what the job id is for the
execution.
.SS Version Specification in Multiple\-Package States
.sp
Versions can now be specified within multiple\-package \fBpkg.installed\fP states. An example can be found below:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mypkgs:
pkg.installed:
\- pkgs:
\- foo
\- bar: 1.2.3\-4
\- baz
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Noteworthy Changes
.sp
The configuration subsystem in Salt has been overhauled to make the \fBopts\fP
dict used by Salt applications more portable, the problem is that this is an
incompatible change with salt\-cloud, and salt\-cloud will need to be updated
to the latest git to work with Salt 0.13.0. Salt Cloud 0.8.5 will also require
Salt 0.13.0 or later to function.
.sp
The SaltStack team is sorry for the inconvenience here, we work hard to make
sure these sorts of things do not happen, but sometimes hard changes get in.
.SS Salt 0.13.1 Release Notes
.INDENT 0.0
.TP
.B release
2013\-02\-15
.UNINDENT
.SS Salt 0.13.2 Release Notes
.INDENT 0.0
.TP
.B release
2013\-03\-13
.UNINDENT
.SS Salt 0.13.3 Release Notes
.INDENT 0.0
.TP
.B release
2013\-03\-18
.UNINDENT
.SS Salt 0.14.0 Release Notes
.INDENT 0.0
.TP
.B release
2013\-03\-23
.UNINDENT
.sp
Salt 0.14.0 is here! This release was held up primarily by PyCon, Scale and
illness, but has arrived! 0.14.0 comes with many new features and is breaking
ground for Salt in the area of cloud management with the introduction of Salt
providing basic cloud controller functionality.
.SS Major Features
.SS Salt \- As a Cloud Controller
.sp
This is the first primitive inroad to using Salt as a cloud controller is
available in 0.14.0. Be advised that this is alpha, only tested in a few very
small environments.
.sp
The cloud controller is built using kvm and libvirt for the hypervisors.
Hypervisors are autodetected as minions and only need to have libvirt running
and kvm installed to function. The features of the Salt cloud controller are
as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Basic vm discovery and reporting
.IP \(bu 2
Creation of new virtual machines
.IP \(bu 2
Seeding virtual machines with Salt via qemu\-nbd or libguestfs
.IP \(bu 2
Live migration (shared and non shared storage)
.IP \(bu 2
Delete existing VMs
.UNINDENT
.UNINDENT
.UNINDENT
.sp
It is noteworthy that this feature is still Alpha, meaning that all rights
are reserved to change the interface if needs be in future releases!
.SS Libvirt State
.sp
One of the problems with libvirt is management of certificates needed for live
migration and cross communication between hypervisors. The new \fBlibvirt\fP
state makes the Salt Master hold a CA and manage the signing and distribution
of keys onto hypervisors, just add a call to the libvirt state in the sls
formulas used to set up a hypervisor:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
libvirt_keys:
libvirt.keys
.ft P
.fi
.UNINDENT
.UNINDENT
.SS New get Functions
.sp
An easier way to manage data has been introduced. The pillar, grains and config
execution modules have been extended with the new \fBget\fP function. This
function works much in the same way as the get method in a python dict, but with
an enhancement, nested dict components can be extracted using a \fI:\fP delimiter.
.sp
If a structure like this is in pillar:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo:
bar:
baz: quo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Extracting it from the raw pillar in an sls formula or file template is done
this way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ pillar[\(aqfoo\(aq][\(aqbar\(aq][\(aqbaz\(aq] }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now with the new get function the data can be safely gathered and a default
can be set allowing the template to fall back if the value is not available:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{{ salt[\(aqpillar.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq) }}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This makes handling nested structures much easier, and defaults can be cleanly
set. This new function is being used extensively in the new formulae repository
of salt sls formulas.
.SS Salt 0.14.1 Release Notes
.INDENT 0.0
.TP
.B release
2013\-04\-13
.UNINDENT
.SS Salt 0.15.0 Release Notes
.INDENT 0.0
.TP
.B release
2013\-05\-03
.UNINDENT
.sp
The many new features of Salt 0.15.0 have arrived! Salt 0.15.0 comes with many
smaller features and a few larger ones.
.sp
These features range from better debugging tools to the new Salt Mine system.
.SS Major Features
.SS The Salt Mine
.sp
First there was the peer system, allowing for commands to be executed from a
minion to other minions to gather data live. Then there was the external job
cache for storing and accessing long term data. Now the middle ground is being
filled in with the Salt Mine. The Salt Mine is a system used to execute
functions on a regular basis on minions and then store only the most recent
data from the functions on the master, then the data is looked up via targets.
.sp
The mine caches data that is public to all minions, so when a minion posts
data to the mine all other minions can see it.
.SS IPV6 Support
.sp
0.13.0 saw the addition of initial IPV6 support but errors were encountered and
it needed to be stripped out. This time the code covers more cases and must be
explicitly enabled. But the support is much more extensive than before.
.SS Copy Files From Minions to the Master
.sp
Minions have long been able to copy files down from the master file server, but
until now files could not be easily copied from the minion up to the master.
.sp
A new function called \fBcp.push\fP can push files from the minions up to the
master server. The uploaded files are then cached on the master in the master
cachedir for each minion.
.SS Better Template Debugging
.sp
Template errors have long been a burden when writing states and pillar. 0.15.0
will now send the compiled template data to the debug log, this makes tracking
down the intermittent stage templates much easier. So running state.sls or
state.highstate with \fI\-l debug\fP will now print out the rendered templates in
the debug information.
.SS State Event Firing
.sp
The state system is now more closely tied to the master\(aqs event bus. Now when
a state fails the failure will be fired on the master event bus so that the
reactor can respond to it.
.SS Major Syndic Updates
.sp
The Syndic system has been basically re\-written. Now it runs in a completely
asynchronous way and functions primarily as an event broker. This means that
the events fired on the syndic are now pushed up to the higher level master
instead of the old method used which waited for the client libraries to
return.
.sp
This makes the syndic much more accurate and powerful, it also means that
all events fired on the syndic master make it up the pipe as well making a
reactor on the higher level master able to react to minions further
downstream.
.SS Peer System Updates
.sp
The Peer System has been updated to run using the client libraries instead
of firing directly over the publish bus. This makes the peer system much more
consistent and reliable.
.SS Minion Key Revocation
.sp
In the past when a minion was decommissioned the key needed to be manually
deleted on the master, but now a function on the minion can be used to revoke
the calling minion\(aqs key:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ salt\-call saltutil.revoke_auth
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Function Return Codes
.sp
Functions can now be assigned numeric return codes to determine if the function
executed successfully. While not all functions have been given return codes,
many have and it is an ongoing effort to fill out all functions that might
return a non\-zero return code.
.SS Functions in Overstate
.sp
The overstate system was originally created to just manage the execution of
states, but with the addition of return codes to functions, requisite logic can
now be used with respect to the overstate. This means that an overstate stage
can now run single functions instead of just state executions.
.SS Pillar Error Reporting
.sp
Previously if errors surfaced in pillar, then the pillar would consist of only
an empty dict. Now all data that was successfully rendered stays in pillar and
the render error is also made available. If errors are found in the pillar,
states will refuse to run.
.SS Using Cached State Data
.sp
Sometimes states are executed purely to maintain a specific state rather than
to update states with new configs. This is grounds for the new cached state
system. By adding \fIcache=True\fP to a state call the state will not be generated
fresh from the master but the last state data to be generated will be used.
If no previous state data is available then fresh data will be generated.
.SS Monitoring States
.sp
The new monitoring states system has been started. This is very young but
allows for states to be used to configure monitoring routines. So far only one
monitoring state is available, the \fBdisk.status\fP state. As more capabilities
are added to Salt UI the monitoring capabilities of Salt will continue to be
expanded.
.SS Salt 0.15.1 Release Notes
.INDENT 0.0
.TP
.B release
2013\-05\-08
.UNINDENT
.sp
The 0.15.1 release has been posted, this release includes fixes to a number of
bugs in 0.15.1 and a three security patches.
.SS Security Updates
.sp
A number of security issues have been resolved via the 0.15.1 release.
.SS Path Injection in Minion IDs
.sp
Salt masters did not properly validate the id of a connecting minion. This can
lead to an attacker uploading files to the master in arbitrary locations.
In particular this can be used to bypass the manual validation of new unknown
minions. Exploiting this vulnerability does not require authentication.
.sp
This issue affects all known versions of Salt.
.sp
This issue was reported by Ronald Volgers.
.SS Patch
.sp
The issue is fixed in Salt 0.15.1. Updated packages are available in the usual
locations.
.sp
Specific commits:
.sp
\fI\%https://github.com/saltstack/salt/commit/5427b9438e452a5a8910d9128c6aafb45d8fd5d3\fP
.sp
\fI\%https://github.com/saltstack/salt/commit/7560908ee62351769c3cd43b03d74c1ca772cc52\fP
.sp
\fI\%https://github.com/saltstack/salt/commit/e200b8a7ff53780124e08d2bdefde7587e52bfca\fP
.SS RSA Key Generation Fault
.sp
RSA key generation was done incorrectly, leading to very insecure keys. It is
recommended to regenerate all RSA keys.
.sp
This issue can be used to impersonate Salt masters or minions, or decrypt any
transferred data.
.sp
This issue can only be exploited by attackers who are able to observe or modify
traffic between Salt minions and the legitimate Salt master.
.sp
A tool was included in 0.15.1 to assist in mass key regeneration, the
manage.regen_keys runner.
.sp
This issue affects all known versions of Salt.
.sp
This issue was reported by Ronald Volgers.
.SS Patch
.sp
The issue is fixed in Salt 0.15.1. Updated packages are available in the usual
locations.
.sp
Specific commits:
.sp
\fI\%https://github.com/saltstack/salt/commit/5dd304276ba5745ec21fc1e6686a0b28da29e6fc\fP
.SS Command Injection Via ext_pillar
.sp
Arbitrary shell commands could be executed on the master by an authenticated
minion through options passed when requesting a pillar.
.sp
Ext pillar options have been restricted to only allow safe external pillars to
be called when prompted by the minion.
.sp
This issue affects Salt versions from 0.14.0 to 0.15.0.
.sp
This issue was reported by Ronald Volgers.
.SS Patch
.sp
The issue is fixed in Salt 0.15.1. Updated packages are available in the usual locations.
.sp
Specific commits:
.sp
\fI\%https://github.com/saltstack/salt/commit/43d8c16bd26159d827d1a945c83ac28159ec5865\fP
.SS Salt 0.15.2 Release Notes
.INDENT 0.0
.TP
.B release
2013\-05\-29
.UNINDENT
.SS Salt 0.15.3 Release Notes
.INDENT 0.0
.TP
.B release
2013\-06\-01
.UNINDENT
.SS Salt 0.16.0 Release Notes
.INDENT 0.0
.TP
.B release
2013\-07\-01
.UNINDENT
.sp
The 0.16.0 release is an exciting one, with new features in master redundancy,
and a new, powerful requisite.
.SS Major Features
.SS Multi\-Master
.sp
This new capability allows for a minion to be actively connected to multiple
salt masters at the same time. This allows for multiple masters to send out commands
to minions and for minions to automatically reconnect to masters that have gone
down. A tutorial is available to help get started here:
.sp
\fBMulti Master Tutorial\fP
.SS Prereq, the New Requisite
.sp
The new \fIprereq\fP requisite is very powerful! It allows for states to execute
based on a state that is expected to make changes in the future. This allows
for a change on the system to be preempted by another execution. A good example
is needing to shut down a service before modifying files associated with it,
allowing, for instance, a webserver to be shut down allowing a load balancer to
stop sending requests while server side code is updated. In this case, the
prereq will only run if changes are expected to happen in the prerequired
state, and the prerequired state will always run after the prereq state and
only if the prereq state succeeds.
.SS Peer System Improvements
.sp
The peer system has been revamped to make it more reliable, faster, and like
the rest of Salt, async. The peer calls when an updated minion and master are
used together will be much faster!
.SS Relative Includes
.sp
The ability to include an sls relative to the defined sls has been added, the
new syntax id documented here:
.sp
\fBIncludes\fP
.SS More State Output Options
.sp
The \fBstate_output\fP option in the past only supported \fIfull\fP and \fIterse\fP,
0.16.0 add the \fImixed\fP and \fIchanges\fP modes further refining how states are sent
to users\(aq eyes.
.SS Improved Windows Support
.sp
Support for Salt on Windows continues to improve. Software management on
Windows has become more seamless with Linux/UNIX/BSD software management.
Installed software is now recognized by the short names defined in the
\fBrepository SLS\fP\&. This makes it
possible to run \fBsalt \(aq*\(aq pkg.version firefox\fP and get back results from
Windows and non\-Windows minions alike.
.sp
When templating files on Windows, Salt will now correctly use Windows
appropriate line endings. This makes it much easier to edit and consume files
on Windows.
.sp
When using the cmd state the \fBshell\fP option now allows for specifying
Windows Powershell as an alternate shell to execute cmd.run and cmd.script.
This opens up Salt to all the power of Windows Powershell and its advanced
Windows management capabilities.
.sp
Several fixes and optimizations were added for the Windows networking modules,
especially when working with IPv6.
.sp
A system module was added that makes it easy to restart and shutdown Windows
minions.
.sp
The Salt Minion will now look for its config file in \fBc:\esalt\econf\fP by
default. This means that it\(aqs no longer necessary to specify the \fB\-c\fP option
to specify the location of the config file when starting the Salt Minion on
Windows in a terminal.
.SS Muliple Targets for pkg.removed, pkg.purged States
.sp
Both \fBpkg.removed\fP and \fBpkg.purged\fP now support the \fBpkgs\fP argument, which allow for
multiple packages to be targeted in a single state. This, as in
\fBpkg.installed\fP, helps speed up these
states by reducing the number of times that the package management tools (apt,
yum, etc.) need to be run.
.SS Random Times in Cron States
.sp
The temporal parameters in \fBcron.present\fP
states (minute, hour, etc.) can now be randomized by using \fBrandom\fP instead
of a specific value. For example, by using the \fBrandom\fP keyword in the
\fBminute\fP parameter of a cron state, the same cron job can be pushed to
hundreds or thousands of hosts, and they would each use a randomly\-generated
minute. This can be helpful when the cron job accesses a network resource, and
it is not desirable for all hosts to run the job concurrently.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/path/to/cron/script:
cron.present:
\- user: root
\- minute: random
\- hour: 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since Salt assumes a value of \fB*\fP for unspecified temporal parameters, adding
a parameter to the state and setting it to \fBrandom\fP will change that value
from \fB*\fP to a randomized numeric value. However, if that field in the cron
entry on the minion already contains a numeric value, then using the \fBrandom\fP
keyword will not modify it.
.SS Confirmation Prompt on Key Acceptance
.sp
When accepting new keys with \fBsalt\-key \-a minion\-id\fP or \fBsalt\-key \-A\fP,
there is now a prompt that will show the affected keys and ask for confirmation
before proceeding. This prompt can be bypassed using the \fB\-y\fP or \fB\-\-yes\fP
command line argument, as with other \fBsalt\-key\fP commands.
.SS Support for Setting Password Hashes on BSD Minions
.sp
FreeBSD, NetBSD, and OpenBSD all now support setting passwords in
\fBuser.present\fP states.
.SS Salt 0.16.1 Release Notes
.INDENT 0.0
.TP
.B release
2013\-07\-29
.UNINDENT
.SS Salt 0.16.2 Release Notes
.INDENT 0.0
.TP
.B release
2013\-08\-01
.UNINDENT
.sp
Version 0.16.2 is a bugfix release for \fB0.16.0\fP,
and contains a number of fixes.
.SS Windows
.INDENT 0.0
.IP \(bu 2
Only allow Administrator\(aqs group and SYSTEM user access to C:\esalt. This
eliminates a race condition where a non\-admin user could modify a template or
managed file before it is executed by the minion (which is running as an
elevated user), thus avoiding a potential escalation of privileges. (\fI\%issue 6361\fP)
.UNINDENT
.SS Grains
.INDENT 0.0
.IP \(bu 2
Fixed detection of \fBvirtual\fP grain on OpenVZ hardware nodes
.IP \(bu 2
Gracefully handle lsb_release data when it is enclosed in quotes
.IP \(bu 2
LSB grains are now prefixed with \fBlsb_distrib_\fP instead of simply \fBlsb_\fP\&.
The old naming is not preserved, so SLS may be affected.
.IP \(bu 2
Improved grains detection on MacOS
.UNINDENT
.SS Pillar
.INDENT 0.0
.IP \(bu 2
Don\(aqt try to load \fBgit_pillar\fP
if not enabled in master config (\fI\%issue 6052\fP)
.IP \(bu 2
Functions \fBpillar.item\fP and
\fBpillar.items\fP added for parity with
\fBgrains.item\fP/\fBgrains.items\fP\&. The old function \fBpillar.data\fP is preserved
for backwards compatibility.
.IP \(bu 2
Fixed minion traceback when Pillar SLS is malformed (\fI\%issue 5910\fP)
.UNINDENT
.SS Peer Publishing
.INDENT 0.0
.IP \(bu 2
More gracefully handle improperly quoted publish commands (\fI\%issue 5958\fP)
.IP \(bu 2
Fixed traceback when timeout specified via the CLI fo \fBpublish.publish\fP, \fBpublish.full_data\fP (\fI\%issue 5959\fP)
.IP \(bu 2
Fixed unintended change in output of \fBpublish.publish\fP (\fI\%issue 5928\fP)
.UNINDENT
.SS Minion
.INDENT 0.0
.IP \(bu 2
Fixed salt\-key usage in minionswarm script
.IP \(bu 2
Quieted warning about \fBSALT_MINION_CONFIG\fP environment variable on
minion startup and for CLI commands run via \fBsalt\-call\fP (\fI\%issue 5956\fP)
.IP \(bu 2
Added minion config parameter \fBrandom_reauth_delay\fP to stagger
re\-auth attempts when the minion is waiting for the master to approve its
public key. This helps prevent SYN flooding in larger environments.
.UNINDENT
.SS User/Group Management
.INDENT 0.0
.IP \(bu 2
Implement previously\-ignored \fBunique\fP option for \fBuser.present\fP states in FreeBSD
.IP \(bu 2
Report in state output when a \fBgroup.present\fP state attempts to use a gid in use by another
group
.IP \(bu 2
Fixed regression that prevents a \fBuser.present\fP state to set the password hash to the system
default (i.e. an unset password)
.IP \(bu 2
Fixed multiple \fBgroup.present\fP states with
the same group (\fI\%issue 6439\fP)
.UNINDENT
.SS File Management
.INDENT 0.0
.IP \(bu 2
Fixed file.mkdir setting incorrect permissions (\fI\%issue 6033\fP)
.IP \(bu 2
Fixed cleanup of source files for templates when \fB/tmp\fP is in file_roots
(\fI\%issue 6118\fP)
.IP \(bu 2
Fixed caching of zero\-byte files when a non\-empty file was previously cached
at the same path
.IP \(bu 2
Added HTTP authentication support to the cp module (\fI\%issue 5641\fP)
.IP \(bu 2
Diffs are now suppressed when binary files are changed
.UNINDENT
.SS Package/Repository Management
.INDENT 0.0
.IP \(bu 2
Fixed traceback when there is only one target for \fBpkg.latest\fP states
.IP \(bu 2
Fixed regression in detection of virtual packages (apt)
.IP \(bu 2
Limit number of pkg database refreshes to once per \fBstate.sls\fP/\fBstate.highstate\fP
.IP \(bu 2
YUM: Allow 32\-bit packages with arches other than i686 to be managed on
64\-bit systems (\fI\%issue 6299\fP)
.IP \(bu 2
Fixed incorrect reporting in pkgrepo.managed states (\fI\%issue 5517\fP)
.IP \(bu 2
Fixed 32\-bit binary package installs on 64\-bit RHEL\-based distros, and added
proper support for 32\-bit packages on 64\-bit Debian\-based distros
(\fI\%issue 6303\fP)
.IP \(bu 2
Fixed issue where requisites were inadvertently being put into YUM repo files
(\fI\%issue 6471\fP)
.UNINDENT
.SS Service Management
.INDENT 0.0
.IP \(bu 2
Fixed inaccurate reporting of results in \fBservice.running\fP states when the service fails to start
(\fI\%issue 5894\fP)
.IP \(bu 2
Fixed handling of custom initscripts in RHEL\-based distros so that they are
immediately available, negating the need for a second state run to manage the
service that the initscript controls
.UNINDENT
.SS Networking
.INDENT 0.0
.IP \(bu 2
Function network.hwaddr renamed to \fBnetwork.hw_addr\fP to match \fBnetwork.ip_addrs\fP and \fBnetwork.ip_addrs6\fP\&. All three functions also now work without
the underscore in the name, as well.
.IP \(bu 2
Fixed traceback in \fBbridge.show\fP when
interface is not present (\fI\%issue 6326\fP)
.UNINDENT
.SS SSH
.INDENT 0.0
.IP \(bu 2
Fixed incorrect result reporting for some \fBssh_known_hosts.present\fP states
.IP \(bu 2
Fixed inaccurate reporting when \fBssh_auth.present\fP states are run with \fBtest=True\fP, when
rsa/dss is used for the \fBenc\fP param instead of ssh\-rsa/ssh\-dss
(\fI\%issue 5374\fP)
.UNINDENT
.SS pip
.INDENT 0.0
.IP \(bu 2
Properly handle \fB\-f\fP lines in pip freeze output
.IP \(bu 2
Fixed regression in pip.installed states with specifying a requirements file
(\fI\%issue 6003\fP)
.IP \(bu 2
Fixed use of \fBeditable\fP argument in \fBpip.installed\fP states (\fI\%issue 6025\fP)
.IP \(bu 2
Deprecated \fBrunas\fP parameter in execution function calls, in favor of
\fBuser\fP
.UNINDENT
.SS MySQL
.INDENT 0.0
.IP \(bu 2
Allow specification of \fBMySQL\fP
connection arguments via the CLI, overriding/bypassing minion config params
.IP \(bu 2
Allow \fBmysql_user.present\fP states to
set a passwordless login (\fI\%issue 5550\fP)
.IP \(bu 2
Fixed endless loop when \fBmysql.processlist\fP is run (\fI\%issue 6297\fP)
.UNINDENT
.SS PostgreSQL
.INDENT 0.0
.IP \(bu 2
Fixed traceback in \fBpostgres.user_list\fP (\fI\%issue 6352\fP)
.UNINDENT
.SS Miscellaneous
.INDENT 0.0
.IP \(bu 2
Don\(aqt allow \fBnpm states\fP to be used if
\fBnpm module\fP is not available
.IP \(bu 2
Fixed \fBalternatives.install\fP states
for which the target is a symlink (\fI\%issue 6162\fP)
.IP \(bu 2
Fixed traceback in \fBsysbench module\fP (\fI\%issue 6175\fP)
.IP \(bu 2
Fixed traceback in job cache
.IP \(bu 2
Fixed tempfile cleanup for windows
.IP \(bu 2
Fixed issue where SLS files using the \fBpydsl renderer\fP were not being run
.IP \(bu 2
Fixed issue where returners were being passed incorrect information
(\fI\%issue 5518\fP)
.IP \(bu 2
Fixed traceback when numeric args are passed to \fBcmd.script\fP states
.IP \(bu 2
Fixed bug causing \fBcp.get_dir\fP to return more
directories than expected (\fI\%issue 6048\fP)
.IP \(bu 2
Fixed traceback when \fBsupervisord.running\fP states are run with \fBtest=True\fP
(\fI\%issue 6053\fP)
.IP \(bu 2
Fixed tracebacks when Salt encounters problems running rbenv (\fI\%issue 5888\fP)
.IP \(bu 2
Only make the \fBmonit module\fP
available if monit binary is present (\fI\%issue 5871\fP)
.IP \(bu 2
Fixed incorrect behavior of \fBimg.mount_image\fP
.IP \(bu 2
Fixed traceback in \fBtomcat.deploy_war\fP
in Windows
.IP \(bu 2
Don\(aqt re\-write /etc/fstab if mount fails
.IP \(bu 2
Fixed tracebacks when Salt encounters problems running gem (\fI\%issue 5886\fP)
.IP \(bu 2
Fixed incorrect behavior of \fBselinux.boolean\fP states (\fI\%issue 5912\fP)
.IP \(bu 2
\fBRabbitMQ\fP: Quote passwords to
avoid symbols being interpolated by the shell (\fI\%issue 6338\fP)
.IP \(bu 2
Fixed tracebacks in \fBextfs.mkfs\fP and
\fBextfs.tune\fP (\fI\%issue 6462\fP)
.IP \(bu 2
Fixed a regression with the \fBmodule.run\fP state
where the \fBm_name\fP and \fBm_fun\fP arguments were being ignored (\fI\%issue 6464\fP)
.UNINDENT
.SS Salt 0.16.3 Release Notes
.INDENT 0.0
.TP
.B release
2013\-08\-09
.UNINDENT
.sp
Version 0.16.3 is another bugfix release for \fB0.16.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Various documentation fixes
.IP \(bu 2
Fix proc directory regression (\fI\%issue 6502\fP)
.IP \(bu 2
Properly detect \fI\%Linaro\fP Linux (\fI\%issue 6496\fP)
.IP \(bu 2
Fix regressions in \fBmount.mounted\fP
(\fI\%issue 6522\fP, \fI\%issue 6545\fP)
.IP \(bu 2
Skip malformed state requisites (\fI\%issue 6521\fP)
.IP \(bu 2
Fix regression in gitfs from bad import
.IP \(bu 2
Fix for watching prereq states (including recursive requisite error)
(\fI\%issue 6057\fP)
.IP \(bu 2
Fix mod_watch not overriding prereq (\fI\%issue 6520\fP)
.IP \(bu 2
Don\(aqt allow functions which compile states to be called within states
(\fI\%issue 5623\fP)
.IP \(bu 2
Return error for malformed top.sls (\fI\%issue 6544\fP)
.IP \(bu 2
Fix traceback in \fBmysql.query\fP
.IP \(bu 2
Fix regression in binary package installation for 64\-bit packages
on Debian\-based Linux distros (\fI\%issue 6563\fP)
.IP \(bu 2
Fix traceback caused by running \fBcp.push\fP without
having set \fBfile_recv\fP in the master config file
.IP \(bu 2
Fix scheduler configuration in pillar (\fI\%issue 6201\fP)
.UNINDENT
.SS Salt 0.16.4 Release Notes
.INDENT 0.0
.TP
.B release
2013\-09\-07
.UNINDENT
.sp
Version 0.16.4 is another bugfix release for \fB0.16.0\fP, likely to be the last before 0.17.0 is released.
The changes include:
.INDENT 0.0
.IP \(bu 2
Multiple documentation improvements/additions
.IP \(bu 2
Added the \fBosfinger\fP and \fBosarch\fP grains
.IP \(bu 2
Properly handle 32\-bit packages for debian32 on x86_64 (\fI\%issue 6607\fP)
.IP \(bu 2
Fix regression in yum package installation in CentOS 5 (\fI\%issue 6677\fP)
.IP \(bu 2
Fix bug in \fBhg.latest\fP state that would
erroneously delete directories (\fI\%issue 6661\fP)
.IP \(bu 2
Fix bug related to pid not existing for \fBps.top\fP
(\fI\%issue 6679\fP)
.IP \(bu 2
Fix regression in \fBMySQL returner\fP
(\fI\%issue 6695\fP)
.IP \(bu 2
Fix IP addresses grains (\fBipv4\fP and \fBipv6\fP) to include all addresses
(\fI\%issue 6656\fP)
.IP \(bu 2
Fix regression preventing authenticated FTP (\fI\%issue 6733\fP)
.IP \(bu 2
Fix setting password for windows users (\fI\%issue 6824\fP)
.IP \(bu 2
Fix \fBfile.contains\fP on values YAML parses
as non\-string (\fI\%issue 6817\fP)
.IP \(bu 2
Fix \fBfile.get_gid\fP, \fBfile.get_uid\fP, and \fBfile.chown\fP
for broken symlinks (\fI\%issue 6826\fP)
.IP \(bu 2
Fix comment for service reloads in service state (\fI\%issue 6851\fP)
.UNINDENT
.SS Salt 0.17.0 Release Notes
.INDENT 0.0
.TP
.B release
2013\-09\-26
.UNINDENT
.sp
The 0.17.0 release is a very exciting release of Salt, this brings to Salt
some very powerful new features and advances. The advances range from the
state system to the test suite, covering new transport capabilities and
making states easier and more powerful, to extending Salt Virt and much more!
.sp
The 0.17.0 release will also be the last release of Salt to follow the old
0.XX.X numbering system, the next release of Salt will change the numbering to
be date based following this format:
.sp
<Year>.<Month>.<Minor>
.sp
So if the release happens in November of 2013 the number will be 13.11.0, the
first bugfix release will be 13.11.1 and so forth.
.SS Major Features
.SS Halite
.sp
The new Halite web GUI is now available on PyPI. A great deal of work has
been put into Halite to make it fully event driven and amazingly fast. The
Halite UI can be started from within the Salt Master (after being installed
from PyPI), or standalone, and does not require an external database to run.
It is very lightweight!
.sp
This initial release of Halite is primarily the framework for the UI and the
communication systems, making it easy to extend and build the UI up. It
presently supports watching the event bus and firing commands over Salt.
.sp
At this time, Halite is not available as a package, but installation
documentation is available at:
\fI\%http://docs.saltstack.com/topics/tutorials/halite.html\fP
.sp
Halite is, like the rest of Salt, Open Source!
.sp
Much more will be coming in the future of Halite!
.SS Salt SSH
.sp
The new \fBsalt\-ssh\fP command has been added to Salt. This system allows for
remote execution and states to be run over ssh. The benefit here being, that
salt can run relying only on the ssh agent, rather than requiring a minion
to be deployed.
.sp
The \fBsalt\-ssh\fP system runs states in a compatible way as Salt and states
created and run with salt\-ssh can be moved over to a standard salt deployment
without modification.
.sp
Since this is the initial release of salt\-ssh, there is plenty of room for
improvement, but it is fully operational, not just a bootstrap tool.
.SS Rosters
.sp
Salt is designed to have the minions be aware of the master and the master does
not need to be aware of the location of the minions. The new salt roster system
was created and designed to facilitate listing the targets for salt\-ssh.
.sp
The roster system, like most of Salt, is a plugin system, allowing for the list
of systems to target to be derived from any pluggable backend. The rosters
shipping with 0.17.0 are flat and scan. Flat is a file which is read in via the
salt render system and the scan roster does simple network scanning to discover
ssh servers.
.SS State Auto Order
.sp
This is a major change in how states are evaluated in Salt. State Auto Order
is a new feature that makes states get evaluated and executed in the order in
which they are defined in the sls file. This feature makes it very easy to
see the finite order in which things will be executed, making Salt now, fully
imperative AND fully declarative.
.sp
The requisite system still takes precedence over the order in which states are
defined, so no existing states should break with this change. But this new
feature can be turned off by setting \fBstate_auto_order: False\fP in the master
config, thus reverting to the old lexicographical order.
.SS state.sls Runner
.sp
The \fBstate.sls\fP runner has been created to allow for a more powerful system
for orchestrating state runs and function calls across the salt minions. This
new system uses the state system for organizing executions.
.sp
This allows for states to be defined that are executed on the master to call
states on minions via \fBsalt\-run state.sls\fP\&.
.SS Salt Thin
.sp
Salt Thin is an exciting new component of Salt, this is the ability to execute
Salt routines without any transport mechanisms installed, it is a pure python
subset of Salt.
.sp
Salt Thin does not have any networking capability, but can be dropped into any
system with Python installed and then \fBsalt\-call\fP can be called directly. The
Salt Thin system, is used by the \fBsalt\-ssh\fP command, but can still be used to
just drop salt somewhere for easy use.
.SS Event Namespacing
.sp
Events have been updated to be much more flexible. The tags in events have all
been namespaced allowing easier tracking of event names.
.SS Mercurial Fileserver Backend
.sp
The popular git fileserver backend has been joined by the mercurial fileserver
backend, allowing the state tree to be managed entirely via mercurial.
.SS External Logging Handlers
.sp
The external logging handler system allows for Salt to directly hook into any
external logging system. Currently supported are sentry and logstash.
.SS Jenkins Testing
.sp
The testing systems in Salt have been greatly enhanced, tests for salt are now
executed, via jenkins.saltstack.com, across many supported platforms. Jenkins
calls out to salt\-cloud to create virtual machines on Rackspace, then the
minion on the virtual machine checks into the master running on Jenkins where
a state run is executed that sets up the minion to run tests and executes the
test suite.
.sp
This now automates the sequence of running platform tests and allows for
continuous destructive tests to be run.
.SS Salt Testing Project
.sp
The testing libraries for salt have been moved out of the main salt code base
and into a standalone codebase. This has been done to ease the use of the
testing systems being used in salt based projects other than Salt itself.
.SS StormPath External Authentication
.sp
The external auth system now supports the fantastic Stormpath cloud based
authentication system.
.SS LXC Support
.sp
Extensive additions have been added to Salt for LXC support. This included
the backend libs for managing LXC containers. Addition into the salt\-virt
system is still in the works.
.SS Mac OS X User/Group Support
.sp
Salt is now able to manage users and groups on Minions running Mac OS X.
However, at this time user passwords cannot be managed.
.SS Django ORM External Pillar
.sp
Pillar data can now be derived from Django managed databases.
.SS Fixes from RC to release
.INDENT 0.0
.IP \(bu 2
Multiple documentation fixes
.IP \(bu 2
Add multiple source files + templating for \fBfile.append\fP (\fI\%issue 6905\fP)
.IP \(bu 2
Support sysctl configuration files in systemd>=207 (\fI\%issue 7351\fP)
.IP \(bu 2
Add \fBfile.search\fP and \fBfile.replace\fP
.IP \(bu 2
Fix cross\-calling execution functions in provider overrides
.IP \(bu 2
Fix locale override for postgres (\fI\%issue 4543\fP)
.IP \(bu 2
Fix Raspbian identification for service/pkg support (\fI\%issue 7371\fP)
.IP \(bu 2
Fix \fBcp.push\fP file corruption (\fI\%issue 6495\fP)
.IP \(bu 2
Fix ALT Linux password hash specification (\fI\%issue 3474\fP)
.IP \(bu 2
Multiple salt\-ssh\-related fixes and improvements
.UNINDENT
.SS Salt 0.17.1 Release Notes
.INDENT 0.0
.TP
.B release
2013\-10\-17
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
THIS RELEASE IS NOT COMPATIBLE WITH PREVIOUS VERSIONS. If you update your
master to 0.17.1, you must update your minions as well. Sorry for the
inconvenience \-\- this is a result of one of the security fixes listed
below.
.UNINDENT
.UNINDENT
.sp
The 0.17.1 release comes with a number of improvements to salt\-ssh, many
bugfixes, and a number of security updates.
.sp
Salt SSH has been improved to be faster, more featureful and more secure.
Since the original release of Salt SSH was primarily a proof of concept, it has
been very exciting to see its rapid adoption. We appreciate the willingness of
security experts to review Salt SSH and help discover oversights and ensure
that security issues only exist for such a tiny window of time.
.SS SSH Enhancements
.SS Shell Improvements
.sp
Improvements to Salt SSH\(aqs communication have been added that improve routine
execution regardless of the target system\(aqs login shell.
.SS Performance
.sp
Deployment of routines is now faster and takes fewer commands to execute.
.SS Security Updates
.sp
Be advised that these security issues all apply to a small subset of Salt
users and mostly apply to Salt SSH.
.SS Insufficient Argument Validation
.sp
This issue allowed for a user with limited privileges to embed executions
inside of routines to execute routines that should be restricted. This applies
to users using external auth or client ACL and opening up specific routines.
.sp
Be advised that these patches address the direct issue. Additional commits have
been applied to help mitigate this issue from resurfacing.
.SS CVE
.sp
CVE\-2013\-4435
.SS Affected Versions
.sp
0.15.0 \- 0.17.0
.SS Patches
.sp
\fI\%https://github.com/saltstack/salt/commit/6d8ef68b605fd63c36bb8ed96122a75ad2e80269\fP
\fI\%https://github.com/saltstack/salt/commit/ebdef37b7e5d2b95a01d34b211c61c61da67e46a\fP
\fI\%https://github.com/saltstack/salt/commit/7f190ff890e47cdd591d9d7cefa5126574660824\fP
\fI\%https://github.com/saltstack/salt/commit/8e5afe59cef6743fe5dbd510dcf463dbdfca1ced\fP
\fI\%https://github.com/saltstack/salt/commit/aca78f314481082862e96d4f0c1b75fa382bb885\fP
\fI\%https://github.com/saltstack/salt/commit/6a9752cdb1e8df2c9505ea910434c79d132eb1e2\fP
\fI\%https://github.com/saltstack/salt/commit/b73677435ba54ecfc93c1c2d840a7f9ba6f53410\fP
\fI\%https://github.com/saltstack/salt/commit/07972eb0a6f985749a55d8d4a2e471596591c80d\fP
\fI\%https://github.com/saltstack/salt/commit/1e3f197726aa13ac5c3f2416000089f477f489b5\fP
.SS Found By
.sp
Feth Arezki, of Majerti
.SS MITM SSH attack in salt\-ssh
.sp
SSH host keys were being accepted by default and not enforced on future SSH
connections. These patches set SSH host key checking by default and can be
overridden by passing the \-i flag to \fIsalt\-ssh\fP\&.
.SS CVE
.sp
CVE\-2013\-4436
.SS Affected Versions
.sp
0.17.0
.SS Found By
.sp
Michael Scherer, Red Hat
.SS Insecure Usage of /tmp in salt\-ssh
.sp
The initial release of salt\-ssh used the /tmp directory in an insecure way.
These patches not only secure usage of files under /tmp in salt\-ssh, but
also add checksum validation for all packages sent into the now secure
locations on target systems.
.SS CVE
.sp
CVE\-2013\-4438
.SS Affected Versions
.sp
0.17.0
.SS Patches
.sp
\fI\%https://github.com/saltstack/salt/commit/aa4bb77ef230758cad84381dde0ec660d2dc340a\fP
\fI\%https://github.com/saltstack/salt/commit/8f92b6b2cb2e4ec3af8783eb6bf4ff06f5a352cf\fP
\fI\%https://github.com/saltstack/salt/commit/c58e56811d5a50c908df0597a0ba0b643b45ebfd\fP
\fI\%https://github.com/saltstack/salt/commit/0359db9b46e47614cff35a66ea6a6a76846885d2\fP
\fI\%https://github.com/saltstack/salt/commit/4348392860e0fd43701c331ac3e681cf1a8c17b0\fP
\fI\%https://github.com/saltstack/salt/commit/664d1a1cac05602fad2693f6f97092d98a72bf61\fP
\fI\%https://github.com/saltstack/salt/commit/bab92775a576e28ff9db262f32db9cf2375bba87\fP
\fI\%https://github.com/saltstack/salt/commit/c6d34f1acf64900a3c87a2d37618ff414e5a704e\fP
.SS Found By
.sp
Michael Scherer, Red Hat
.SS YAML Calling Unsafe Loading Routine
.sp
It has been argued that this is not a valid security issue, as the YAML loading
that was happening was only being called after an initial gateway filter in
Salt has already safely loaded the YAML and would fail if non\-safe routines
were embedded. Nonetheless, the CVE was filed and patches applied.
.SS CVE
.sp
CVE\-2013\-4438
.SS Patches
.sp
\fI\%https://github.com/saltstack/salt/commit/339b0a51befae6b6b218ebcb55daa9cd3329a1c5\fP
.SS Found By
.sp
Michael Scherer, Red Hat
.SS Failure to Drop Supplementary Group on Salt Master
.sp
If a salt master was started as a non\-root user by the root user, root\(aqs
groups would still be applied to the running process. This fix changes the
process to have only the groups of the running user.
.SS CVE
.sp
CVE not considered necessary by submitter.
.SS Affected Versions
.sp
0.11.0 \- 0.17.0
.SS Patches
.sp
\fI\%https://github.com/saltstack/salt/commit/b89fa9135822d029795ab1eecd68cce2d1ced715\fP
.SS Found By
.sp
Michael Scherer, Red Hat
.SS Failure to Validate Minions Posting Data
.sp
This issue allowed a minion to pose as another authorized minion when posting
data such as the mine data. All minions now pass through the id challenge
before posting such data.
.SS CVE
.sp
CVE\-2013\-4439
.SS Affected Versions
.sp
0.15.0 \- 0.17.0
.SS Patches
.sp
\fI\%https://github.com/saltstack/salt/commit/7b850ff3d07ef6782888914ac4556c01e8a1c482\fP
\fI\%https://github.com/saltstack/salt/commit/151759b2a1e1c6ce29277aa81b054219147f80fd\fP
.SS Found By
.sp
David Anderson
.SS Fix Reference
.sp
Version 0.17.1 is the first bugfix release for \fB0.17.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Fix symbolic links in thin.tgz (\fI\%issue 7482\fP)
.IP \(bu 2
Pass env through to file.patch state (\fI\%issue 7452\fP)
.IP \(bu 2
Service provider fixes and reporting improvements (\fI\%issue 7361\fP)
.IP \(bu 2
Add \fB\-\-priv\fP option for specifying salt\-ssh private key
.IP \(bu 2
Fix salt\-thin\(aqs salt\-call on setuptools installations (\fI\%issue 7516\fP)
.IP \(bu 2
Fix salt\-ssh to support passwords with spaces (\fI\%issue 7480\fP)
.IP \(bu 2
Fix regression in wildcard includes (\fI\%issue 7455\fP)
.IP \(bu 2
Fix salt\-call outputter regression (\fI\%issue 7456\fP)
.IP \(bu 2
Fix custom returner support for startup states (\fI\%issue 7540\fP)
.IP \(bu 2
Fix value handling in augeas (\fI\%issue 7605\fP)
.IP \(bu 2
Fix regression in apt (\fI\%issue 7624\fP)
.IP \(bu 2
Fix minion ID guessing to use \fBsocket.getfqdn()\fP first (\fI\%issue 7558\fP)
.IP \(bu 2
Add minion ID caching (\fI\%issue 7558\fP)
.IP \(bu 2
Fix salt\-key race condition (\fI\%issue 7304\fP)
.IP \(bu 2
Add \fB\-\-include\-all\fP flag to salt\-key (\fI\%issue 7399\fP)
.IP \(bu 2
Fix custom grains in pillar (part of \fI\%issue 5716\fP, \fI\%issue 6083\fP)
.IP \(bu 2
Fix race condition in salt\-key (\fI\%issue 7304\fP)
.IP \(bu 2
Fix regression in minion ID guessing, prioritize \fBsocket.getfqdn()\fP
(\fI\%issue 7558\fP)
.IP \(bu 2
Cache minion ID on first guess (\fI\%issue 7558\fP)
.IP \(bu 2
Allow trailing slash in \fBfile.directory\fP state
.IP \(bu 2
Fix reporting of file_roots in pillar return (\fI\%issue 5449\fP and
\fI\%issue 5951\fP)
.IP \(bu 2
Remove pillar matching for mine.get (\fI\%issue 7197\fP)
.IP \(bu 2
Sanitize args for multiple execution modules
.IP \(bu 2
Fix yumpkg mod_repo functions to filter hidden args (\fI\%issue 7656\fP)
.IP \(bu 2
Fix conflicting IDs in state includes (\fI\%issue 7526\fP)
.IP \(bu 2
Fix mysql_grants.absent string formatting issue (\fI\%issue 7827\fP)
.IP \(bu 2
Fix postgres.version so it won\(aqt return None (\fI\%issue 7695\fP)
.IP \(bu 2
Fix for trailing slashes in mount.mounted state
.IP \(bu 2
Fix rogue AttributErrors in the outputter system (\fI\%issue 7845\fP)
.IP \(bu 2
Fix for incorrect ssh key encodings resulting in incorrect key added
(\fI\%issue 7718\fP)
.IP \(bu 2
Fix for pillar/grains naming regression in python renderer (\fI\%issue 7693\fP)
.IP \(bu 2
Fix args/kwargs handling in the scheduler (\fI\%issue 7422\fP)
.IP \(bu 2
Fix logfile handling for \fIfile://\fP, \fItcp://\fP and \fIudp://\fP (\fI\%issue 7754\fP)
.IP \(bu 2
Fix error handling in config file parsing (\fI\%issue 6714\fP)
.IP \(bu 2
Fix RVM using sudo when running as non\-root user (\fI\%issue 2193\fP)
.IP \(bu 2
Fix client ACL and underlying logging bugs (\fI\%issue 7706\fP)
.IP \(bu 2
Fix scheduler bug with returner (\fI\%issue 7367\fP)
.IP \(bu 2
Fix user management bug related to default groups (\fI\%issue 7690\fP)
.IP \(bu 2
Fix various salt\-ssh bugs (\fI\%issue 7528\fP)
.IP \(bu 2
Many various documentation fixes
.UNINDENT
.SS Salt 0.17.2 Release Notes
.INDENT 0.0
.TP
.B release
2013\-11\-14
.UNINDENT
.sp
Version 0.17.2 is another bugfix release for \fB0.17.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Add ability to delete key with grains.delval (\fI\%issue 7872\fP)
.IP \(bu 2
Fix possible state compiler stack trace (\fI\%issue 5767\fP)
.IP \(bu 2
Fix architecture regression in yumpkg (\fI\%issue 7813\fP)
.IP \(bu 2
Use correct \fBps\fP on Debian to prevent truncating (\fI\%issue 5646\fP)
.IP \(bu 2
Fix grains targeting for new grains (\fI\%issue 5737\fP)
.IP \(bu 2
Fix bug with merging in git_pillar (\fI\%issue 6992\fP)
.IP \(bu 2
Fix print_jobs duplicate results
.IP \(bu 2
Fix apt version specification for pkg.install
.IP \(bu 2
Fix possible KeyError from ext_job_cache missing option
.IP \(bu 2
Fix auto_order for \fB\- names\fP states (\fI\%issue 7649\fP)
.IP \(bu 2
Fix regression in new gitfs installs (directory not found error)
.IP \(bu 2
Fix escape pipe issue on Windows for file.recurse (\fI\%issue 7967\fP)
.IP \(bu 2
Fix fileclient in case of master restart (\fI\%issue 7987\fP)
.IP \(bu 2
Try to output warning if CLI command malformed (\fI\%issue 6538\fP)
.IP \(bu 2
Fix \fB\-\-out=quiet\fP to actually be quiet (\fI\%issue 8000\fP)
.IP \(bu 2
Fix for state.sls in salt\-ssh (\fI\%issue 7991\fP)
.IP \(bu 2
Fix for MySQL grants ordering issue (\fI\%issue 5817\fP)
.IP \(bu 2
Fix traceback for certain missing CLI args (\fI\%issue 8016\fP)
.IP \(bu 2
Add ability to disable lspci queries on master (\fI\%issue 4906\fP)
.IP \(bu 2
Fail if sls defined in topfile does not exist (\fI\%issue 5998\fP)
.IP \(bu 2
Add ability to downgrade MySQL grants (\fI\%issue 6606\fP)
.IP \(bu 2
Fix ssh_auth.absent traceback (\fI\%issue 8043\fP)
.IP \(bu 2
Add upstart detection for Debian/Raspbian (\fI\%issue 8039\fP)
.IP \(bu 2
Fix ID\-related issues (\fI\%issue 8052\fP, \fI\%issue 8050\fP, and others)
.IP \(bu 2
Fix for jinja rendering issues (\fI\%issue 8066\fP and \fI\%issue 8079\fP)
.IP \(bu 2
Fix argument parsing in salt\-ssh (\fI\%issue 7928\fP)
.IP \(bu 2
Fix some GPU detection instances (\fI\%issue 6945\fP)
.IP \(bu 2
Fix bug preventing includes from other environments in SLS files
.IP \(bu 2
Fix for kwargs with dashes (\fI\%issue 8102\fP)
.IP \(bu 2
Fix salt.utils.which for windows \(aq.exe\(aq (\fI\%issue 7904\fP)
.IP \(bu 2
Fix apache.adduser without apachectl (\fI\%issue 8123\fP)
.IP \(bu 2
Fix issue with evaluating \fBtest\fP kwarg in states (\fI\%issue 7788\fP)
.IP \(bu 2
Fix regression in \fBsalt.client.Caller()\fP (\fI\%issue 8078\fP)
.IP \(bu 2
Fix apt\-key silent failure
.IP \(bu 2
Fix bug where cmd.script would try to run even if caching failed (\fI\%issue 7601\fP)
.IP \(bu 2
Fix apt \fBpkg.latest\fP regression (\fI\%issue 8067\fP)
.IP \(bu 2
Fix for mine data not being updated (\fI\%issue 8144\fP)
.IP \(bu 2
Fix for noarch packages in yum
.IP \(bu 2
Fix a Xen detection edge case (\fI\%issue 7839\fP)
.IP \(bu 2
Fix windows \fB__opts__\fP dictionary persistence (\fI\%issue 7714\fP)
.IP \(bu 2
Fix version generation for when it\(aqs part of another git repo (\fI\%issue 8090\fP)
.IP \(bu 2
Fix _handle_iorder stacktrace so that the real syntax error is shown (\fI\%issue 8114\fP and \fI\%issue 7905\fP)
.IP \(bu 2
Fix \fBgit.latest\fP state when a commit SHA is used (\fI\%issue 8163\fP)
.IP \(bu 2
Fix various small bugs in yumpkg.py (\fI\%issue 8201\fP)
.IP \(bu 2
Fix for specifying identify file in git.latest (\fI\%issue 8094\fP)
.IP \(bu 2
Fix for \fB\-\-output\-file\fP CLI arg (\fI\%issue 8205\fP)
.IP \(bu 2
Add ability to specify shutdown time for system.shutdown (\fI\%issue 7833\fP)
.IP \(bu 2
Fix for salt version using non\-salt git repo info (\fI\%issue 8266\fP)
.IP \(bu 2
Add additional hints at impact of \fBpkgrepo\fP states when \fBtest=True\fP (\fI\%issue 8247\fP)
.IP \(bu 2
Fix for salt\-ssh files not being owned by root (\fI\%issue 8216\fP)
.IP \(bu 2
Fix retry logic and error handling in fileserver (related to \fI\%issue 7755\fP)
.IP \(bu 2
Fix file.replace with \fBtest=True\fP (\fI\%issue 8279\fP)
.IP \(bu 2
Add flag for limiting file traversal in fileserver (\fI\%issue 6928\fP)
.IP \(bu 2
Fix for extra mine processes (\fI\%issue 5729\fP)
.IP \(bu 2
Fix for unloading custom modules (\fI\%issue 7691\fP)
.IP \(bu 2
Fix for salt\-ssh opts (\fI\%issue 8005\fP and \fI\%issue 8271\fP)
.IP \(bu 2
Fix compound matcher for grains (\fI\%issue 7944\fP)
.IP \(bu 2
Improve error reporting in ebuild module (related to \fI\%issue 5393\fP)
.IP \(bu 2
Add \fBdir_mode\fP to \fBfile.managed\fP (\fI\%issue 7860\fP)
.IP \(bu 2
Improve traceroute support for FreeBSD and OS X (\fI\%issue 4927\fP)
.IP \(bu 2
Fix for matching minions under syndics (\fI\%issue 7671\fP)
.IP \(bu 2
Improve exception handling for missing ID (\fI\%issue 8259\fP)
.IP \(bu 2
Fix grain mismatch for ScientificLinux (\fI\%issue 8338\fP)
.IP \(bu 2
Add configuration option for minion_id_caching
.IP \(bu 2
Fix open mode auth errors (\fI\%issue 8402\fP)
.UNINDENT
.SS Salt 0.17.3 Release Notes
.INDENT 0.0
.TP
.B release
2013\-12\-08
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
0.17.3 had some regressions which were promptly fixed in the 0.17.4
release. Please use 0.17.4 instead.
.UNINDENT
.UNINDENT
.sp
Version 0.17.3 is another bugfix release for \fB0.17.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Fix some jinja render errors (\fI\%issue 8418\fP)
.IP \(bu 2
Fix \fBfile.replace\fP state changing file ownership (\fI\%issue 8399\fP)
.IP \(bu 2
Fix state ordering with the PyDSL renderer (\fI\%issue 8446\fP)
.IP \(bu 2
Fix for new npm version (\fI\%issue 8517\fP)
.IP \(bu 2
Fix for pip state requiring \fBname\fP even with requirements file (\fI\%issue 8519\fP)
.IP \(bu 2
Fix yum logging to open terminals (\fI\%issue 3855\fP)
.IP \(bu 2
Add sane maxrunning defaults for scheduler (\fI\%issue 8563\fP)
.IP \(bu 2
Fix states duplicate key detection (\fI\%issue 8053\fP)
.IP \(bu 2
Fix SUSE patch level reporting (\fI\%issue 8428\fP)
.IP \(bu 2
Fix managed file creation umask (\fI\%issue 8590\fP)
.IP \(bu 2
Fix logstash exception (\fI\%issue 8635\fP)
.IP \(bu 2
Improve argument exception handling for salt command (\fI\%issue 8016\fP)
.IP \(bu 2
Fix pecl success reporting (\fI\%issue 8750\fP)
.IP \(bu 2
Fix launchctl module exceptions (\fI\%issue 8759\fP)
.IP \(bu 2
Fix argument order in pw_user module
.IP \(bu 2
Add warnings for failing grains (\fI\%issue 8690\fP)
.IP \(bu 2
Fix hgfs problems caused by connections left open (\fI\%issue 8811\fP and \fI\%issue 8810\fP)
.IP \(bu 2
Add Debian iptables default for iptables\-persistent package (\fI\%issue 8889\fP)
.IP \(bu 2
Fix installation of packages with dots in pkg name (\fI\%issue 8614\fP)
.IP \(bu 2
Fix noarch package installation on CentOS 6 (\fI\%issue 8945\fP)
.IP \(bu 2
Fix portage_config.enforce_nice_config (\fI\%issue 8252\fP)
.IP \(bu 2
Fix salt.util.copyfile umask usage (\fI\%issue 8590\fP)
.IP \(bu 2
Fix rescheduling of failed jobs (\fI\%issue 8941\fP)
.IP \(bu 2
Fix pkg on Amazon Linux (uses yumpkg5 now) (\fI\%issue 8226\fP)
.IP \(bu 2
Fix conflicting options in postgres module (\fI\%issue 8717\fP)
.IP \(bu 2
Fix ps modules for psutil >= 0.3.0 (\fI\%issue 7432\fP)
.IP \(bu 2
Fix postgres module to return False on failure (\fI\%issue 8778\fP)
.IP \(bu 2
Fix argument passing for args with pound signs (\fI\%issue 8585\fP)
.IP \(bu 2
Fix pid of salt CLi command showing in status.pid output (\fI\%issue 8720\fP)
.IP \(bu 2
Fix rvm to run gem as the correct user (\fI\%issue 8951\fP)
.IP \(bu 2
Fix namespace issue in win_file module (\fI\%issue 9060\fP)
.IP \(bu 2
Fix masterless state paths on windows (\fI\%issue 9021\fP)
.IP \(bu 2
Fix timeout option in master config (\fI\%issue 9040\fP)
.UNINDENT
.SS Salt 0.17.4 Release Notes
.INDENT 0.0
.TP
.B release
2013\-12\-10
.UNINDENT
.sp
Version 0.17.4 is another bugfix release for \fB0.17.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Fix file.replace bug when replacement str is numeric (\fI\%issue 9101\fP)
.IP \(bu 2
Fix regression in file.managed (\fI\%issue 9131\fP)
.IP \(bu 2
Prevent traceback when job is None. (\fI\%issue 9145\fP)
.UNINDENT
.SS Salt 0.17.5 Release Notes
.INDENT 0.0
.TP
.B release
2014\-01\-27
.UNINDENT
.sp
Version 0.17.5 is another bugfix release for \fB0.17.0\fP\&. The changes include:
.INDENT 0.0
.IP \(bu 2
Fix \fBuser.present\fP states with non\-string fullname (\fI\%issue 9085\fP)
.IP \(bu 2
Fix \fBvirt.init\fP return value on failure (\fI\%issue 6870\fP)
.IP \(bu 2
Fix reporting of \fBfile.blockreplace\fP state when \fBtest=True\fP
.IP \(bu 2
Fix \fBnetwork.interfaces\fP when used in cron (\fI\%issue 7990\fP)
.IP \(bu 2
Fix bug in pkgrepo when switching to/from mirrorlist\-based repo def (\fI\%issue 9121\fP)
.IP \(bu 2
Fix infinite recursion when cache file is corrupted
.IP \(bu 2
Add checking for rev and mirror/bare args in \fBgit.latest\fP (\fI\%issue 9107\fP)
.IP \(bu 2
Add \fBcmd.watch\fP alias (points to \fBcmd.wait\fP) (\fI\%issue 8612\fP)
.IP \(bu 2
Fix stacktrace when prereq is not formed as a list (\fI\%issue 8235\fP)
.IP \(bu 2
Fix stdin issue with lvdisplay command (\fI\%issue 9128\fP)
.IP \(bu 2
Add pre\-check function for range matcher (\fI\%issue 9236\fP)
.IP \(bu 2
Add exception handling for psutil for processes that go missing (\fI\%issue 9274\fP)
.IP \(bu 2
Allow \fB_in\fP requisites to match both on ID and name (\fI\%issue 9061\fP)
.IP \(bu 2
Fix multiple client timeout issues (\fI\%issue 7157\fP and \fI\%issue 9302\fP, probably others)
.IP \(bu 2
Fix \fBZMQError: Operation cannot be accomplished in current state\fP errors (\fI\%issue 6306\fP)
.IP \(bu 2
Multiple optimization in minion auth routines
.IP \(bu 2
Clarify logs for minion ID caching
.UNINDENT
.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 ZeroMQ 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://cloud.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/salt\-git/\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://cloud.github.com/downloads/saltstack/salt/salt\-0.7.0.tar.gz\fP
.sp
Arch Linux Package:
.sp
\fI\%https://aur.archlinux.org/packages/salt\-git/\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://cloud.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/develop/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/develop/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:
\fBWriting 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/develop/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/develop/conf/minion\fP
.SS 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!
.sp
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://cloud.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/develop/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://cloud.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://cloud.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://docs.saltstack.com/\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:
Slides:
\fI\%https://cloud.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://cloud.github.com/downloads/saltstack/salt/salt\-0.8.9.tar.gz\fP
.sp
Or from PyPI:
.sp
\fI\%https://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 \fIinstallation\fP
instructions.
.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 \fBhere\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 \fBmodules documentation\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://www.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
.INDENT 0.0
.TP
.B release
2011\-08\-27
.UNINDENT
.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://cloud.github.com/downloads/saltstack/salt/salt\-0.9.0.tar.gz\fP
.sp
Or from PyPI:
.sp
\fI\%https://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 \fIinstallation\fP
instructions.
.SS New Features
.SS Salt Syndic
.sp
The new \fISyndic interface\fP 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.
.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 \fBPeer
interface\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/develop/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/develop/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.1 Release Notes
.INDENT 0.0
.TP
.B release
2011\-08\-29
.UNINDENT
.SS Salt 0.9.2 Release Notes
.INDENT 0.0
.TP
.B release
2011\-09\-17
.UNINDENT
.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://cloud.github.com/downloads/saltstack/salt/salt\-0.9.2.tar.gz\fP
.sp
Or from PyPI:
.sp
\fI\%https://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 \fIinstallation\fP
instructions.
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt\-call state.highstate
.ft P
.fi
.UNINDENT
.UNINDENT
.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/saltstack/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
.INDENT 0.0
.TP
.B release
2011\-11\-05
.UNINDENT
.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://cloud.github.com/downloads/saltstack/salt/salt\-0.9.3.tar.gz\fP
.sp
Or from PyPI:
.sp
\fI\%https://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 \fIinstallation\fP
instructions.
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- apache
extend:
apache:
service:
\- require:
\- pkg: mod_python
mod_python:
pkg:
\- installed
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- python
python\-mako:
pkg:
\- installed
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
date > /tmp/datestamp:
cron:
\- present
\- user: fred
\- minute: 5
\- hour: 3
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/srv/foo:
file:
\- directory
\- user: root
\- group: root
\- mode: 1755
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B file.symlink
Make a symlink.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/var/lib/www:
file:
\- symlink
\- target: /srv/www
\- force: True
.ft P
.fi
.UNINDENT
.UNINDENT
.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 recurse function is very
powerful and has been tested by pushing out the full Linux kernel source.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/opt/code:
file:
\- recurse
\- source: salt://linux
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B file.absent
Make sure that the file is not on the system, recursively deletes
directories, files and symlinks.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/httpd/conf.d/somebogusfile.conf:
file:
\- absent
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vm.swappiness:
sysctl:
\- present
\- value: 20
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kvm_intel:
kmod:
\- present
.ft P
.fi
.UNINDENT
.UNINDENT
.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.
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.SS Salt 0.9.4 Release Notes
.INDENT 0.0
.TP
.B release
2011\-11\-27
.UNINDENT
.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://cloud.github.com/downloads/saltstack/salt/salt\-0.9.4.tar.gz\fP
.sp
Or from PyPI:
.sp
\fI\%https://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 \fIinstallation\fP
instructions.
.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:
.INDENT 0.0
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg:
\- installed
\- order: 1
.ft P
.fi
.UNINDENT
.UNINDENT
.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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
pkg:
\- installed
\- order: last
.ft P
.fi
.UNINDENT
.UNINDENT
.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
.INDENT 0.0
.TP
.B release
2012\-01\-15
.UNINDENT
.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.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Be sure to \fI\%read the upgrade instructions\fP about the
switch to msgpack before upgrading!
.UNINDENT
.UNINDENT
.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
committers. The following individuals have contributed to the development of
0.9.5:
.INDENT 0.0
.IP \(bu 2
Aaron Bull Schaefer
.IP \(bu 2
Antti Kaihola
.IP \(bu 2
Bas Tichelaar
.IP \(bu 2
Brad Barden
.IP \(bu 2
Brian Wagner
.IP \(bu 2
Byron Clark
.IP \(bu 2
Chris Scheller
.IP \(bu 2
Christer Edwards
.IP \(bu 2
Clint Savage
.IP \(bu 2
Corey Quinn
.IP \(bu 2
David Boucha
.IP \(bu 2
Eivind Uggedal
.IP \(bu 2
Eric Poelke
.IP \(bu 2
Evan Borgstrom
.IP \(bu 2
Jed Glazner
.IP \(bu 2
Jeff Schroeder
.IP \(bu 2
Jeffrey C. Ollie
.IP \(bu 2
Jonas Buckner
.IP \(bu 2
Kent Tenney
.IP \(bu 2
Martin Schnabel
.IP \(bu 2
Maxim Burgerhout
.IP \(bu 2
Mitch Anderson
.IP \(bu 2
Nathaniel Whiteinge
.IP \(bu 2
Seth House
.IP \(bu 2
Thomas S Hatch
.IP \(bu 2
Thomas Schreiber
.IP \(bu 2
Tor Hveem
.IP \(bu 2
lzyeval
.IP \(bu 2
syphernl
.UNINDENT
.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 \fBserial\fP
config value in the master is set to \fBpickle\fP\&. 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 \fBthe suggested methods for upgrading\fP are either to just upgrade
everything at once, or:
.INDENT 0.0
.IP 1. 3
Upgrade the master to 0.9.5
.IP 2. 3
Set \fBserial\fP to \fBpickle\fP in the master config
.IP 3. 3
Upgrade the minions
.IP 4. 3
Remove the \fBserial\fP option from the master config
.UNINDENT
.sp
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
modules can be deployed and used in the same state run.
.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 \fBsalt.modules.saltutil.sync_all\fP\&.
.sp
The directories are named:
.INDENT 0.0
.IP \(bu 2
\fB_modules\fP
.IP \(bu 2
\fB_states\fP
.IP \(bu 2
\fB_grains\fP
.IP \(bu 2
\fB_renderers\fP
.IP \(bu 2
\fB_returners\fP
.UNINDENT
.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 \fBsalt.modules.sys.reload_modules\fP 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 \fBservice state\fP can now
accept \fB\- enable: True\fP to make sure a service is enabled at boot, and \fB\-
enable: False\fP 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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-C \(aqwebserv* and G@os:Debian or E@db.*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will match all minions with ids starting with webserv via a glob and minions
matching the \fBos:Debian\fP grain. Or minions that match the \fBdb.*\fP 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
.INDENT 3.5
.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
.UNINDENT
.UNINDENT
.sp
And then used via the \fB\-N\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-N group1 test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.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 \fB\-Q\fP 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://svnweb.freebsd.org/ports/head/sysutils/py\-salt/\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:
.INDENT 0.0
.IP \(bu 2
Corey
.IP \(bu 2
Aaron Toponce
.IP \(bu 2
and\(ga
.UNINDENT
.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 \fBdata\fP
.sp
The new data module manages a persistent datastore on the minion.
Big thanks to bastichelaar for his help refining this module
.SS \fBfreebsdkmod\fP
.sp
FreeBSD kernel modules can now be managed in the same way Salt handles Linux
kernel modules.
.sp
This module was contributed thanks to the efforts of Christer Edwards
.SS \fBgentoo_service\fP
.sp
Support has been added for managing services in Gentoo. Now Gentoo services
can be started, stopped, restarted, enabled, disabled and viewed.
.SS \fBpip\fP
.sp
The pip module introduces management for pip installed applications.
Thanks goes to whitinge for the addition of the pip module
.SS \fBrh_service\fP
.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 \fBsaltutil\fP
.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 \fBsystemd\fP
.sp
Systemd support has been added to Salt, now systems using this next generation
init system are supported on systems running systemd.
.SS \fBvirtualenv\fP
.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 \fBwin_disk\fP
.sp
Support for gathering disk information on Microsoft Windows minions
The windows modules come courtesy of Utah_Dave
.SS \fBwin_service\fP
.sp
The win_service module adds service support to Salt for Microsoft Windows
services
.SS \fBwin_useradd\fP
.sp
Salt can now manage local users on Microsoft Windows Systems
.SS \fByumpkg5\fP
.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 \fBmysql_database\fP
.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 \fBmysql_user\fP
.sp
The mysql_user state enables mysql user management.
.SS \fBvirtualenv\fP
.sp
The virtualenv state can manage the state of Python virtual environments.
Thanks to Whitinge for the virtualenv state
.SS New Returners
.SS \fBcassandra_returner\fP
.sp
A returner allowing Salt to send data to a cassandra server.
Thanks to Byron Clark for contributing this returner
.SS Salt 0.9.6 Release Notes
.INDENT 0.0
.TP
.B release
2012\-01\-21
.UNINDENT
.sp
Salt 0.9.6 is a release targeting a few bugs and changes. This is primarily
targeting an issue found in the names declaration in the state system. But a
few other bugs were also repaired, like missing support for grains in extmods.
.sp
Due to a conflict in distribution packaging msgpack will no longer be bundled
with Salt, and is required as a dependency.
.SS New Features
.SS HTTP and ftp support in files.managed
.sp
Now under the source option in the file.managed state a HTTP or ftp address
can be used instead of a file located on the salt master.
.SS Allow Multiple Returners
.sp
Now the returner interface can define multiple returners, and will also return
data back to the master, making the process less ambiguous.
.SS Minion Memory Improvements
.sp
A number of modules have been taken out of the minion if the underlying
systems required by said modules are not present on the minion system.
A number of other modules need to be stripped out in this same way which
should continue to make the minion more efficient.
.SS Minions Can Locally Cache Return Data
.sp
A new option, cache_jobs, has been added to the minion to allow for all of the
historically run jobs to cache on the minion, allowing for looking up historic
returns. By default cache_jobs is set to False.
.SS Pure Python Template Support For file.managed
.sp
Templates in the file.managed state can now be defined in a Python script.
This script needs to have a run function that returns the string that needs to
be in the named file.
.SS Salt 0.9.7 Release Notes
.INDENT 0.0
.TP
.B release
2012\-02\-15
.UNINDENT
.sp
Salt 0.9.7 is here! The latest iteration of Salt brings more features and many
fixes. This release is a great refinement over 0.9.6, adding many conveniences
under the hood, as well as some features that make working with Salt much
better.
.sp
A few highlights include the new Job system, refinements to the requisite
system in states, the \fBmod_init\fP interface for states, external node
classification, search path to managed files in the file state, and refinements
and additions to dynamic module loading.
.sp
0.9.7 also introduces the long developed (and oft changed) unit test framework
and the initial unit tests.
.SS Major Features
.SS Salt Jobs Interface
.sp
The new jobs interface makes the management of running executions much cleaner
and more transparent. Building on the existing execution framework the jobs
system allows clear introspection into the active running state of the
running Salt interface.
.sp
The Jobs interface is centered in the new minion side proc system. The
minions now store msgpack serialized files under \fB/var/cache/salt/proc\fP\&.
These files keep track of the active state of processes on the minion.
.SS Functions in the saltutil Module
.sp
A number of functions have been added to the saltutil module to manage and
view the jobs:
.sp
\fBrunning\fP \- Returns the data of all running jobs that are found in the proc
directory.
.sp
\fBfind_job\fP \- Returns specific data about a certain job based on job id.
.sp
\fBsignal_job\fP \- Allows for a given jid to be sent a signal.
.sp
\fBterm_job\fP \- Sends a termination signal (\fBSIGTERM, 15\fP) to the process
controlling the specified job.
.sp
\fBkill_job\fP Sends a kill signal (\fBSIGKILL, 9\fP) to the process controlling the
specified job.
.SS The jobs Runner
.sp
A convenience runner front end and reporting system has been added as well.
The jobs runner contains functions to make viewing data easier and cleaner.
.sp
The jobs runner contains a number of functions...
.SS active
.sp
The active function runs \fBsaltutil.running\fP on all minions and formats the
return data about all running jobs in a much more usable and compact format.
The active function will also compare jobs that have returned and jobs that
are still running, making it easier to see what systems have completed a job
and what systems are still being waited on.
.SS lookup_jid
.sp
When jobs are executed the return data is sent back to the master and cached.
By default is is cached for 24 hours, but this can be configured via the
\fBkeep_jobs\fP option in the master configuration.
.sp
Using the \fBlookup_jid\fP runner will display the same return data that the
initial job invocation with the salt command would display.
.SS list_jobs
.sp
Before finding a historic job, it may be required to find the job id.
\fBlist_jobs\fP will parse the cached execution data and display all of the job
data for jobs that have already, or partially returned.
.SS External Node Classification
.sp
Salt can now use external node classifiers like Cobbler\(aqs
\fBcobbler\-ext\-nodes\fP\&.
.sp
Salt uses specific data from the external node classifier. In particular the
classes value denotes which sls modules to run, and the environment value sets
to another environment.
.sp
An external node classification can be set in the master configuration file via
the \fBexternal_nodes\fP option:
\fI\%http://salt.readthedocs.org/en/latest/ref/configuration/master.html#external\-nodes\fP
.sp
External nodes are loaded in addition to the top files. If it is intended to
only use external nodes, do not deploy any top files.
.SS State Mod Init System
.sp
An issue arose with the pkg state. Every time a package was run Salt would
need to refresh the package database. This made systems with slower package
metadata refresh speeds much slower to work with. To alleviate this issue the
\fBmod_init\fP interface has been added to salt states.
.sp
The \fBmod_init\fP interface is a function that can be added to a state file.
This function is called with the first state called. In the case of the pkg
state, the \fBmod_init\fP function sets up a tag which makes the package database
only refresh on the first attempt to install a package.
.sp
In a nutshell, the \fBmod_init\fP interface allows a state to run any command that
only needs to be run once, or can be used to set up an environment for working
with the state.
.SS Source File Search Path
.sp
The file state continues to be refined, adding speed and capabilities. This
release adds the ability to pass a list to the source option. This list is then
iterated over until the source file is found, and the first found file is used.
.sp
The new syntax looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/httpd/conf/httpd.conf:
file:
\- managed
\- source:
\- salt://httpd/httpd.conf
\- http://myserver/httpd.conf: md5=8c1fe119e6f1fd96bc06614473509bf1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The source option can take sources in the list from the salt file server
as well as an arbitrary web source. If using an arbitrary web source the
checksum needs to be passed as well for file verification.
.SS Refinements to the Requisite System
.sp
A few discrepancies were still lingering in the requisite system, in
particular, it was not possible to have a \fBrequire\fP and a \fBwatch\fP requisite
declared in the same state declaration.
.sp
This issue has been alleviated, as well as making the requisite system run
more quickly.
.SS Initial Unit Testing Framework
.sp
Because of the module system, and the need to test real scenarios, the
development of a viable unit testing system has been difficult, but unit
testing has finally arrived. Only a small amount of unit testing coverage
has been developed, much more coverage will be in place soon.
.sp
A huge thanks goes out to those who have helped with unit testing, and the
contributions that have been made to get us where we are. Without these
contributions unit tests would still be in the dark.
.SS Compound Targets Expanded
.sp
Originally only support for \fBand\fP and \fBor\fP were available in the compound
target. 0.9.7 adds the capability to negate compound targets with \fBnot\fP\&.
.SS Nodegroups in the Top File
.sp
Previously the nodegroups defined in the master configuration file could not
be used to match nodes for states. The nodegroups support has been expanded
and the nodegroups defined in the master configuration can now be used to
match minions in the top file.
.SS Salt 0.9.8 Release Notes
.INDENT 0.0
.TP
.B release
2012\-03\-21
.UNINDENT
.sp
Salt 0.9.8 is a big step forward, with many additions and enhancements, as
well as a number of precursors to advanced future developments.
.sp
This version of Salt adds much more power to the command line, making the
old hard timeout issues a thing of the past and adds keyword argument
support. These additions are also available in the salt client API, making
the available API tools much more powerful.
.sp
The new pillar system allows for data to be stored on the master and
assigned to minions in a granular way similar to the state system. It also
allows flexibility for users who want to keep data out of their state tree
similar to \(aqexternal lookup\(aq functionality in other tools.
.sp
A new way to extend requisites was added, the "requisite in" statement.
This makes adding requires or watch statements to external state decs
much easier.
.sp
Additions to requisites making them much more powerful have been added as well
as improved error checking for sls files in the state system. A new provider
system has been added to allow for redirecting what modules run in the
background for individual states.
.sp
Support for OpenSUSE has been added and support for Solaris has begun
serious development. Windows support has been significantly enhanced as well.
.sp
The matcher and target systems have received a great deal of attention. The
default behavior of grain matching has changed slightly to reflect the rest
of salt and the compound matcher system has been refined.
.sp
A number of impressive features with keyword arguments have been added to both
the CLI and to the state system. This makes states much more powerful and
flexible while maintaining the simple configuration everyone loves.
.sp
The new batch size capability allows for executions to be rolled through a
group of targeted minions a percentage or specific number at a time. This
was added to prevent the "thundering herd" problem when targeting large
numbers of minions for things like service restarts or file downloads.
.SS Upgrade Considerations
.SS Upgrade Issues
.sp
There was a previously missed oversight which could cause a newer minion to
crash an older master. That oversight has been resolved so the version
incompatibility issue will no longer occur. When upgrading to 0.9.8 make
sure to upgrade the master first, followed by the minions.
.SS Debian/Ubuntu Packages
.sp
The original Debian/Ubuntu packages were called salt and included all salt
applications. New packages in the ppa are split by function. If an old salt
package is installed then it should be manually removed and the new split
packages need to be freshly installed.
.sp
On the master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# apt\-get purge salt
# apt\-get install salt\-{master,minion}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On the minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# apt\-get purge salt
# apt\-get install salt\-minion
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And on any Syndics:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# apt\-get install salt\-syndic
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The official Salt PPA for Ubuntu is located at:
\fI\%https://launchpad.net/~saltstack/+archive/salt\fP
.SS Major Features
.SS Pillar
.sp
\fBPillar\fP offers an interface to declare variable data on the master that is then
assigned to the minions. The pillar data is made available to all modules,
states, sls files etc. It is compiled on the master and is declared using the
existing renderer system. This means that learning pillar should be fairly
trivial to those already familiar with salt states.
.SS CLI Additions
.sp
The \fBsalt\fP command has received a serious overhaul and is more powerful
than ever. Data is returned to the terminal as it is received, and the salt
command will now wait for all running minions to return data before stopping.
This makes adding very large \fI\-\-timeout\fP arguments completely unnecessary and
gets rid of long running operations returning empty \fB{}\fP when the timeout is
exceeded.
.sp
When calling salt via sudo, the user originally running salt is saved to the
log for auditing purposes. This makes it easy to see who ran what by just
looking through the minion logs.
.sp
The \fIsalt\-key\fP command gained the \fI\-D\fP and \fI\-\-delete\-all\fP arguments for
removing all keys. Be careful with this one!
.SS Running States Without a Master
.sp
The addition of running states without a salt\-master has been added
to 0.9.8. This feature allows for the unmodified salt state tree to be
read locally from a minion. The result is that the UNMODIFIED state tree
has just become portable, allowing minions to have a local copy of states
or to manage states without a master entirely.
.sp
This is accomplished via the new file client interface in Salt that allows
for the \fBsalt://\fP URI to be redirected to custom interfaces. This means that
there are now two interfaces for the salt file server, calling the master
or looking in a local, minion defined \fBfile_roots\fP\&.
.sp
This new feature can be used by modifying the minion config to point to a
local \fBfile_roots\fP and setting the \fBfile_client\fP option to \fBlocal\fP\&.
.SS Keyword Arguments and States
.sp
State modules now accept the \fB**kwargs\fP argument. This results in all data
in a sls file assigned to a state being made available to the state function.
.sp
This passes data in a transparent way back to the modules executing the logic.
In particular, this allows adding arguments to the \fBpkg.install\fP module that
enable more advanced and granular controls with respect to what the state is
capable of.
.sp
An example of this along with the new debconf module for installing ldap
client packages on Debian:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ldap\-client\-packages:
pkg:
\- debconf: salt://debconf/ldap\-client.ans
\- installed
\- names:
\- nslcd
\- libpam\-ldapd
\- libnss\-ldapd
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Keyword Arguments and the CLI
.sp
In the past it was required that all arguments be passed in the proper order to
the \fIsalt\fP and \fIsalt\-call\fP commands. As of 0.9.8, keyword arguments can be
passed in the form of \fBkwarg=argument\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \-G \(aqtype:dev\(aq git.clone \e
repository=https://github.com/saltstack/salt.git cwd=/tmp/salt user=jeff
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Matcher Refinements and Changes
.sp
A number of fixes and changes have been applied to the Matcher system. The
most noteworthy is the change in the grain matcher. The grain matcher used to
use a regular expression to match the passed data to a grain, but now defaults
to a shell glob like the majority of match interfaces in Salt. A new option
is available that still uses the old style regex matching to grain data called
\fBgrain\-pcre\fP\&. To use regex matching in compound matches use the letter \fIP\fP\&.
.sp
For example, this would match any ArchLinux or Fedora minions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# salt \-\-grain\-pcre \(aqos:(Arch:Fed).*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And the associated compound matcher suitable for \fBtop.sls\fP is \fIP\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
P@os:(Arch|Fed).*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE\fP: Changing the grains matcher from pcre to glob is backwards
incompatible.
.sp
Support has been added for matching minions with Yahoo\(aqs range library. This
is handled by passing range syntax with \fI\-R\fP or \fI\-\-range\fP arguments to salt.
.sp
More information at:
\fI\%https://github.com/ytoolshed/range/wiki/%22yamlfile%22\-module\-file\-spec\fP
.SS Requisite "in"
.sp
A new means to updating requisite statements has been added to make adding
watchers and requires to external states easier. Before 0.9.8 the only way
to extend the states that were watched by a state outside of the sls was to
use an extend statement:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- http
extend:
apache:
service:
\- watch:
\- pkg: tomcat
tomcat:
pkg:
\- installed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
But the new \fBRequisite in\fP statement allows for easier extends for
requisites:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- http
tomcat:
pkg:
\- installed
\- watch_in:
\- service: apache
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Requisite in is part of the extend system, so still remember to always include
the sls that is being extended!
.SS Providers
.sp
Salt predetermines what modules should be mapped to what uses based on the
properties of a system. These determinations are generally made for modules
that provide things like package and service management. The apt module
maps to pkg on Debian and the yum module maps to pkg on Fedora for instance.
.sp
Sometimes in states, it may be necessary for a non\-default module to be used
for the desired functionality. For instance, an Arch Linux system may have
been set up with systemd support. Instead of using the default service module
detected for Arch Linux, the systemd module can be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
http:
service:
\- running
\- enable: True
\- provider: systemd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Default providers can also be defined in the minion config file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
providers:
service: systemd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When default providers are passed in the minion config, then those providers
will be applied to all functionality in Salt, this means that the functions
called by the minion will use these modules, as well as states.
.SS Requisite Glob Matching
.sp
Requisites can now be defined with glob expansion. This means that if there are
many requisites, they can be defined on a single line.
.sp
To watch all files in a directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
http:
service:
\- running
\- enable: True
\- watch:
\- file: /etc/http/conf.d/*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example will watch all defined files that match the glob
\fB/etc/http/conf.d/*\fP
.SS Batch Size
.sp
The new batch size option allows commands to be executed while maintaining that
only so many hosts are executing the command at one time. This option can
take a percentage or a finite number:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq \-b 10 test.ping
salt \-G \(aqos:RedHat\(aq \-\-batch\-size 25% apache.signal restart
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will only run test.ping on 10 of the targeted minions at a time and then
restart apache on 25% of the minions matching \fBos:RedHat\fP at a time and work
through them all until the task is complete. This makes jobs like rolling web
server restarts behind a load balancer or doing maintenance on BSD firewalls
using carp much easier with salt.
.SS Module Updates
.sp
This is a list of notable, but non\-exhaustive updates with new and existing
modules.
.sp
Windows support has seen a flurry of support this release cycle. We\(aqve gained
all new \fBfile\fP,
\fBnetwork\fP, and
\fBshadow\fP modules. Please note
that these are still a work in progress.
.sp
For our ruby users, new \fBrvm\fP and
\fBgem\fP modules have been added along
with the \fBassociated\fP
\fBstates\fP
.sp
The \fBvirt\fP module gained basic Xen support.
.sp
The \fByum\fP module gained
Scientific Linux support.
.sp
The \fBpkg\fP module on Debian, Ubuntu,
and derivatives force apt to run in a non\-interactive mode. This prevents
issues when package installation waits for confirmation.
.sp
A \fBpkg\fP module for OpenSUSE\(aqs
zypper was added.
.sp
The \fBservice\fP module on Ubuntu
natively supports upstart.
.sp
A new \fBdebconf\fP module was
contributed by our community for more advanced control over deb package
deployments on Debian based distributions.
.sp
The \fBmysql.user\fP state and
\fBmysql\fP module gained a
\fIpassword_hash\fP argument.
.sp
The \fBcmd\fP module and state gained
a \fIshell\fP keyword argument for specifying a shell other than \fB/bin/sh\fP on
Linux / Unix systems.
.sp
New \fBgit\fP and
\fBmercurial\fP modules have been added
for fans of distributed version control.
.SS In Progress Development
.SS Master Side State Compiling
.sp
While we feel strongly that the advantages gained with minion side state
compiling are very critical, it does prevent certain features that may be
desired. 0.9.8 has support for initial master side state compiling, but many
more components still need to be developed, it is hoped that these can be
finished for 0.9.9.
.sp
The goal is that states can be compiled on both the master and the minion
allowing for compilation to be split between master and minion. Why will
this be great? It will allow storing sensitive data on the master and sending
it to some minions without all minions having access to it. This will be
good for handling ssl certificates on front\-end web servers for instance.
.SS Solaris Support
.sp
Salt 0.9.8 sees the introduction of basic Solaris support. The daemon runs
well, but grains and more of the modules need updating and testing.
.SS Windows Support
.sp
Salt states on windows are now much more viable thanks to contributions from
our community! States for file, service, local user, and local group management are more fully
fleshed out along with network and disk modules. Windows users can also now manage
registry entries using the new "reg" module.
.SS Salt 0.9.9 Release Notes
.INDENT 0.0
.TP
.B release
2012\-04\-27
.UNINDENT
.sp
0.9.9 is out and comes with some serious bug fixes and even more serious
features. This release is the last major feature release before 1.0.0 and
could be considered the 1.0.0 release candidate.
.sp
A few updates include more advanced kwargs support, the ability for salt
states to more safely configure a running salt minion, better job directory
management and the new state test interface.
.sp
Many new tests have been added as well, including the new minion swarm test
that allows for easier testing of Salt working with large groups of minions.
This means that if you have experienced stability issues with Salt before,
particularly in larger deployments, that these bugs have been tested for,
found, and killed.
.SS Major Features
.SS State Test Interface
.sp
Until 0.9.9 the only option when running states to see what was going to be
changed was to print out the highstate with state.show_highstate and manually
look it over. But now states can be run to discover what is going to be
changed.
.sp
Passing the option \fBtest=True\fP to many of the state functions will now cause
the salt state system to only check for what is going to be changed and report
on those changes.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.highstate test=True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now states that would have made changes report them back in yellow.
.SS State Syntax Update
.sp
A shorthand syntax has been added to sls files, and it will be the default
syntax in documentation going forward. The old syntax is still fully supported
and will not be deprecated, but it is recommended to move to the new syntax in
the future. This change moves the state function up into the state name using
a dot notation. This is in\-line with how state functions are generally referred
to as well:
.sp
The new way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/etc/sudoers:
file.present:
\- source: salt://sudo/sudoers
\- user: root
\- mode: 400
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Use and Use_in Requisites
.sp
Two new requisite statements are available in 0.9.9. The use and use_in
requisite and requisite\-in allow for the transparent duplication of data
between states. When a state "uses" another state it copies the other state\(aqs
arguments as defaults. This was created in direct response to the new network
state, and allows for many network interfaces to be configured in the same way
easily. A simple example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
root_file:
file.absent:
\- name: /tmp/nothing
\- user: root
\- mode: 644
\- group: root
\- use_in:
\- file: /etc/vimrc
fred_file:
file.absent:
\- name: /tmp/nothing
\- user: fred
\- group: marketing
\- mode: 660
/files/marketing/district7.rst:
file.present:
\- source: salt://marketing/district7.rst
\- template: jinja
\- use:
\- file: fred_file
/etc/vimrc:
file.present:
\- source: salt://edit/vimrc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This makes the 2 lower state decs inherit the options from their respectively
"used" state decs.
.SS Network State
.sp
The new network state allows for the configuration of network devices via salt
states and the ip salt module. This addition has been given to the project by
Jeff Hutchins and Bret Palsson from Jive Communications.
.sp
Currently the only network configuration backend available is for Red Hat
based systems, like Red Hat Enterprise, CentOS, and Fedora.
.SS Exponential Jobs
.sp
Originally the jobs executed were stored on the master in the format:
\fB<cachedir>/jobs/jid/{minion ids}\fP
But this format restricted the number of jobs in the cache to the number of
subdirectories allowed on the filesystem. Ext3 for instance limits
subdirectories to 32000. To combat this the new format for 0.9.9 is:
\fB<cachedir>/jobs/jid_hash[:2]/jid_hash[2:]/{minion ids}\fP
So that now the number of maximum jobs that can be run before the cleanup
cycle hits the job directory is substantially higher.
.SS ssh_auth Additions
.sp
The original ssh_auth state was limited to accepting only arguments to apply
to a public key, and the key itself. This was restrictive due to the way the
we learned that many people were using the state, so the key section has been
expanded to accept options and arguments to the key that over ride arguments
passed in the state. This gives substantial power to using ssh_auth with names:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sshkeys:
ssh_auth:
\- present
\- user: backup
\- enc: ssh\-dss
\- options:
\- option1="value1"
\- option2="value2 flag2"
\- comment: backup
\- names:
\- AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0111==
\- AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0222== override
\- ssh\-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0333== override
\- ssh\-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0444==
\- option3="value3",option4="value4 flag4" ssh\-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0555== override
\- option3="value3" ssh\-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAlyE26SMFFVY5YJvnL7AF5CRTPtAigSW1U887ASfBt6FDa7Qr1YdO5ochiLoz8aSiMKd5h4dhB6ymHbmntMPjQena29jQjXAK4AK0500rMShG1Y1HYEjTXjQxIy/SMjq2aycHI+abiVDn3sciQjsLsNW59t48Udivl2RjWG7Eo+LYiB17MKD5M40r5CP2K4B8nuL+r4oAZEHKOJUF3rzA20MZXHRQuki7vVeWcW7ie8JHNBcq8iObVSoruylXav4aKG02d/I4bz/l0UdGh18SpMB8zVnT3YF5nukQQ/ATspmhpU66s4ntMehULC+ljLvZL40ByNmF0TZc2sdSkA0666==
.ft P
.fi
.UNINDENT
.UNINDENT
.SS LocalClient Additions
.sp
To follow up the recent additions in 0.9.8 of additional kwargs support,
0.9.9 also adds the capability to send kwargs into commands via a dict.
This addition to the LocalClient api can be used like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import salt.client
client = salt.client.LocalClient(\(aq/etc/salt/master\(aq)
ret = client.cmd(\(aq*\(aq, \(aqcmd.run\(aq, [\(aqls \-l\(aq], kwarg={\(aqcwd\(aq: \(aq/etc\(aq})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This update has been added to all cmd methods in the LocalClient class.
.SS Better Self Salting
.sp
One problem faced with running Salt states, is that it has been difficult
to manage the Salt minion via states, this is due to the fact that if the
minion is called to restart while a state run is happening then the state
run would be killed. 0.9.9 slightly changes the process scope of the state
runs, so now when salt is executing states it can safely restart the
salt\-minion daemon.
.sp
In addition to daemonizing the state run, the apt module also daemonizes.
This update makes it possible to cleanly update the salt\-minion package on
Debian/Ubuntu systems without leaving apt in an inconsistent state or killing
the active minion process mid\-execution.
.SS Wildcards for SLS Modules
.sp
Now, when including sls modules in include statements or in the top file,
shell globs can be used. This can greatly simplify listing matched sls
modules in the top file and include statements:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
base:
\(aq*\(aq:
\- files*
\- core*
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include:
\- users.dev.*
\- apache.ser*
.ft P
.fi
.UNINDENT
.UNINDENT
.SS External Pillar
.sp
Since the pillar data is just, data, it does not need to come expressly from
the pillar interface. The external pillar system allows for hooks to be added
making it possible to extract pillar data from any arbitrary external
interface. The external pillar interface is configured via the \fBext_pillar\fP
option. Currently interfaces exist to gather external pillar data via hiera
or via a shell command that sends yaml data to the terminal:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ext_pillar:
\- cmd_yaml: cat /etc/salt/ext.yaml
\- hiera: /etc/hirea.yaml
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The initial external pillar interfaces and extra interfaces can be added to
the file salt/pillar.py, it is planned to add more external pillar interfaces.
If the need arises a new module loader interface will be created in the future
to manage external pillar interfaces.
.SS Single State Executions
.sp
The new state.single function allows for single states to be cleanly executed.
This is a great tool for setting up a small group of states on a system or for
testing out the behavior of single states:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.single user.present name=wade uid=2000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The test interface functions here as well, so changes can also be tested
against as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aq*\(aq state.single user.present name=wade uid=2000 test=True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS New Tests
.sp
A few exciting new test interfaces have been added, the minion swarm allows
not only testing of larger loads, but also allows users to see how Salt behaves
with large groups of minions without having to create a large deployment.
.SS Minion Swarm
.sp
The minion swarm test system allows for large groups of minions to be tested
against easily without requiring large numbers of servers or virtual
machines. The minion swarm creates as many minions as a system can handle and
roots them in the /tmp directory and connects them to a master.
.sp
The benefit here is that we were able to replicate issues that happen only
when there are large numbers of minions. A number of elusive bugs which were
causing stability issues in masters and minions have since been hunted down.
Bugs that used to take careful watch by users over several days can now be
reliably replicated in minutes, and fixed in minutes.
.sp
Using the swarm is easy, make sure a master is up for the swarm to connect to,
and then use the minionswarm.py script in the tests directory to spin up
as many minions as you want. Remember, this is a fork bomb, don\(aqt spin up more
than your hardware can handle!
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
python minionswarm.py \-m 20 \-\-master salt\-master
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Shell Tests
.sp
The new Shell testing system allows us to test the behavior of commands
executed from a high level. This allows for the high level testing of salt
runners and commands like salt\-key.
.SS Client Tests
.sp
Tests have been added to test the aspects of the client APIs and ensure that
the client calls work, and that they manage passed data, in a desirable way.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBLegacy salt\-cloud release docs\fP
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\fBLegacy salt\-api release docs\fP
.UNINDENT
.UNINDENT
.SH SALT BASED PROJECTS
.sp
A number of unofficial open source projects, based on Salt, or written to
enhance Salt have been created.
.SS Salt Sandbox
.sp
Created by Aaron Bull Schaefer, aka "elasticdog".
.sp
\fI\%https://github.com/elasticdog/salt\-sandbox\fP
.sp
Salt Sandbox is a multi\-VM Vagrant\-based Salt development environment used
for creating and testing new Salt state modules outside of your production
environment. It\(aqs also a great way to learn firsthand about Salt and its
remote execution capabilities.
.sp
Salt Sandbox will set up three separate virtual machines:
.INDENT 0.0
.IP \(bu 2
salt.example.com \- the Salt master server
.IP \(bu 2
minion1.example.com \- the first Salt minion machine
.IP \(bu 2
minion2.example.com \- the second Salt minion machine
.UNINDENT
.sp
These VMs can be used in conjunction to segregate and test your modules based
on node groups, top file environments, grain values, etc. You can even test
modules on different Linux distributions or release versions to better match
your production infrastructure.
.SH SECURITY DISCLOSURE POLICY
.INDENT 0.0
.TP
.B email
\fI\%security@saltstack.com\fP
.TP
.B gpg key ID
4EA0793D
.TP
.B gpg key fingerprint
\fB8ABE 4EFC F0F4 B24B FF2A AF90 D570 F2D3 4EA0 793D\fP
.UNINDENT
.sp
\fBgpg public key:\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-\-\-\-BEGIN PGP PUBLIC KEY BLOCK\-\-\-\-
Version: GnuPG/MacGPG2 v2.0.22 (Darwin)
mQINBFO15mMBEADa3CfQwk5ED9wAQ8fFDku277CegG3U1hVGdcxqKNvucblwoKCb
hRK6u9ihgaO9V9duV2glwgjytiBI/z6lyWqdaD37YXG/gTL+9Md+qdSDeaOa/9eg
7y+g4P+FvU9HWUlujRVlofUn5Dj/IZgUywbxwEybutuzvvFVTzsn+DFVwTH34Qoh
QIuNzQCSEz3Lhh8zq9LqkNy91ZZQO1ZIUrypafspH6GBHHcE8msBFgYiNBnVcUFH
u0r4j1Rav+621EtD5GZsOt05+NJI8pkaC/dDKjURcuiV6bhmeSpNzLaXUhwx6f29
Vhag5JhVGGNQxlRTxNEM86HEFp+4zJQ8m/wRDrGX5IAHsdESdhP+ljDVlAAX/ttP
/Ucl2fgpTnDKVHOA00E515Q87ZHv6awJ3GL1veqi8zfsLaag7rw1TuuHyGLOPkDt
t5PAjsS9R3KI7pGnhqI6bTOi591odUdgzUhZChWUUX1VStiIDi2jCvyoOOLMOGS5
AEYXuWYP7KgujZCDRaTNqRDdgPd93Mh9JI8UmkzXDUgijdzVpzPjYgFaWtyK8lsc
Fizqe3/Yzf9RCVX/lmRbiEH+ql/zSxcWlBQd17PKaL+TisQFXcmQzccYgAxFbj2r
QHp5ABEu9YjFme2Jzun7Mv9V4qo3JF5dmnUk31yupZeAOGZkirIsaWC3hwARAQAB
tDBTYWx0U3RhY2sgU2VjdXJpdHkgVGVhbSA8c2VjdXJpdHlAc2FsdHN0YWNrLmNv
bT6JAj4EEwECACgFAlO15mMCGwMFCQeGH4AGCwkIBwMCBhUIAgkKCwQWAgMBAh4B
AheAAAoJENVw8tNOoHk9z/MP/2vzY27fmVxU5X8joiiturjlgEqQw41IYEmWv1Bw
4WVXYCHP1yu/1MC1uuvOmOd5BlI8YO2C2oyW7d1B0NorguPtz55b7jabCElekVCh
h/H4ZVThiwqgPpthRv/2npXjIm7SLSs/kuaXo6Qy2JpszwDVFw+xCRVL0tH9KJxz
HuNBeVq7abWD5fzIWkmGM9hicG/R2D0RIlco1Q0VNKy8klG+pOFOW886KnwkSPc7
JUYp1oUlHsSlhTmkLEG54cyVzrTP/XuZuyMTdtyTc3mfgW0adneAL6MARtC5UB/h
q+v9dqMf4iD3wY6ctu8KWE8Vo5MUEsNNO9EA2dUR88LwFZ3ZnnXdQkizgR/Aa515
dm17vlNkSoomYCo84eN7GOTfxWcq+iXYSWcKWT4X+h/ra+LmNndQWQBRebVUtbKE
ZDwKmiQz/5LY5EhlWcuU4lVmMSFpWXt5FR/PtzgTdZAo9QKkBjcv97LYbXvsPI69
El1BLAg+m+1UpE1L7zJT1il6PqVyEFAWBxW46wXCCkGssFsvz2yRp0PDX8A6u4yq
rTkt09uYht1is61joLDJ/kq3+6k8gJWkDOW+2NMrmf+/qcdYCMYXmrtOpg/wF27W
GMNAkbdyzgeX/MbUBCGCMdzhevRuivOI5bu4vT5s3KdshG+yhzV45bapKRd5VN+1
mZRquQINBFO15mMBEAC5UuLii9ZLz6qHfIJp35IOW9U8SOf7QFhzXR7NZ3DmJsd3
f6Nb/habQFIHjm3K9wbpj+FvaW2oWRlFVvYdzjUq6c82GUUjW1dnqgUvFwdmM835
1n0YQ2TonmyaF882RvsRZrbJ65uvy7SQxlouXaAYOdqwLsPxBEOyOnMPSktW5V2U
IWyxsNP3sADchWIGq9p5D3Y/loyIMsS1dj+TjoQZOKSj7CuRT98+8yhGAY8YBEXu
9r3I9o6mDkuPpAljuMc8r09Im6az2egtK/szKt4Hy1bpSSBZU4W/XR7XwQNywmb3
wxjmYT6Od3Mwj0jtzc3gQiH8hcEy3+BO+NNmyzFVyIwOLziwjmEcw62S57wYKUVn
HD2nglMsQa8Ve0e6ABBMEY7zGEGStva59rfgeh0jUMJiccGiUDTMs0tdkC6knYKb
u/fdRqNYFoNuDcSeLEw4DdCuP01l2W4yY+fiK6hAcL25amjzc+yYo9eaaqTn6RAT
bzdhHQZdpAMxY+vNT0+NhP1Zo5gYBMR65Zp/VhFsf67ijb03FUtdw9N8dHwiR2m8
vVA8kO/gCD6wS2p9RdXqrJ9JhnHYWjiVuXR+f755ZAndyQfRtowMdQIoiXuJEXYw
6XN+/BX81gJaynJYc0uw0MnxWQX+A5m8HqEsbIFUXBYXPgbwXTm7c4IHGgXXdwAR
AQABiQIlBBgBAgAPBQJTteZjAhsMBQkHhh+AAAoJENVw8tNOoHk91rcQAIhxLv4g
duF/J1Cyf6Wixz4rqslBQ7DgNztdIUMjCThg3eB6pvIzY5d3DNROmwU5JvGP1rEw
hNiJhgBDFaB0J/y28uSci+orhKDTHb/cn30IxfuAuqrv9dujvmlgM7JUswOtLZhs
5FYGa6v1RORRWhUx2PQsF6ORg22QAaagc7OlaO3BXBoiE/FWsnEQCUsc7GnnPqi7
um45OJl/pJntsBUKvivEU20fj7j1UpjmeWz56NcjXoKtEvGh99gM5W2nSMLE3aPw
vcKhS4yRyLjOe19NfYbtID8m8oshUDji0XjQ1z5NdGcf2V1YNGHU5xyK6zwyGxgV
xZqaWnbhDTu1UnYBna8BiUobkuqclb4T9k2WjbrUSmTwKixokCOirFDZvqISkgmN
r6/g3w2TRi11/LtbUciF0FN2pd7rj5mWrOBPEFYJmrB6SQeswWNhr5RIsXrQd/Ho
zvNm0HnUNEe6w5YBfA6sXQy8B0Zs6pcgLogkFB15TuHIIIpxIsVRv5z8SlEnB7HQ
Io9hZT58yjhekJuzVQB9loU0C/W0lzci/pXTt6fd9puYQe1DG37pSifRG6kfHxrR
if6nRyrfdTlawqbqdkoqFDmEybAM9/hv3BqriGahGGH/hgplNQbYoXfNwYMYaHuB
aSkJvrOQW8bpuAzgVyd7TyNFv+t1kLlfaRYJ
=wBTJ
\-\-\-\-\-END PGP PUBLIC KEY BLOCK\-\-\-\-\-
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The SaltStack Security Team is available at \fI\%security@saltstack.com\fP for
security\-related bug reports or questions.
.sp
We request the disclosure of any security\-related bugs or issues be reported
non\-publicly until such time as the issue can be resolved and a security\-fix
release can be prepared. At that time we will release the fix and make a public
announcement with upgrade instructions and download locations.
.SS Security response procedure
.sp
SaltStack takes security and the trust of our customers and users very
seriously. Our disclosure policy is intended to resolve security issues as
quickly and safely as is possible.
.INDENT 0.0
.IP 1. 3
A security report sent to \fI\%security@saltstack.com\fP is assigned to a team
member. This person is the primary contact for questions and will
coordinate the fix, release, and announcement.
.IP 2. 3
The reported issue is reproduced and confirmed. A list of affected projects
and releases is made.
.IP 3. 3
Fixes are implemented for all affected projects and releases that are
actively supported. Back\-ports of the fix are made to any old releases that
are actively supported.
.IP 4. 3
Packagers are notified via the \fI\%salt\-packagers\fP mailing list that an issue
was reported and resolved, and that an announcement is incoming.
.IP 5. 3
A new release is created and pushed to all affected repositories. The
release documentation provides a full description of the issue, plus any
upgrade instructions or other relevant details.
.IP 6. 3
An announcement is made to the \fI\%salt\-users\fP and \fI\%salt\-announce\fP mailing
lists. The announcement contains a description of the issue and a link to
the full release documentation and download locations.
.UNINDENT
.SS Receiving security announcemnts
.sp
The fastest place to receive security announcements is via the \fI\%salt\-announce\fP
mailing list. This list is low\-traffic.
.SH FREQUENTLY ASKED QUESTIONS
.SS FAQ
.INDENT 0.0
.IP \(bu 2
\fI\%Frequently Asked Questions\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Is Salt open\-core?\fP
.IP \(bu 2
\fI\%What ports should I open on my firewall?\fP
.IP \(bu 2
\fI\%I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly)\fP
.IP \(bu 2
\fI\%My script runs every time I run a state.highstate. Why?\fP
.IP \(bu 2
\fI\%When I run test.ping, why don\(aqt the Minions that aren\(aqt responding return anything? Returning False would be helpful.\fP
.IP \(bu 2
\fI\%How does Salt determine the Minion\(aqs id?\fP
.IP \(bu 2
\fI\%I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why?\fP
.IP \(bu 2
\fI\%I\(aqm using gitfs and my custom modules/states/etc are not syncing. Why?\fP
.IP \(bu 2
\fI\%Why aren\(aqt my custom modules/states/etc. available on my Minions?\fP
.IP \(bu 2
\fI\%Module X isn\(aqt available, even though the shell command it uses is installed. Why?\fP
.IP \(bu 2
\fI\%Can I run different versions of Salt on my Master and Minion?\fP
.IP \(bu 2
\fI\%Does Salt support backing up managed files?\fP
.IP \(bu 2
\fI\%What is the best way to restart a Salt daemon using Salt?\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Linux/Unix\fP
.IP \(bu 2
\fI\%Windows\fP
.UNINDENT
.IP \(bu 2
\fI\%Salting the Salt Master\fP
.UNINDENT
.UNINDENT
.SS Is Salt open\-core?
.sp
No. Salt is 100% committed to being open\-source, including all of our APIs and
the \fI\%\(aqHalite\(aq web interface\fP which was introduced in version 0.17.0. It is
developed under the \fI\%Apache 2.0 license\fP, allowing it to be used in both open
and proprietary projects.
.SS What ports should I open on my firewall?
.sp
Minions need to be able to connect to the Master on TCP ports 4505 and 4506.
Minions do not need any inbound ports open. More detailed information on
firewall settings can be found \fBhere\fP\&.
.SS I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly)
.sp
This is often caused by SELinux. Try disabling SELinux or putting it in
permissive mode and see if the weird behavior goes away.
.SS My script runs every time I run a \fIstate.highstate\fP\&. Why?
.sp
You are probably using \fBcmd.run\fP rather than
\fBcmd.wait\fP\&. A \fBcmd.wait\fP state will only run when there has been a change in a
state that it is watching.
.sp
A \fBcmd.run\fP state will run the corresponding command
\fIevery time\fP (unless it is prevented from running by the \fBunless\fP or \fBonlyif\fP
arguments).
.sp
More details can be found in the documentation for the \fBcmd\fP states.
.SS When I run \fItest.ping\fP, why don\(aqt the Minions that aren\(aqt responding return anything? Returning \fBFalse\fP would be helpful.
.sp
When you run \fItest.ping\fP the Master tells Minions to run commands/functions,
and listens for the return data, printing it to the screen when it is received.
If it doesn\(aqt receive anything back, it doesn\(aqt have anything to display for
that Minion.
.sp
There are a couple options for getting information on Minions that are not
responding. One is to use the verbose (\fB\-v\fP) option when you run salt
commands, as it will display "Minion did not return" for any Minions which time
out.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-v \(aq*\(aq pkg.install zsh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Another option is to use the \fBmanage.down\fP
runner:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run manage.down
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Also, if the Master is under heavy load, it is possible that the CLI will exit
without displaying return data for all targeted Minions. However, this doesn\(aqt
mean that the Minions did not return; this only means that the Salt CLI timed
out waiting for a response. Minions will still send their return data back to
the Master once the job completes. If any expected Minions are missing from the
CLI output, the \fBjobs.list_jobs\fP runner can
be used to show the job IDs of the jobs that have been run, and the
\fBjobs.lookup_jid\fP runner can be used to get
the return data for that job.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-run jobs.list_jobs
salt\-run jobs.lookup_jid 20130916125524463507
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you find that you are often missing Minion return data on the CLI, only to
find it with the jobs runners, then this may be a sign that the
\fBworker_threads\fP value may need to be increased in the master
config file. Additionally, running your Salt CLI commands with the \fB\-t\fP
option will make Salt wait longer for the return data before the CLI command
exits. For instance, the below command will wait up to 60 seconds for the
Minions to return:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt \-t 60 \(aq*\(aq test.ping
.ft P
.fi
.UNINDENT
.UNINDENT
.SS How does Salt determine the Minion\(aqs id?
.sp
If the Minion id is not configured explicitly (using the \fBid\fP
parameter), Salt will determine the id based on the hostname. Exactly how this
is determined varies a little between operating systems and is described in
detail \fIhere\fP\&.
.SS I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why?
.sp
Salt detects the Minion\(aqs operating system and assigns the correct package or
service management module based on what is detected. However, for certain custom
spins and OS derivatives this detection fails. In cases like this, an issue
should be opened on our \fI\%tracker\fP, with the following information:
.INDENT 0.0
.IP 1. 3
The output of the following command:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
salt <minion_id> grains.items | grep os
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
The contents of \fB/etc/lsb\-release\fP, if present on the Minion.
.UNINDENT
.SS I\(aqm using gitfs and my custom modules/states/etc are not syncing. Why?
.sp
In versions of Salt 0.16.3 or older, there is a bug in \fBgitfs\fP which can affect the syncing of custom types.
Upgrading to 0.16.4 or newer will fix this.
.SS Why aren\(aqt my custom modules/states/etc. available on my Minions?
.sp
Custom modules are only synced to Minions when \fBstate.highstate\fP, \fBsaltutil.sync_modules\fP, or \fBsaltutil.sync_all\fP is run. Similarly, custom states are only
synced to Minions when \fBstate.highstate\fP,
\fBsaltutil.sync_states\fP, or
\fBsaltutil.sync_all\fP is run.
.sp
Other custom types (renderers, outputters, etc.) have similar behavior, see the
documentation for the \fBsaltutil\fP module for more
information.
.SS Module \fBX\fP isn\(aqt available, even though the shell command it uses is installed. Why?
.sp
This is most likely a PATH issue. Did you custom\-compile the software which the
module requires? RHEL/CentOS/etc. in particular override the root user\(aqs path
in \fB/etc/init.d/functions\fP, setting it to \fB/sbin:/usr/sbin:/bin:/usr/bin\fP,
making software installed into \fB/usr/local/bin\fP unavailable to Salt when the
Minion is started using the initscript. In version 2014.1.0, Salt will have a
better solution for these sort of PATH\-related issues, but recompiling the
software to install it into a location within the PATH should resolve the
issue in the meantime. Alternatively, you can create a symbolic link within the
PATH using a \fBfile.symlink\fP state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/usr/bin/foo:
file.symlink:
\- target: /usr/local/bin/foo
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Can I run different versions of Salt on my Master and Minion?
.sp
This depends on the versions. In general, it is recommended that Master and
Minion versions match.
.sp
When upgrading Salt, the master(s) should always be upgraded first. Backwards
compatibility for minions running newer versions of salt than their masters is
not guaranteed.
.sp
Whenever possible, backwards compatibility between new masters
and old minions will be preserved. Generally, the only exception to this
policy is in case of a security vulnerability.
.sp
Recent examples of backwards compatibility breakage include the 0.17.1 release
(where all backwards compatibility was broken due to a security fix), and the
2014.1.0 release (which retained compatibility between 2014.1.0 masters and
0.17 minions, but broke compatibility for 2014.1.0 minions and older masters).
.SS Does Salt support backing up managed files?
.sp
Yes. Salt provides an easy to use addition to your file.managed states that
allow you to back up files via \fBbackup_mode\fP,
backup_mode can be configured on a per state basis, or in the minion config
(note that if set in the minion config this would simply be the default
method to use, you still need to specify that the file should be backed up!).
.SS What is the best way to restart a Salt daemon using Salt?
.sp
Restarting Salt using Salt without having the restart interrupt the whole
process is a tricky problem to solve. We\(aqre still working on it but in the
meantime a good way is to use the system scheduler with a short interval. The
following example is a state that will always execute at the very end of a
state run.
.SS Linux/Unix
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-minion\-reload:
cmd.run:
\- name: echo service salt\-minion restart | at now + 1 minute
\- order: last
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To ensure that \fBat\fP is installed and \fBatd\fP is running, the following states
can be used (be sure to double\-check the package name and service name for the
distro the minion is running, in case they differ from the example below.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
at:
pkg.installed:
\- name: at
service.running:
\- name: atd
\- enable: True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
An alternatvie to using the \fBatd\fP daemon is to fork and disown the
process.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
restart_minion:
cmd.run:
\- name: |
nohup /bin/sh \-c \(aqsleep 10 && salt\-call \-\-local service.restart salt\-minion\(aq
\- python_shell: True
\- order: last
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Windows
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
schedule\-start:
cmd.run:
\- name: at (Get\-Date).AddMinutes(1).ToString("HH:mm") cmd /c "net start salt\-minion"
\- shell: powershell
\- order: last
service.dead:
\- name: salt\-minion
\- require:
\- cmd: schedule\-start
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Salting the Salt Master
.sp
In order to configure a master server via states, the Salt master can also be
"salted" in order to enforce state on the Salt master as well as the Salt
minions. Salting the Salt master requires a Salt minion to be installed on
the same machine as the Salt master. Once the Salt minion is installed, the
minion configuration file must be pointed to the local Salt master:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
master: 127.0.0.1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Once the Salt master has been "salted" with a Salt minion, it can be targeted
just like any other minion. If the minion on the salted master is running, the
minion can be targeted via any usual \fBsalt\fP command. Additionally, the
\fBsalt\-call\fP command can execute operations to enforce state on the salted
master without requiring the minion to be running.
.sp
More information about salting the Salt master can be found in the salt\-formula
for salt itself:
.sp
\fI\%https://github.com/saltstack\-formulas/salt\-formula\fP
.SH GLOSSARY
.INDENT 0.0
.TP
.B Auto\-Order
The evaluation of states in the order that they are defined in a SLS
file. \fISee also\fP: \fIordering\fP\&.
.TP
.B Bootstrap
A stand\-alone Salt project which can download and install a Salt master
and/or a Salt minion onto a host. \fISee also\fP: \fIsalt\-bootstrap
<https://github.com/saltstack/salt\-bootstrap>\fP\&.
.TP
.B Compound Matcher
A combination of many target definitions that can be combined with
boolean operators. \fISee also\fP: \fItargeting\fP\&.
.TP
.B EAuth
Shorthand for \(aqexternal authentication\(aq. A system for calling to a
system outside of Salt in order to authenticate users and determine if
they are allowed to issue particular commands to Salt. \fISee also\fP:
\fIexternal auth\fP\&.
.TP
.B Environment
A directory tree containing state files which can be applied to
minions. \fISee also\fP: \fItop file\fP\&.
.TP
.B Execution Module
A Python module that contains execution functions which directly
perform various system\-management tasks on a server. Salt ships with a
number of execution modules but users can also write their own
execution modules to perform specialized tasks. \fISee also\fP: \fIthe
list of execution modules\fP\&.
.TP
.B Execution Function
A Python function inside an Execution Module that may take arguments
and performs specific system\-management tasks. \fISee also\fP: \fIthe
list of execution modules\fP\&.
.TP
.B External Job Cache
An external data\-store that can archive information about jobs that
have been run. A default returner. \fISee also\fP:
\fBext_job_cache\fP, \fIthe list of returners\fP\&.
.TP
.B External Pillar
A module that accepts arbitrary arguments and returns a dictionary.
The dictionary is automatically added to a pillar for a minion.
.TP
.B Event
A notice emitted onto an event bus. Events are often driven by requests
for actions to occur on a minion or master and the results of those
actions. \fISee also\fP: \fISalt Reactor\fP\&.
.TP
.B File Server
A local or remote location for storing both Salt\-specific files such as
top files or SLS files as well as files that can be distributed to
minions, such as system configuration files. \fISee also\fP: \fISalt\(aqs
file server\fP\&.
.TP
.B Grain
A key\-value pair which contains a fact about a system, such as its
hostname, network addresses. \fISee also\fP: \fItargeting with grains\fP\&.
.TP
.B Halite
The Salt GUI. \fISee also\fP: \fI\%Halite\fP\&.
.TP
.B Jinja
A templating language which allows variables and simple logic to be
dynamically inserted into static text files when they are rendered.
\fISee also\fP: \fBSalt\(aqs Jinja documentation\fP\&.
.TP
.B Job
The complete set of tasks to be performed by the execution of a Salt
command are a single job. \fISee also\fP: \fBjobs runner\fP\&.
.TP
.B Job ID
A unique identifier to represent a given \fI\%job\fP\&.
.TP
.B Highdata
The data structure in a SLS file the represents a set of state
declarations. \fISee also\fP: \fIstate layers\fP\&.
.TP
.B Highstate
The collection of states to be applied to a system. \fISee also\fP:
\fIstate layers\fP\&.
.TP
.B Low State
The collection of processed states after requisites and order are
evaluated. \fISee also\fP: \fIstate layers\fP\&.
.TP
.B Master
A central Salt daemon which from which commands can be issued to
listening minions.
.TP
.B Masterless
A minion which does not require a Salt master to operate. All
configuration is local. \fISee also\fP: \fBfile_client\fP\&.
.TP
.B Master Tops
A system for the master that allows hooks into external systems to
generate top file data.
.TP
.B Mine
A facility to collect arbitrary data from minions and store that data
on the master. This data is then available to all other minions.
[Sometimes referred to as Salt Mine.] \fISee also\fP: \fISalt Mine\fP\&.
.TP
.B Minion
A server running a Salt minion daemon which can listen to commands from
a master and perform the requested tasks. Generally, minions are
servers which are to be controlled using Salt.
.TP
.B Minion ID
A globally unique identifier for a minion. \fISee also\fP:
\fBid\fP\&.
.TP
.B Multi\-Master
The ability for a minion to be actively connected to multiple Salt
masters at the same time in high\-availability environments.
.TP
.B Node Group
A pre\-defined group of minions declared in the master configuration
file. \fISee also\fP: \fItargeting\fP\&.
.TP
.B Outputter
A formatter for defining the characteristics of output data from a Salt
command. \fISee also\fP: \fIlist of outputters\fP\&.
.TP
.B Overstate
A system by which a Master can issue function calls to minions in a
deterministic order. \fISee also\fP: \fIoverstate\fP\&.
.TP
.B Peer Communication
The ability for minions to communicate directly with other minions
instead of brokering commands through the Salt master. \fISee also\fP:
\fIpeer communication\fP\&.
.TP
.B Pillar
A simple key\-value store for user\-defined data to be made available to
a minion. Often used to store and distribute sensitive data to minions.
\fISee also\fP: \fIPillar\fP, \fIlist of Pillar
modules\fP\&.
.TP
.B Proxy Minion
A minion which can control devices that are unable to run a Salt minion
locally, such as routers and switches.
.TP
.B PyDSL
A Pythonic domain\-specific\-language used as a Salt renderer. PyDSL can
be used in cases where adding pure Python into SLS files is beneficial.
\fISee also\fP: \fBPyDSL\fP\&.
.TP
.B Reactor
An interface for listening to events and defining actions that Salt
should taken upon receipt of given events. \fISee also\fP: \fIReactor\fP\&.
.TP
.B Render Pipe
Allows SLS files to be rendered by multiple renderers, with each
renderer receiving the output of the previous. \fISee also\fP:
\fIcomposing renderers\fP\&.
.TP
.B Renderer
Responsible for translating a given data serialization format such as
YAML or JSON into a Python data structure that can be consumed by Salt.
\fISee also\fP: \fIlist of renderers\fP\&.
.TP
.B Returner
Allows for the results of a Salt command to be sent to a given
data\-store such as a database or log file for archival. \fISee also\fP:
\fIlist of returners\fP\&.
.TP
.B Roster
A flat\-file list of target hosts. (Currently only used by salt\-ssh.)
.TP
.B Runner Module
A module containing a set of runner functions. \fISee also\fP: \fIlist
of runner modules\fP\&.
.TP
.B Runner Function
A function which is is called by the \fBsalt\-run\fP command and
executes on the master instead of on a minion. \fISee also\fP:
\fI\%Runner Module\fP\&.
.TP
.B Salt Cloud
A suite of tools used to create and deploy systems on many hosted cloud
providers. \fISee also\fP: \fIsalt\-cloud\fP\&.
.TP
.B Salt SSH
A configuration management and remote orchestration system that does
not require that any software besides SSH be installed on systems to be
controlled.
.TP
.B Salt Thin
A subset of the normal Salt distribution that does not include any
transport routines. A Salt Thin bundle can be dropped onto a host and
used directly without any requirement that the host be connected to a
network. Used by Salt SSH. \fISee also\fP: \fBthin runner\fP\&.
.TP
.B Salt Virt
Used to manage the creation and deployment of virtual machines onto a
set of host machines. Often used to create and deploy private clouds.
\fISee also\fP: \fBvirt runner\fP\&.
.TP
.B SLS Module
Contains a set of \fI\%state declarations\fP\&.
.TP
.B State Declaration
A data structure which contains a unique ID and describes one or more
states of a system such as ensuring that a package is installed or a
user is defined. \fISee also\fP: \fIhighstate structure\fP\&.
.TP
.B State Module
A module which contains a set of state functions. \fISee also\fP:
\fIlist of state modules\fP\&.
.TP
.B State Function
A function contained inside a \fI\%state module\fP which
can manages the application of a particular state to a system. State
functions frequently call out to one or more \fI\%execution modules\fP to perform a given task.
.TP
.B State Run
The application of a set of states on a set of systems.
.TP
.B State Compiler
Translates \fI\%highdata\fP into lowdata.
.TP
.B Syndic
A forwarder which can relay messages between tiered masters. \fBSee
also\fP: \fISyndic\fP\&.
.TP
.B Target
Minion(s) to which a given salt command will apply. \fISee also\fP:
\fItargeting\fP\&.
.TP
.B Top File
Determines which SLS files should be applied to various systems and
organizes those groups of systems into environments. \fISee also\fP:
\fItop file\fP, \fIlist of master top modules\fP\&.
.TP
.B Worker
A master process which can send notices and receive replies from
minions. \fISee also\fP: \fBworker_threads\fP\&.
.TP
.B __virtual__
A function in a module that is called on module load to determine
whether or not the module should be available to a minion. This
function commonly contains logic to determine if all requirements
for a module are available, such as external libraries.
.UNINDENT
.SH AUTHOR
Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2014 SaltStack, Inc.
.\" Generated by docutils manpage writer.
.
Reference in New Issue View Git Blame Copy Permalink