valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-07 17:09:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge branch '0.9.8' of git://github.com/saltstack/salt into networkstate

Browse Source 
Conflicts:
	doc/ref/modules/all/index.rst
This commit is contained in:
Jeff Hutchins 2012-04-03 10:25:30 -06:00
commit 63393e98ef
228 changed files with 20258 additions and 3477 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
MANIFEST.in
View File

@ -1,3 +1,11 @@
include AUTHORS
include LICENSE
include README.rst
include requirements.txt
include tests/*.py
recursive-include tests *.py
include tests/integration/modules/files/*
include tests/integration/files/*
include tests/integration/tmp/_README
include tests/unit/templates/files/*
recursive-include doc *

54
README.rst
View File

@ -11,8 +11,8 @@ Salt is a distributed remote execution system used to execute commands and
query data. It was developed in order to bring the best solutions found in the
world of remote execution together and make them better, faster and more
malleable. Salt accomplishes this via its ability to handle larger loads of
information, and not just dozens, but hundreds or even thousands of individual
servers, handle them quickly and through a simple and manageable interface.
information, and not just dozens, but hundreds, or even thousands of individual
servers. It handles them quickly and through a simple yet manageable interface.
Simplicity
==========
@ -30,53 +30,55 @@ Parallel Execution
==================
The core function of Salt is to enable remote commands to be called in parallel
rather than in serial, to use a secure and encrypted protocol, the smallest and
fastest network payloads possible, and with a simple programmer interface. Salt
also introduces more granular controls to the realm of remote execution,
rather than in serial. It does this over a secure and encrypted protocol using
the smallest and fastest network payloads possible. All of this is possible
and salt still manages to have a simple interface for developers. Salt also
introduces more granular controls to the realm of remote execution,
allowing for commands to be executed in parallel and for systems to be targeted
based on more than just hostname, but by system properties.
based on more than just hostname, but by live system properties.
Building on Proven Technology
=============================
Salt takes advantage of a number of technologies and techniques. The networking
layer is built with the excellent `ZeroMQ`_ networking library, so Salt itself
contains a viable, and transparent, AMQ broker inside the daemon. Salt uses
layer is built with the excellent `ZeroMQ`_ networking library. Salt itself
contains a viable, and transparent, 0MQ broker inside the daemon. Salt uses
public keys for authentication with the master daemon, then uses faster AES
encryption for payload communication, this means that authentication and
encryption for payload communication. This means that authentication and
encryption are also built into Salt. Salt takes advantage of communication via
Python pickles, enabling fast and light network traffic.
the most excellent `msgpack`_ library, enabling fast and light network traffic.
.. _`ZeroMQ`: http://www.zeromq.org/
.. _`msgpack`: http://msgpack.org/
Python Client Interface
=======================
In order to allow for simple expansion, Salt execution routines can be written
as plain Python modules and the data collected from Salt executions can be sent
back to the master server, or to any arbitrary program. Salt can be called from
a simple Python API, or from the command line, so that Salt can be used to
execute one-off commands as well as operate as an integral part of a larger
application.
Salt execution routines can be written as plain Python modules and the data
collected from execution can be sent back to the master server, or any
arbitrary program. Salt can be called from a simple Python API, or from the
command line. This makes it easy to execute one-off commands as well as
operate as an integral part of a larger application.
Fast, Flexible, Scalable, Secure
================================
The result is a system that can execute commands across groups of
varying size, from very few to very many servers at considerably high
speed. A system that is very fast, easy to set up and amazingly
malleable, able to suit the needs of any number of servers working
within the same system. Salt’s unique architecture brings together the
best of the remote execution world, amplifies its capabilities and
expands its range, resulting in this system that is as versatile as it
is practical, able to suit any network. Our source code is pretty
(*pep8*, *pylint*, *pychecker*), well documented, and since we use a
speed. We consider speed to be a feature, not an afterthought. Salt’s
unique architecture brings together the best of the remote execution
world, amplifies its capabilities and expands its range, resulting in
this system that is as versatile as it is practical. Our source code is
pretty (*pep8*, *pylint*, *pychecker*), well documented, and since we use a
battle-tested branching model (*gitflow*), we are able to deliver
stable software while keeping a fast pace. Last but not least,
security is an intrinsic part of salt and something not just
influencing how source code is written and how tests are done, but
also something that defines the overall architecture and has heavy
influence on the core design of salt.
influence on the core design tenants.
Open
====
@ -84,7 +86,7 @@ Open
Salt is developed under the `Apache 2.0 licence`_, and can be used for
open and proprietary projects. Please submit your expansions back to
the Salt project so that we can all benefit together as Salt grows.
So, please feel free to sprinkle some of this around your systems and
let the deliciousness come forth.
Finally, please sprinkle some salt around your systems and let the
deliciousness come forth.
.. _`Apache 2.0 licence`: http://www.apache.org/licenses/LICENSE-2.0.html

20
conf/master.template
View File

@ -113,6 +113,19 @@
# The buffer size in the file server can be adjusted here:
#file_buffer_size: 1048576
# Pillar Configurations:
# The Salt Pillar, is a system that allows for the building of global data
# that is refined based on minion. Basically, the pillar creates data that
# can be generated to be specific based on the grains of the minion. Pillar
# is laid out in the same fashion as the file server, with environments, a top
# file and sls files. The difference is that the data does not need to be
# in the highstate format, and is generally just key/value pairs.
#
#pillar_roots:
# base:
# - /srv/pillar
#
##### Syndic settings #####
##########################################
# The Salt syndic is used to pass commands through a master from a higher
@ -127,7 +140,7 @@
#order_masters: False
#
# If this master will be running a salt syndic daemon, syndic_master tells
# this master where to recieve commands from.
# this master where to receive commands from.
#syndic_master: masterofmaster
##### Peer Publish settings #####
@ -202,3 +215,8 @@
# group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com',
# group2: 'G@os:Debian and foo.domain.com',
##### Range Cluster settings #####
##########################################
# The range server (and optional port) that
# serves your cluster information
#range_server: range:80

65
conf/minion.template
View File

@ -24,6 +24,11 @@
# clusters.
#id:
# Append a domain to a hostname in the event that it does not exist. This is
# usefule for systems where socket.getfqdn() does not actually result in a
# FQDN (for instance, Solaris).
#append_domain:
# If the the connection to the server is interrupted, the minion will
# attempt to reconnect. sub_timeout allows you to control the rate
# of reconnection attempts (in seconds). To disable reconnects, set
@ -44,6 +49,10 @@
# seconds, between those reconnection attempts.
#acceptance_wait_time = 10
# 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 then set this value to False.
#dns_check: True
##### Minion module management #####
@ -62,6 +71,14 @@
#states_dirs: []
#render_dirs: []
#
# A module provider can be statically overwritten or extended for the minion
# via the providers option, in this case the default module will be
# overwritten by the specified module. In this example the pkg module will
# be provided by the yumpkg5 module instead of the system default.
#
# providers:
# pkg: yumpkg5
#
# Enable Cython modules searching and loading. (Default: False)
#cython_enable: False
@ -101,6 +118,54 @@
# by statically setting it. Remember that the recommended way to manage
# environments is to issolate 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
##### 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
# coppied completely onto the minion. This is a literal copy of the settings on
# the master but used to reference a local directory on the minion.
# Set the file client, the client defaults to looking on the master server for
# files, but can be directed to look at the local file directory setting
# defined below by setting it to local.
#file_client: remote
# The file directory works on environments passed to the minion, each environment
# can have multiple root directories, the subdirectories in the multiple file
# roots cannot match, otherwise the downloaded files will not be able to be
# reliably ensured. A base environment is required to house the top file.
# Example:
# file_roots:
# base:
# - /srv/salt/
# dev:
# - /srv/salt/dev/services
# - /srv/salt/dev/states
# prod:
# - /srv/salt/prod/services
# - /srv/salt/prod/states
#
# Default:
#file_roots:
# base:
# - /srv/salt
# The hash_type is the hash to use when discovering the hash of a file in
# the minion directory, the default is md5, but sha1, sha224, sha256, sha384
# and sha512 are also supported.
#hash_type: md5
# The Salt pillar is searched for locally if file_client is set to local. If
# this is the case, and pillar data is defined, then the pillar_roots need to
# also be configured on the minion:
#pillar_roots:
# base:
# - /srv/pillar
###### Security settings #####
###########################################

6
doc/_templates/domainindex.html vendored Normal file
View File

@ -0,0 +1,6 @@
{% extends "!domainindex.html" %}
{%- block rootrellink %}
<li><a href="http://saltstack.org">&laquo; SaltStack.org</a>&nbsp;|&nbsp;</li>
<li><a href="{{ pathto('index') }}">Documentation home</a></li>
{%- endblock %}

6
doc/_templates/page.html vendored Normal file
View File

@ -0,0 +1,6 @@
{% extends "!page.html" %}
{%- block rootrellink %}
<li><a href="http://saltstack.org">&laquo; SaltStack.org</a>&nbsp;|&nbsp;</li>
<li><a href="{{ pathto('index') }}">Documentation home</a></li>
{%- endblock %}

2
doc/conf.py
View File

@ -30,6 +30,8 @@ class Mock(object):
MOCK_MODULES = [
# salt core
'yaml',
'yaml.nodes',
'yaml.constructor',
'msgpack',
'zmq',
'Crypto',

13
doc/contents.rst
View File

@ -7,15 +7,23 @@ Full Table of Contents
:glob:
topics/index
topics/installation/index
topics/configuration
topics/targeting/index
topics/tutorials/modules
topics/tutorials/starting_states
topics/tutorials/states*
topics/tutorials/firewall
topics/tutorials/bootstrap_ec2
topics/pillar/index
topics/jobs/index
topics/troubleshooting/index
topics/troubleshooting/yaml_idiosyncrasies
topics/community
ref/index
ref/modules/*
ref/modules/all/index
ref/grains
ref/returners/*
ref/returners/all/index
ref/states/*
@ -27,6 +35,8 @@ Full Table of Contents
ref/syndic
ref/python-api
ref/file_server/index
ref/file_server/file_roots
ref/file_server/dynamic-modules
ref/configuration/*
ref/cli/index
@ -39,5 +49,6 @@ Full Table of Contents
ref/cli/salt-run
ref/cli/salt-syndic
topics/specs/salt_auth_proto_abs
topics/roadmap/index
topics/releases/index

227
doc/index.rst
View File

@ -1,6 +1,7 @@
.. _contents:
.. |vid| image:: /_static/film_link.png
:class: math
Get started with Salt
=====================
@ -15,14 +16,14 @@ Get started with Salt
Salt is a **remote execution** and **configuration management** tool.
Salt is designed to be secure using **AES encryption** and **public-key
authentication**; incredibly scaleable using an advanced **ZeroMQ** topology;
authentication**; incredibly scalable using an advanced **ZeroMQ** topology;
fast and efficient using **msgpack**; and extensible using small and simple
**Python** modules.
Read the :doc:`Salt overview <topics/index>` for a more thorough description.
Step 1: Remote execution
------------------------
Tutorial 1: Remote execution
----------------------------
.. sidebar:: |vid| Screencasts
@ -34,20 +35,21 @@ The quickest way to see Salt in action is to run a command on a :term:`minion`
host from the :term:`master` host. This is widely known as :term:`remote
execution` — executing commands on remote hosts.
1. `Installation`_
1. :doc:`Installation </topics/installation/index>`
2. :doc:`Configure the minion <topics/configuration>`
3. :doc:`Run remote commands <topics/tutorials/modules>`
Step 2: Configuration management
--------------------------------
Tutorial 2: Configuration management
------------------------------------
Now that you have the basics out of the way, learn to use Salt to configure
your servers. This is widely known as :term:`configuration management` —
installing packages, configuring users and services, and much more.
1. :doc:`Basic config management <topics/tutorials/states_pt1>`
2. :doc:`Less basic config management <topics/tutorials/states_pt2>`
3. :doc:`Advanced techniques <topics/tutorials/states_pt3>`
1. :doc:`Getting Started with States<topics/tutorials/starting_states>`
2. :doc:`Basic config management <topics/tutorials/states_pt1>`
3. :doc:`Less basic config management <topics/tutorials/states_pt2>`
4. :doc:`Advanced techniques <topics/tutorials/states_pt3>`
Salt in depth
=============
@ -56,132 +58,155 @@ Setting up and using Salt is a simple task but it's capabilities run much, much
deeper. Gaining a better understanding of how Salt works will allow you to
truly make it work for you.
.. contents:: Overview
.. sidebar:: More tutorials!
* :doc:`Bootstraping Salt on EC2 <topics/tutorials/bootstrap_ec2>`
* :doc:`Installing Salt on FreeBSD <topics/installation/freebsd>`
.. contents:: The components of Salt
:local:
:depth: 2
**Remote execution**
Remote execution is the core functionality of Salt. Running pre-defined or
arbitrary commands on remote hosts.
:doc:`Targeting </topics/targeting/index>`
------------------------------------------
**Modules**
Salt modules are the core of remote execution. They provide
functionality such as installing a package, restarting a service,
running a remote command, transferring a file — and the list goes on.
Targeting is specifying which minions should execute commands or manage server
configuration.
:doc:`Full list of modules </ref/modules/all/index>`
The giant list of core modules that ship with Salt
(And there are even more in the `salt-contrib`_ repository!)
:doc:`Globbing and regex </topics/targeting/globbing>`
Match minions using globbing and regular expresssions.
:doc:`Writing modules <ref/modules/index>`
A guide on how to write Salt modules
:doc:`Grains </topics/targeting/grains>`
Match minions using bits of static information about the minion such as
OS, software versions, virtualization, CPU, memory, and much more.
**Targeting**
Specify which hosts should run commands or manage configuration.
:doc:`Node groups </topics/targeting/nodegroups>`
Statically define groups of minions.
:doc:`Targeting <ref/targeting/index>`
Hostnames, lists, regular expressions, or define groups.
:doc:`Compound matchers </topics/targeting/compound>`
Combine the above matchers as a single target.
:doc:`Grains <ref/grains>`
Bits of static information about a minion such as OS, version,
virtualization, CPU, memory, and much more.
Remote execution
----------------
**Returners**
Salt returners allow saving minion responses in various datastores or
to various locations in addition to display at the CLI.
Remote execution is the core functionality of Salt. Running pre-defined or
arbitrary commands on remote hosts.
:doc:`Full list of returners </ref/returners/all/index>`
Store minion responses in Redis, Mongo, Cassandra or more.
**Modules**
Salt modules are the core of remote execution. They provide
functionality such as installing a package, restarting a service,
running a remote command, transferring a file — and the list goes on.
:doc:`Writing returners <ref/returners/index>`
If we're missing your favorite storage backend, webservice, or you
need a custom endpoint returners are *tiny* and simple to write.
:doc:`Full list of modules </ref/modules/all/index>`
The giant list of core modules that ship with Salt
(And there are even more in the `salt-contrib`_ repository!)
**Configuration management**
Building on the remote execution core is a robust and flexible config
management framework. Execution happens on the minions allowing
effortless, simultaneous configuration of thousands of hosts.
:doc:`Writing modules <ref/modules/index>`
A guide on how to write Salt modules
**States**
Express the state of a host using small, easy to read, easy to
understand configuration files. No programming required (unless you
want to).
**Returners**
Salt returners allow saving minion responses in various datastores or
to various locations in addition to display at the CLI.
:doc:`Full list of states <ref/states/all/index>`
Install packages, create users, transfer files, start services, and
more and more.
:doc:`Full list of returners </ref/returners/all/index>`
Store minion responses in Redis, Mongo, Cassandra or more.
:doc:`Using states <ref/states/index>`
You've seen the big list of available states, now learn how to call
them.
:doc:`Writing returners <ref/returners/index>`
If we're missing your favorite storage backend, webservice, or you
need a custom endpoint returners are *tiny* and simple to write.
:doc:`Highstate data structure <ref/states/highstate>`
A dry, vocabulary and technical representation of the configuration
format that states represent.
Configuration management
------------------------
**Renderers**
Write state configuration files in the language, templating engine, or
file type of your choice. The world doesn't need yet another DSL.
Building on the remote execution core is a robust and flexible config
management framework. Execution happens on the minions allowing
effortless, simultaneous configuration of thousands of hosts.
:doc:`Full list of renderers <ref/renderers/all/index>`
YAML? JSON? Jinja? Mako? Python? We got you covered. (And if we
don't, new renderers are *tiny* and easy to write.)
**States**
Express the state of a host using small, easy to read, easy to
understand configuration files. No programming required (unless you
want to).
:doc:`Renderers <ref/renderers/index>`
Salt states are only concerned with the ultimate highstate data
structure. How you create that data structure isn't our business.
Tweak a config option and use whatever you're most comfortable
with.
:doc:`Full list of states <ref/states/all/index>`
Install packages, create users, transfer files, start services, and
more and more.
**Miscellaneous topics**
Salt is a many splendid thing.
:doc:`Using states <ref/states/index>`
You've seen the big list of available states, now learn how to call
them.
:doc:`File Server <ref/file_server/index>`
Salt can easily and quickly transfer files (in fact, that's how Salt
States work). Even under load, files are chunked and served.
:doc:`Highstate data structure <ref/states/highstate>`
A dry, vocabulary and technical representation of the configuration
format that states represent.
:doc:`Syndic <ref/syndic>`
A seamless master of masters. Scale Salt to thousands of hosts or
across many different networks.
**Renderers**
Write state configuration files in the language, templating engine, or
file type of your choice. The world doesn't need yet another DSL.
:doc:`Peer communication <ref/peer>`
Allow minions to communicate amongst themselves. For example, configure
one minion by querying live data from all the others. With great power
comes great responsibility.
:doc:`Full list of renderers <ref/renderers/all/index>`
YAML? JSON? Jinja? Mako? Python? We got you covered. (And if we
don't, new renderers are *tiny* and easy to write.)
:doc:`Network topology <ref/topology>`
At it's core, Salt is a highly scalable communication layer built on
top of ZeroMQ that enables remote execution and configuration
management. The possibilities are endless and Salt's future looks
bright.
:doc:`Renderers <ref/renderers/index>`
Salt states are only concerned with the ultimate highstate data
structure. How you create that data structure isn't our business.
Tweak a config option and use whatever you're most comfortable
with.
:doc:`Python API interface <ref/python-api>`
Use Salt programmatically from your own scripts and programs easily and
simply via ``import salt``.
Miscellaneous topics
--------------------
**Reference**
:doc:`Command-line interface <ref/cli/index>`
Read the Salt manpages.
Salt is a many splendid thing.
:doc:`Full list of master settings <ref/configuration/master>`
Read through the heavily-commented master configuration file.
:doc:`File Server <ref/file_server/index>`
Salt can easily and quickly transfer files (in fact, that's how Salt
States work). Even under load, files are chunked and served.
:doc:`Full list of minion settings <ref/configuration/minion>`
Read through the heavily-commented minion configuration file.
:doc:`Syndic <ref/syndic>`
A seamless master of masters. Scale Salt to thousands of hosts or
across many different networks.
:doc:`Full table of contents </contents>`
Dense but complete.
:doc:`Peer communication <ref/peer>`
Allow minions to communicate amongst themselves. For example, configure
one minion by querying live data from all the others. With great power
comes great responsibility.
**More information about the project**
:doc:`Network topology <ref/topology>`
At it's core, Salt is a highly scalable communication layer built on
top of ZeroMQ that enables remote execution and configuration
management. The possibilities are endless and Salt's future looks
bright.
:doc:`Roadmap </topics/roadmap/index>`
Where we're headed.
:doc:`Python API interface <ref/python-api>`
Use Salt programmatically from your own scripts and programs easily and
simply via ``import salt``.
:doc:`Release notes </topics/releases/index>`
Where we've been.
Reference
---------
:doc:`Community </topics/community>`
How you can get involved.
:doc:`Command-line interface <ref/cli/index>`
Read the Salt manpages.
:doc:`Full list of master settings <ref/configuration/master>`
Read through the heavily-commented master configuration file.
:doc:`Full list of minion settings <ref/configuration/minion>`
Read through the heavily-commented minion configuration file.
:doc:`Full table of contents </contents>`
Dense but complete.
More information about the project
----------------------------------
:doc:`Roadmap </topics/roadmap/index>`
Where we're headed.
:doc:`Release notes </topics/releases/index>`
Where we've been.
:doc:`Community </topics/community>`
How you can get involved.
.. _`salt-contrib`: https://github.com/saltstack/salt-contrib
.. _`salt-states`: https://github.com/saltstack/salt-states

39
doc/man/salt-call.1
View File

@ -1,4 +1,4 @@
.TH "SALT-CALL" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT-CALL" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt-call \- salt-call Documentation
.
@ -60,10 +60,45 @@ directories can be delimited by commas
Return the documentation for the specified module of for all modules if
none are specified
.UNINDENT
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console log level. One of \fBinfo\fP, \fBnone\fP, \fBgarbage\fP,
\fBtrace\fP, \fBwarning\fP, \fBerror\fP, \fBdebug\fP. For the logfile
settings see the config file. Default: \fBinfo\fP.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-raw\-out
Print the output from the salt command in raw python
form, this is suitable for re\-reading the output into
an executing python script with eval.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-text\-out
Print the output from the salt command in the same
form the shell would.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-yaml\-out
Print the output from the salt command in yaml.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-json\-out
Print the output from the salt command in json.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-color
Disable all colored output
.UNINDENT
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

34
doc/man/salt-cp.1
View File

@ -1,4 +1,4 @@
.TH "SALT-CP" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT-CP" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt-cp \- salt-cp Documentation
.
@ -61,27 +61,47 @@ The timeout in seconds to wait for replies from the salt minions.
.INDENT 0.0
.TP
.B \-E, \-\-pcre
The target expression will be interpereted as a pcre regular expression
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 interpereted as a comma delimited 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
.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>:<pcre
regular expression>\(aq; example: \(aqos:Arch.*\(aq
.UNINDENT
.INDENT 0.0
.TP
.B \-Q, \-\-query
Execute a salt command query, this can be used to find the results of a
previous function call: \-Q test.echo\(aq)
.B \-R, \-\-range
Instead of using shell globs to evaluate the targe 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 and or or. The default matcher is a
glob as usual, if something other than a glob is used preface it with the
letter denoting the type, example: \(aqwebserv* and \fI\%G@os\fP:Debian or \fI\%E@db*\fP\(aq
make sure that the compound target is encapsulated in quotes.
.UNINDENT
.INDENT 0.0
.TP
@ -93,7 +113,7 @@ default=/etc/salt/master
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

28
doc/man/salt-key.1
View File

@ -1,4 +1,4 @@
.TH "SALT-KEY" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT-KEY" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt-key \- salt-key Documentation
.
@ -51,8 +51,8 @@ List the unaccepted minion public keys.
.INDENT 0.0
.TP
.B \-L, \-\-list\-all
List all public keys on this salt master, both accepted and pending
acceptance.
List all public keys on this salt master: accepted, pending,
and rejected.
.UNINDENT
.INDENT 0.0
.TP
@ -66,6 +66,26 @@ Accepts all pending public keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-r REJECT, \-\-reject=REJECT
Reject the named minion public key.
.UNINDENT
.INDENT 0.0
.TP
.B \-R, \-\-reject\-all
Rejects all pending public keys.
.UNINDENT
.INDENT 0.0
.TP
.B \-d DELETE, \-\-delete=DELETE
Delete the named minion key for command execution.
.UNINDENT
.INDENT 0.0
.TP
.B \-D DELETE_ALL, \-\-delete\-all=DELETE_ALL
Deleta all keys
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG, \-\-config=CONFIG
The master configuration file needs to be read to determine where the salt
keys are stored via the pki_dir configuration value;
@ -74,7 +94,7 @@ default=/etc/salt/master
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

9
doc/man/salt-master.1
View File

@ -1,4 +1,4 @@
.TH "SALT-MASTER" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT-MASTER" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt-master \- salt-master Documentation
.
@ -61,6 +61,11 @@ Specify user to run minion
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file PIDFILE
Specify the location of the pidfile.
.UNINDENT
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console log level. One of \fBinfo\fP, \fBnone\fP, \fBgarbage\fP,
\fBtrace\fP, \fBwarning\fP, \fBerror\fP, \fBdebug\fP. For the logfile
@ -69,7 +74,7 @@ settings see the config file. Default: \fBwarning\fP.
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

9
doc/man/salt-minion.1
View File

@ -1,4 +1,4 @@
.TH "SALT-MINION" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT-MINION" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt-minion \- salt-minion Documentation
.
@ -62,6 +62,11 @@ Specify user to run minion
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file PIDFILE
Specify the location of the pidfile
.UNINDENT
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console log level. One of \fBinfo\fP, \fBnone\fP, \fBgarbage\fP,
\fBtrace\fP, \fBwarning\fP, \fBerror\fP, \fBdebug\fP. For the logfile
@ -70,7 +75,7 @@ settings see the config file. Default: \fBwarning\fP.
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

6
doc/man/salt-run.1
View File

@ -1,4 +1,4 @@
.TH "SALT-RUN" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT-RUN" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt-run \- salt-run Documentation
.
@ -41,7 +41,7 @@ salt\-run RUNNER
.fi
.SH DESCRIPTION
.sp
Salt run is the frontend command for executing \fBSalt Runners\fP.
salt\-run is the frontend command for executing \fBSalt Runners\fP.
Salt runners are simple modules used to execute convenience functions on the
master
.SH OPTIONS
@ -60,7 +60,7 @@ default=/etc/salt/master
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

9
doc/man/salt-syndic.1
View File

@ -1,4 +1,4 @@
.TH "SALT-SYNDIC" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT-SYNDIC" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt-syndic \- salt-syndic Documentation
.
@ -53,6 +53,11 @@ Run the salt syndic as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file PIDFILE
Specify the location of the pidfile
.UNINDENT
.INDENT 0.0
.TP
.B \-\-master\-config=MASTER_CONFIG
The master configuration file to use, the default is /etc/salt/master
.UNINDENT
@ -64,7 +69,7 @@ The minion configuration file to use, the default is /etc/salt/minion
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

54
doc/man/salt.1
View File

@ -1,4 +1,4 @@
.TH "SALT" "1" "January 20, 2012" "0.9.6" "Salt"
.TH "SALT" "1" "March 19, 2012" "0.9.8" "Salt"
.SH NAME
salt \- salt
.
@ -62,6 +62,22 @@ The timeout in seconds to wait for replies from the salt minions.
.UNINDENT
.INDENT 0.0
.TP
.B \-s STATIC, \-\-static=STATIC
By default as of version 0.9.8 the salt command returns data to the
console as it is received from minions, but previous releases would return
data only after all data was received. To only return the data with a hard
timeout and after all minions have returned then use the static option.
.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 \-\-version
Print the version of salt that is running.
.UNINDENT
@ -81,7 +97,18 @@ example: server1.foo.bar,server2.foo.bar,example7.quo.qux
.TP
.B \-G, \-\-grain
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of \(aq<grain value>:<pcre
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
@ -90,7 +117,7 @@ regular expression>\(aq; example: \(aqos:Arch.*\(aq
Utilize many target definitions to make the call very granular. This option
takes a group of targets separated by and or or. The default matcher is a
glob as usual, if something other than a glob is used preface it with the
letter denoting the type, example: \(aqwebserv* and \fI\%G@os\fP:Debian or \fI\%E@db.*\fP\(aq
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
@ -106,6 +133,16 @@ file
.UNINDENT
.INDENT 0.0
.TP
.B \-R, \-\-range
Instead of using shell globs to evaluate the targe 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 \-\-return
Chose an alternative returner to call on the minion, if an alternative
returner is used then the return will not come back tot he command line
@ -114,6 +151,10 @@ but will be sent to the specified return system.
.INDENT 0.0
.TP
.B \-Q, \-\-query
The \-Q option is being deprecated and will be removed in version 0.9.9,
Use the salt jobs interface instead, for documentation on the salt jobs
interface execute the command "salt\-run \-d jobs"
.sp
Execute a salt command query, this can be used to find the results of a
previous function call: \-Q test.echo\(aq)
.UNINDENT
@ -147,6 +188,11 @@ Print the output from the salt command in yaml.
.B \-\-json\-out
Print the output from the salt command in json.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-color
Disable all colored output
.UNINDENT
.SH SEE ALSO
.sp
\fIsalt(7)\fP
@ -155,7 +201,7 @@ Print the output from the salt command in json.
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas S. Hatch
2012, Thomas S. Hatch
.\" Generated by docutils manpage writer.
.\"
.

7966
doc/man/salt.7
View File

File diff suppressed because it is too large Load Diff

4
doc/ref/cli/index.rst
View File

@ -2,9 +2,9 @@
Command Line Reference
======================
Salt can be controlled by a command line client by the root user on the Salt
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
with the Salt master server. The Salt client is straightforward and simple
to use.
Using the Salt client commands can be easily sent to the minions.

29
doc/ref/cli/salt-call.rst
View File

@ -31,3 +31,32 @@ Options
Return the documentation for the specified module of for all modules if
none are specified
.. option:: -l LOG_LEVEL, --log-level=LOG_LEVEL
Console log level. One of ``info``, ``none``, ``garbage``,
``trace``, ``warning``, ``error``, ``debug``. For the logfile
settings see the config file. Default: ``info``.
.. option:: --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.
.. option:: --text-out
Print the output from the salt command in the same
form the shell would.
.. option:: --yaml-out
Print the output from the salt command in yaml.
.. option:: --json-out
Print the output from the salt command in json.
.. option:: --no-color
Disable all colored output

24
doc/ref/cli/salt-cp.rst
View File

@ -46,14 +46,32 @@ Options
.. option:: -G, --grain
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of '<grain value>:<glob
expression>'; example: 'os:Arch*'
.. option:: --grain-pcre
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of '<grain value>:<pcre
regular expression>'; example: 'os:Arch.*'
.. option:: -Q, --query
.. option:: -R, --range
Execute a salt command query, this can be used to find the results of a
previous function call: -Q test.echo')
Instead of using shell globs to evaluate the target use a range expression
to identify targets. Range expressions look like %cluster.
Using the Range option requires that a range server is set up and the
location of the range server is referenced in the master configuration
file.
.. option:: -C, --compound
Utilize many target definitions to make the call very granular. This option
takes a group of targets separated by and or or. The default matcher is a
glob as usual, if something other than a glob is used preface it with the
letter denoting the type, example: 'webserv* and G@os:Debian or E@db*'
make sure that the compound target is encapsulated in quotes.
.. option:: -c CONFIG, --config=CONFIG

8
doc/ref/cli/salt-key.rst
View File

@ -47,6 +47,14 @@ Options
Rejects all pending public keys.
.. option:: -d DELETE, --delete=DELETE
Delete the named minion key for command execution.
.. option:: -D DELETE_ALL, --delete-all=DELETE_ALL
Deleta all keys
.. option:: -c CONFIG, --config=CONFIG
The master configuration file needs to be read to determine where the salt

4
doc/ref/cli/salt-master.rst
View File

@ -35,6 +35,10 @@ Options
Specify user to run minion
.. option:: --pid-file PIDFILE
Specify the location of the pidfile.
.. option:: -l LOG_LEVEL, --log-level=LOG_LEVEL
Console log level. One of ``info``, ``none``, ``garbage``,

4
doc/ref/cli/salt-minion.rst
View File

@ -36,6 +36,10 @@ Options
Specify user to run minion
.. option:: --pid-file PIDFILE
Specify the location of the pidfile
.. option:: -l LOG_LEVEL, --log-level=LOG_LEVEL
Console log level. One of ``info``, ``none``, ``garbage``,

4
doc/ref/cli/salt-syndic.rst
View File

@ -29,6 +29,10 @@ Options
Run the salt syndic as a daemon
.. option:: --pid-file PIDFILE
Specify the location of the pidfile
.. option:: --master-config=MASTER_CONFIG
The master configuration file to use, the default is /etc/salt/master

47
doc/ref/cli/salt.rst
View File

@ -35,6 +35,20 @@ Options
The timeout in seconds to wait for replies from the salt minions.
.. option:: -s STATIC, --static=STATIC
By default as of version 0.9.8 the salt command returns data to the
console as it is received from minions, but previous releases would return
data only after all data was received. To only return the data with a hard
timeout and after all minions have returned then use the static option.
.. option:: -b BATCH, --batch-size=BATCH
Instead of executing on all targeted minions at once, execute on a
progressive set of minions. This option takes an argument in the form of
an explicit number of minions to execute at once, or a percentage of
minions to execute on.
.. option:: --version
Print the version of salt that is running.
@ -52,7 +66,17 @@ Options
.. option:: -G, --grain
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of '<grain value>:<pcre
the minions. The target expression is in the format of '<grain value>:<glob
expression>'; example: 'os:Arch*'
This was changed in version 0.9.8 to accept glob expressions instead of
regular expression. To use regular expression matching with grains use
the --grain-pcre option.
.. option:: --grain-pcre
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of '<grain value>:<
regular expression>'; example: 'os:Arch.*'
.. option:: -C, --compound
@ -60,7 +84,7 @@ Options
Utilize many target definitions to make the call very granular. This option
takes a group of targets separated by and or or. The default matcher is a
glob as usual, if something other than a glob is used preface it with the
letter denoting the type, example: 'webserv* and G@os:Debian or E@db.*'
letter denoting the type, example: 'webserv* and G@os:Debian or E@db*'
make sure that the compound target is encapsulated in quotes.
.. option:: -X, --exsel
@ -72,6 +96,15 @@ Options
Use a predefined compound target defined in the salt master configuration
file
.. option:: -R, --range
Instead of using shell globs to evaluate the target use a range expression
to identify targets. Range expressions look like %cluster.
Using the Range option requires that a range server is set up and the
location of the range server is referenced in the master configuration
file.
.. option:: --return
Chose an alternative returner to call on the minion, if an alternative
@ -80,6 +113,10 @@ Options
.. option:: -Q, --query
The -Q option is being deprecated and will be removed in version 0.9.9,
Use the salt jobs interface instead, for documentation on the salt jobs
interface execute the command "salt-run -d jobs"
Execute a salt command query, this can be used to find the results of a
previous function call: -Q test.echo')
@ -95,7 +132,7 @@ Options
form, this is suitable for re-reading the output into
an executing python script with eval.
.. option:: --text-out
.. option:: --text-out
Print the output from the salt command in the same
form the shell would.
@ -108,6 +145,10 @@ Options
Print the output from the salt command in json.
.. option:: --no-color
Disable all colored output
See also
========

33
doc/ref/configuration/master.rst
View File

@ -91,7 +91,7 @@ execution returns and command executions.
Default: :file:`/`
The system root direcotry to oporate from, change this to make Salt run from
The system root directory to operate from, change this to make Salt run from
an alternative root
.. code-block:: yaml
@ -158,9 +158,9 @@ 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
minions. Open mode should not be turned on for general use. Open mode should
only be used for a short period of time to clean up pki keys. To turn on open
mode the value passed must be ``True``.
mode set this value to ``True``.
.. code-block:: yaml
@ -173,7 +173,7 @@ mode the value passed must be ``True``.
Default: ``False``
Enable auto_accept, this setting will automatically accept all incoming
Enable auto_accept. This setting will automatically accept all incoming
public keys from the minions
.. code-block:: yaml
@ -206,7 +206,7 @@ root of the base environment
Default: None
The external_nodes option allows Salt to gather data that would normally be
placed in a top file from and external node controller. The external_nodes
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!
@ -252,10 +252,10 @@ Default: ``base: [/srv/salt]``
Salt runs a lightweight file server written in zeromq to deliver files to
minions. This file server is built into the master daemon and does not
require a dedicated port.
The file server works on environments passed to the master, each environment
can have multiple root directories, the subdirectories in the multiple file
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
reliably ensured. A base environment is required to house the top file.
Example:
.. code-block:: yaml
@ -306,12 +306,11 @@ The buffer size in the file server in bytes
Syndic Server 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
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
to recieve commands from
.. conf_master:: order_masters
@ -320,7 +319,7 @@ to recieve commands from
Default: ``False``
Extra data needs to be sind with publications if the master os controlling a
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
@ -336,7 +335,7 @@ value must be set to True
Default: ``None``
If this master will be running a salt-syndic to connect to a higher level
master specify the higher level master with this configuration value
master, specify the higher level master with this configuration value
.. code-block:: yaml
@ -358,7 +357,7 @@ compartmentalization of commands based on individual minions.
Default: ``{}``
The configuration uses regular expressions to match minions and then a list
of regular expressions to match functions, the following will allow the
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
@ -377,7 +376,7 @@ This will allow all minions to execute all commands:
.*:
- .*
This is not recomanded, since it would allow anyone who gets root on any
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!
Node Groups
@ -434,7 +433,7 @@ One of 'info', 'quiet', 'critical', 'error', 'debug', 'warning'.
Default: ``{}``
Logger levels can be used to tweak specific loggers logging levels.
Imagine you want to have the salt library at the 'warning' level, but, you
Imagine you want to have the salt library at the 'warning' level, but you
still wish to have 'salt.modules' at the 'debug' level:
.. code-block:: yaml

8
doc/ref/configuration/minion.rst
View File

@ -69,7 +69,7 @@ The directory used to store the minion's public and private keys.
pki_dir: /etc/salt/pki
.. conf_minion:: hostname
.. conf_minion:: id
``id``
------------
@ -91,7 +91,7 @@ clusters.
``sub_timeout``
---------------
The minion connection to the master may be inturupted, the minion will
The minion connection to the master may be interrupted, the minion will
verify the connection every so many seconds, to disable connection
verification set this value to 0
@ -172,7 +172,7 @@ disabling modules will lover the minion's ram footprint.
Default: ``[]`` (all returners are enabled by default)
If certian returners should be disabled, this is the place
If certain returners should be disabled, this is the place
.. code-block:: yaml
@ -274,7 +274,7 @@ The default renderer used for local state executions
Default: ``False``
state_verbose allows for the data returned from the minion to be more
verbose. Normaly only states that fail or states that have changes are
verbose. Normally only states that fail or states that have changes are
returned, but setting state_verbose to True will return all states that
were checked

31
doc/ref/file_server/dynamic-modules.rst
View File

@ -1,6 +1,37 @@
===========================
Dynamic Module Distribution
===========================
.. versionadded:: 0.9.5
Salt python modules can be distributed automatically via the salt file server.
Under the root of any environment defined via the file_roots option on the
master server directories corresponding to the type of module can be used.
The directories are prepended with an underscore:
1. _modules
2. _grains
3. _renderers
4. _returners
5. _states
The contents of these directories need to be synced over to the minions after
python modules have been created in them. There are a number of ways to sync
the modules.
Sync Via States
===============
The minion configuration contains an option ``autoload_dynamic_modules``
which defaults to True. This option makes the state system refresh all
dynamic modules when states are run. To disable this behavior set
``autoload_dynamic_modules`` to False in the minion config.
Sync Via the saltutil Module
============================
The saltutil module has a number of functions that can be used to sync all
or specific dynamic modules. The saltutil module function ``saltutil.sync_all``
will sync all module types over to a minion. For more information see:
:mod:`salt.modules.saltutil`

65
doc/ref/file_server/file_roots.rst Normal file
View File

@ -0,0 +1,65 @@
=========================
File Server Configuration
=========================
The Salt file server is a high performance file server written in ZeroMQ. It
manages large files quickly and with little overhead, and has been optimized
to handle small files in an extremely efficient manner.
The Salt file server is an environment aware file server. This means that
files can be allocated within many root directories and accessed by
specifying both the file path and the environment to search. The
individual environments can span across multiple directory roots
to crate overlays and to allow for files to be organized in many flexible
ways.
Environments
============
The Salt file server defaults to the mandatory ``base`` environment. This
environment **MUST** be defined and is used to download files when no
environment is specified.
Environments allow for files and sls data to be logically separated, but
environments are not isolated from each other. This allows for logical
isolation of environments by the engineer using Salt, but also allows
for information to be used in multiple environments.
Directory Overlay
=================
The ``environment`` setting is a list of directories to publish files from.
These directories are searched in order to find the specified file and the
first file found is returned.
This means that directory data is prioritized based on the order in which they
are listed. In the case of this ``file_roots`` configuration:
.. code-block:: yaml
file_roots:
base:
- /srv/salt/base
- /srv/salt/failover
If a file's uri is ``salt://httpd/httpd.conf``, it will first search for the
file at ``/srv/salt/base/httpd/httpd.conf``. If the file is found there it
will be returned. If the file is not found there, then
``/srv/salt/failover/httpd/httpd.conf`` will be used for the source.
This allows for directories to be overlaid and prioritized based on the order
they are defined in the configuration.
Local File Server
=================
.. versionadded:: 0.9.8
The file server can be rerouted to run from the minion. This is primarily to
enable running salt states without a salt master. To use the local file server
interface, copy the file server data to the minion and set the file_roots
option on the minion to point to the directories copied from the master.
Once the minion ``file_roots`` option has been set, change the ``file_client``
option to local to make sure that the local file server interface is used.

4
doc/ref/file_server/index.rst
View File

@ -4,9 +4,9 @@ Salt File Server
Salt comes with a simple file server suitable for distributing files to the
salt minions. The file server is a stateless ZeroMQ server that is built into
the salt master.
the salt master.
The main intent of the Salt File server is the present files for use in the
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.

25
doc/ref/modules/all/index.rst
View File

@ -4,6 +4,13 @@
Full list of builtin modules
============================
.. admonition:: Virtual modules
.. toctree::
salt.modules.pkg
salt.modules.sys
.. currentmodule:: salt.modules
.. autosummary::
@ -15,35 +22,44 @@ Full list of builtin modules
archive
butterkvm
cluster
cmd
cmdmod
cp
cron
data
debconfmod
disk
ebuild
file
freebsdkmod
freebsdpkg
freebsdservice
gem
gentoo_service
git
grains
groupadd
hg
hosts
kmod
kvm_hyper
linux_sysctl
mdadm
moosefs
mount
mysql
network
nginx
pacman
pillar
pip
ps
publish
puppet
pw_group
pw_user
rh_service
rh_network
rh_service
rvm
saltutil
selinux
service
@ -55,11 +71,16 @@ Full list of builtin modules
systemd
test
tomcat
upstart
useradd
virt
virtualenv
win_disk
win_file
win_network
win_service
win_shadow
win_useradd
yumpkg
yumpkg5
zypper

4
doc/ref/modules/all/salt.modules.cmd.rst → doc/ref/modules/all/salt.modules.cmdmod.rst
View File

@ -2,5 +2,5 @@
salt.modules.cmd
================
.. automodule:: salt.modules.cmd
:members:
.. automodule:: salt.modules.cmdmod
:members:

6
doc/ref/modules/all/salt.modules.debconfmod.rst Normal file
View File

@ -0,0 +1,6 @@
=======================
salt.modules.debconfmod
=======================
.. automodule:: salt.modules.debconfmod
:members:

6
doc/ref/modules/all/salt.modules.freebsdservice.rst Normal file
View File

@ -0,0 +1,6 @@
===========================
salt.modules.freebsdservice
===========================
.. automodule:: salt.modules.freebsdservice
:members:

6
doc/ref/modules/all/salt.modules.gem.rst Normal file
View File

@ -0,0 +1,6 @@
================
salt.modules.gem
================
.. automodule:: salt.modules.gem
:members:

6
doc/ref/modules/all/salt.modules.git.rst Normal file
View File

@ -0,0 +1,6 @@
================
salt.modules.git
================
.. automodule:: salt.modules.git
:members:

6
doc/ref/modules/all/salt.modules.hg.rst Normal file
View File

@ -0,0 +1,6 @@
===============
salt.modules.hg
===============
.. automodule:: salt.modules.hg
:members:

6
doc/ref/modules/all/salt.modules.kvm_hyper.rst Normal file
View File

@ -0,0 +1,6 @@
======================
salt.modules.kvm_hyper
======================
.. automodule:: salt.modules.kvm_hyper
:members:

6
doc/ref/modules/all/salt.modules.nginx.rst Normal file
View File

@ -0,0 +1,6 @@
==================
salt.modules.nginx
==================
.. automodule:: salt.modules.nginx
:members:

6
doc/ref/modules/all/salt.modules.pillar.rst Normal file
View File

@ -0,0 +1,6 @@
===================
salt.modules.pillar
===================
.. automodule:: salt.modules.pillar
:members:

16
doc/ref/modules/all/salt.modules.pkg.rst Normal file
View File

@ -0,0 +1,16 @@
================
salt.modules.pkg
================
.. py:module:: salt.modules.pkg
:synopsis: A virtual module for installing software packages
``pkg`` is a virtual module that is fulfilled by one of the following modules:
* :mod:`salt.modules.apt`
* :mod:`salt.modules.ebuild`
* :mod:`salt.modules.freebsdpkg`
* :mod:`salt.modules.pacman`
* :mod:`salt.modules.yumpkg`
* :mod:`salt.modules.yumpkg5`
* :mod:`salt.modules.zypper`

6
doc/ref/modules/all/salt.modules.rvm.rst Normal file
View File

@ -0,0 +1,6 @@
================
salt.modules.rvm
================
.. automodule:: salt.modules.rvm
:members:

33
doc/ref/modules/all/salt.modules.sys.rst Normal file
View File

@ -0,0 +1,33 @@
================
salt.modules.sys
================
The regular salt modules execute in a separate context from the salt minion
and manipulating the actual salt modules needs to happen in a higher level
context within the minion process. This is where the sys pseudo module is
used.
The sys pseudo module comes with a few functions that return data about the
available functions on the minion or allows for the minion modules to be
refreshed. These functions are as follows:
.. py:module:: salt.modules.sys
.. py:function:: doc([module[, module.function]])
Display the inline documentation for all available modules, or for the
specified module or function.
.. py:function:: reload_modules
Instruct the minion to reload all available modules in memory. This
function can be called if the modules need to be re-evaluated for
availability or new modules have been made available to the minion.
.. py:function:: list_modules
List all available (loaded) modules.
.. py:function:: list_functions
List all known functions that are in available (loaded) modules.

6
doc/ref/modules/all/salt.modules.upstart.rst Normal file
View File

@ -0,0 +1,6 @@
====================
salt.modules.upstart
====================
.. automodule:: salt.modules.upstart
:members:

6
doc/ref/modules/all/salt.modules.win_file.rst Normal file
View File

@ -0,0 +1,6 @@
=====================
salt.modules.win_file
=====================
.. automodule:: salt.modules.win_file
:members:

6
doc/ref/modules/all/salt.modules.win_network.rst Normal file
View File

@ -0,0 +1,6 @@
========================
salt.modules.win_network
========================
.. automodule:: salt.modules.win_network
:members:

6
doc/ref/modules/all/salt.modules.win_shadow.rst Normal file
View File

@ -0,0 +1,6 @@
=======================
salt.modules.win_shadow
=======================
.. automodule:: salt.modules.win_shadow
:members:

6
doc/ref/modules/all/salt.modules.zypper.rst Normal file
View File

@ -0,0 +1,6 @@
===================
salt.modules.zypper
===================
.. automodule:: salt.modules.zypper
:members:

7
doc/ref/modules/index.rst
View File

@ -12,7 +12,8 @@ Easy Modules to write
=====================
Salt modules are amazingly simple to write, just write a regular Python module
or a regular Cython module and place it in the ``salt/modules`` directory.
or a regular Cython module and place it in the ``salt/modules`` directory. You
can also place them in a directory called ``_modules/`` in your state directory.
Since Salt modules are just Python/Cython modules there are no restraints as to
what you can put inside of a salt module, and if a Salt module has errors and
@ -32,7 +33,7 @@ This means that when creating a module functions in modules which already exist
can be called.
The variable ``__salt__`` is packed into the modules after they are loaded into
the salt minion. This variable is a python dictionary of all of the salt
the salt minion. This variable is a python dictionary of all of the salt
functions, laid out in the same way that they are made available to the salt
command.
@ -40,7 +41,7 @@ Salt modules can be cross called by accessing the value in the ``__salt__``
dict:
.. code-block:: python
def foo(bar):
return __salt__['cmd.run'](bar)

2
doc/ref/python-api.rst
View File

@ -65,7 +65,7 @@ Compound Command Execution With the Salt API
The Salt client API can also send what is called a compound command. Often
a collection of commands need to be executed on the targeted minions, rather
than send the commands one after another, they can be send in a single publish
containing a series of commands. This can dramatically lower overhead and
containing a series of commands. This can dramatically lower overhead and
speed up the application communicating with Salt.
When commands are executed with compound execution the minion functions called

10
doc/ref/renderers/all/index.rst
View File

@ -10,8 +10,8 @@ Full list of builtin renderers
:toctree:
:template: autosummary.rst.tmpl
json_jinja
json_mako
yaml_jinja
yaml_mako
py
salt.renderers.json_jinja
salt.renderers.json_mako
salt.renderers.yaml_jinja
salt.renderers.yaml_mako
salt.renderers.py

2
doc/ref/returners/index.rst
View File

@ -38,7 +38,7 @@ It is also possible to specify multiple returners:
salt '*' test.ping --return mongo_return,redis_return,cassandra_return
In this scenario all three returners will be called and the data from the
test.ping command will be sent out to the three named returers.
test.ping command will be sent out to the three named returners.
Writing a Returner
==================

2
doc/ref/runners.rst
View File

@ -32,7 +32,7 @@ The best examples of runners can be found in the Salt source:
:blob:`salt/runners`
A simple runner that returns a well formated list of the minons that are
A simple runner that returns a well-formatted list of the minions that are
responding to salt calls would look like this:
.. code-block:: python

2
doc/ref/states/all/index.rst
View File

@ -13,6 +13,7 @@ Full list of builtin states
cmd
cron
file
gem
group
host
kmod
@ -21,6 +22,7 @@ Full list of builtin states
mysql_user
network
pkg
rvm
service
ssh_auth
sysctl

6
doc/ref/states/all/salt.states.gem.rst Normal file
View File

@ -0,0 +1,6 @@
===============
salt.states.gem
===============
.. automodule:: salt.states.gem
:members:

6
doc/ref/states/all/salt.states.rvm.rst Normal file
View File

@ -0,0 +1,6 @@
===============
salt.states.rvm
===============
.. automodule:: salt.states.rvm
:members:

74
doc/ref/states/extend.rst Normal file
View File

@ -0,0 +1,74 @@
===========================
Extending External SLS Data
===========================
Sometimes a state defined in one SLS file will need to be modified from a
separate SLS file. A good example of this is when an argument needs to be
overwritten or when a service needs to watch an additional state.
The Extend Declaration
----------------------
The standard way to extend is via the extend declaration. The extend
declaration is a top level declaration like ``include`` and encapsulates ID
declaration data included from other SLS files. A standard extend looks like
this:
.. code-block:: yaml
include:
- http
- ssh
extend:
apache:
file:
- name: /etc/httpd/conf/httpd.conf
- source: salt://http/httpd2.conf
ssh-server:
service:
- watch:
- file: /etc/ssh/banner
/etc/ssh/banner:
file:
- managed
- source: salt://ssh/banner
A few critical things happened here, first off the sls files that are going to
be extended are included, then the extend dec is defined. Under the extend dec
2 IDs are extended, the apache ID's file state is overwritten with a new name
and source. Than the ssh server is extended to watch the banner file in
addition to anything it is already watching.
The Requisite "in" Statement
----------------------------
Since one of the most common things to do when extending another sls is to add
states for a service to watch, or anything for a watcher to watch, the
requisite in statement was added to 0.9.8 to make extending the watch and
require lists easier. The ssh-server extend statement above could be more
cleanly defined like so:
.. code-block:: yaml
include:
- ssh
/etc/ssh/banner:
file:
- managed
- source: salt://ssh/banner
- watch_in:
- service: ssh-server
Rules to Extend By
------------------
There are a few rules to remember when extending states:
1. Always include the sls being extended with an include declaration
2. Requisites (watch and require) are appended to, everything else is
overwritten
3. extend is a top level declaration, like an ID declaration, cannot be
declared twice in a single sls
4. Many IDs can be extended under the extend declaration

199
doc/ref/states/highstate.rst
View File

@ -13,8 +13,14 @@ The Salt State Tree
Configurable via :conf_master:`state_top`.
.. seealso:: :doc:`A detailed description of the top file </ref/states/top>`
.. glossary::
State tree
A collection of ``sls`` files.
A collection of ``sls`` files that live under the directory specified
in :conf_master:`file_roots`. A state tree can be organized into
:term:`sls modules`.
Include declaration
-------------------
@ -27,13 +33,13 @@ Include declaration
Occurs only in the top level of the highstate structure.
Example:
Example:
.. code-block:: yaml
.. code-block:: yaml
include:
- edit.vim
- http.server
include:
- edit.vim
- http.server
Module reference
----------------
@ -59,8 +65,10 @@ ID declaration
Occurs on the top level or under the :term:`extend declaration`.
.. note:: Naming gotchas
Must **not** contain a dot, otherwise highstate summary output will be
unpredictable.
unpredictable. (This has been fixed in versions 0.9.7 and above)
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
@ -72,13 +80,35 @@ Extend declaration
.. glossary::
Extend declaration
Used to extend a :term:`name declaration` from an included ``sls
module``. The keys of the extend declaration always define existing
:term:`ID declarations <ID declaration>` which have been defined in
included ``sls modules``.
Extends a :term:`name declaration` from an included ``sls module``. The
keys of the extend declaration always define existing :term:`ID
declarations <ID declaration>` which have been defined in included
``sls modules``.
Occurs only in the top level and defines a dictionary.
Extend declarations are useful for adding-to or overriding parts of a
:term:`state declaration` that is defined in another ``sls`` files. In the
following contrived example, the shown ``mywebsite.sls`` file is ``include``
-ing and ``extend`` -ing the ``apache.sls`` module in order to add a ``watch``
declaration that will restart Apache whenever the Apache configuration file,
``mywebsite`` changes.
.. code-block:: yaml
include:
- apache
extend:
apache:
service:
- watch:
- file: mywebsite
mywebsite:
file:
- managed
State declaration
-----------------
@ -129,8 +159,17 @@ Function declaration
.. glossary::
Function declaration
The name of the function to call within the state. Any given state
declaration can only have a single function.
The name of the function to call within the state. A state declaration
can contain only a single function declaration.
For example, the following state declaration calls the :mod:`installed
<salt.states.pkg.installed>` function in the ``pkg`` state module:
.. code-block:: yaml
httpd:
pkg:
- installed
Occurs as the only index in the :term:`state declaration` list.
@ -146,16 +185,75 @@ Function arg declaration
Occurs under a :term:`function declaration`.
For example in the following state declaration ``user``, ``group``, and
``mode`` are passed as arguments to the :mod:`managed
<salt.states.file.managed>` function in the ``file`` state module:
.. code-block:: yaml
/etc/http/conf/http.conf:
file:
- managed
- user: root
- group: root
- mode: 644
Name declaration
----------------
.. glossary::
Name declaration
Used to override the name argument relative the :term:`state
declaration`. If the name is not specified then the :term:`ID
declaration` satisfies the name argument. The name is always a single
key dictionary referencing a string.
Overrides the ``name`` argument of a :term:`state declaration`. If
``name`` is not specified the :term:`ID declaration` satisfies the
``name`` argument.
The name is always a single key dictionary referencing a string.
Overriding ``name`` is useful for a variety of scenarios.
For example, avoiding clashing ID declarations. The following two state
declarations cannot both have ``/etc/motd`` as the ID declaration:
.. code-block:: yaml
motd_perms:
file:
- managed
- name: /etc/motd
- mode: 644
motd_quote:
file:
- append
- name: /etc/motd
- text: "Of all smells, bread; of all tastes, salt."
Another common reason to override ``name`` is if the ID declaration is long and
needs to be referenced in multiple places. In the example below it is much
easier to specify ``mywebsite`` than to specify
``/etc/apache2/sites-available/mywebsite.com`` multiple times:
.. code-block:: yaml
mywebsite:
file:
- managed
- name: /etc/apache2/sites-available/mywebsite.com
- source: salt://mywebsite.com
a2ensite mywebsite.com:
cmd:
- wait
- unless: test -L /etc/apache2/sites-enabled/mywebsite.com
- watch:
- file: mywebsite
apache2:
service:
- running
- watch:
- file: mywebsite
Names declaration
-----------------
@ -163,20 +261,37 @@ Names declaration
.. glossary::
Names declaration
Used to apply the contents of the :term:`state declaration` to multiple
states, each with its own name.
Expands the contents of the containing :term:`state declaration` into
multiple state declarations, each with its own name.
Example:
For example, given the following state declaration:
.. code-block:: yaml
.. code-block:: yaml
python-pkgs:
pkg:
- installed
- names:
- python-django
- python-crypto
- python-yaml
python-pkgs:
pkg:
- installed
- names:
- python-django
- python-crypto
- python-yaml
Once converted into the :term:`lowstate` data structure the above state
declaration will be expanded into the following three state declarations:
.. code-block:: yaml
python-django:
pkg:
- installed
python-crypto:
pkg:
- installed
python-yaml:
pkg:
- installed
Large example
=============
@ -189,40 +304,22 @@ components.
<Include Declaration>:
- <Module Reference>
- <Module Reference>
<Extend Declaration>:
<ID Declaration>:
<State Declaration>:
- <Function>
- <Function Arg>
- <Function Arg>
- <Function Arg>
- <Name>: <name>
- <Requisite Declaration>:
- <Requisite Reference>
- <Requisite Reference>
<ID Declaration>:
<State Declaration>:
- <Function>
- <Function Arg>
- <Function Arg>
- <Function Arg>
- <Names>:
- <name>
- <name>
- <name>
- <Requisite Declaration>:
- <Requisite Reference>
- <Requisite Reference>
[<overrides>]
<ID Declaration>:
<State Declaration>:
- <Function>
- <Function Arg>
- <Function Arg>
- <Function Arg>
- <Name>
- <Name>: <name>
- <Requisite Declaration>:
- <Requisite Reference>
- <Requisite Reference>
<ID Declaration>:
<State Declaration>:
- <Function>

79
doc/ref/states/index.rst
View File

@ -29,10 +29,11 @@ then enforced.
Understanding the Salt State System Components
==============================================
The Salt state system is comprised of a number of components, as a user, an
The Salt state system is comprised of a number of components. As a user, an
understanding of the sls and renderer systems are needed. But as a developer,
an understanding of salt states, as well as understanding salt states and how
to write the states used by salt.
an understanding of salt states and how to write the states is needed as well.
Salt SLS System
---------------
@ -80,8 +81,8 @@ users.admin states.
The init.sls files are translated to be the state name of the parent
directory, so the ``salt/init.sls`` file translates to the salt state.
The plain files are visible to the minions, as well as the state files, in
salt, everything is a file, there is not "magic translation" of files and file
The plain files are visible to the minions, as well as the state files. In
salt, everything is a file; there is no "magic translation" of files and file
types. This means that a state file can be distributed to minions just like a
plain text or binary file.
@ -91,8 +92,8 @@ SLS Files
The Salt state files are simple sets of data. Since the SLS files are just data
they can be represented in a number of different ways. The default format is
yaml generated from a jinja template. This allows for the states files to have
all the language constructs of Python, and the simplicity of yaml. State files
can then be complicated jinja templates the translate down to yaml, or just
all the language constructs of Python and the simplicity of yaml. State files
can then be complicated jinja templates that translate down to yaml, or just
plain and simple yaml files!
The State files are constructed data structures in a simple format. The format
@ -104,32 +105,32 @@ Here is an example of a Salt State:
.. code-block:: yaml
vim:
pkg:
- installed
pkg:
- installed
salt:
pkg:
- latest
service:
- running
- require:
- file: /etc/salt/minion
- pkg: salt
- names:
- salt-master
- salt-minion
- watch:
- file: /etc/salt/minion
pkg:
- latest
service:
- running
- require:
- file: /etc/salt/minion
- pkg: salt
- names:
- salt-master
- salt-minion
- watch:
- file: /etc/salt/minion
/etc/salt/minion:
file:
- managed
- source: salt://salt/minion
- user: root
- group: root
- mode: 644
- require:
- pkg: salt
file:
- managed
- source: salt://salt/minion
- user: root
- group: root
- mode: 644
- require:
- pkg: salt
This short stanza will ensure that vim is installed, salt is installed and up
to date, the salt-master and salt-minion daemons are running and the Salt
@ -144,19 +145,19 @@ The top file is the mapping for the state system. The top file specifies which
minions should have which modules applied and which environments they should
draw the states from.
The top file works by specifying the environment, containing matchers with
The top file works by specifying the environment, containing matchers with
lists of Salt states sent to the matching minions:
.. code-block:: yaml
base:
'*':
- salt
- users
- users.admin
'saltmaster.*':
- match: pcre
- salt.master
'*':
- salt
- users
- users.admin
'saltmaster.*':
- match: pcre
- salt.master
This simple example uses the base environment, which is built into the default
salt setup, and then all minions will have the modules salt, users and
@ -169,7 +170,7 @@ Renderer System
The Renderer system is a key component to the state system. SLS files are
representations of Salt "high data" structures. All Salt cares about when
reading an sls file is the data structure that is produced from file.
reading an sls file is the data structure that is produced from the file.
This allows Salt states to be represented by multiple types of files. The
Renderer system can be used to allow different formats to be used for sls

182
doc/ref/states/ordering.rst
View File

@ -9,12 +9,188 @@ order is not necessarily defined the way you want it.
A few tools exist in Salt to set up the correct state ordering. These tools
consist of requisite declarations and order options.
.. note::
Salt does **not** execute :term:`state declarations <state declaration>` in
the order they appear in the source.
Requisite Statements
====================
.. note::
This document represents behavior exhibited by Salt requisites as of
version 0.9.7 of Salt.
Often when setting up states any single action will require or depend on
another action. Salt allows you to build relationships between states with
requisite statements. A requisite statement ensure that the named state is
evaluated before the state requiring it. There are two types of requisite
statements in Salt, **require** and **watch**.
These requisite statements are applied to a specific state declaration:
.. code-block:: yaml
httpd:
pkg:
- installed
file:
- managed
- name: /etc/httpd/conf/httpd.conf
- source: salt://httpd/httpd.conf
- require:
- pkg: httpd
In this example we use the **require** requisite to declare that the file
/etc/httpd/conf/httpd.conf should only be set up if the pkg state executes
successfully.
The requisite system works by finding the states that are required and
executing them before the state that requires them. Then the required states
can be evaluated to see if they have executed correctly.
Multiple Requisites
-------------------
The requisite statement is passed as a list, allowing for the easy addition of
more requisites. Both requisite types can also be separately declared:
.. code-block:: yaml
httpd:
pkg:
- installed
service:
- running
- enable: True
- watch:
- file: /etc/httpd/conf/httpd.conf
- require:
- pkg: httpd
- user: httpd
- group: httpd
file:
- managed
- name: /etc/httpd/conf/httpd.conf
- source: salt://httpd/httpd.conf
- require:
- pkg: httpd
user:
- present
group:
- present
In this example the httpd service is only going to be started if the package,
user, group and file are executed successfully.
The Require Requisite
---------------------
The foundation of the requisite system is the ``require`` requisite. The
require requisite ensures that the required state(s) are executed before the
requiring state. So, if a state is declared that sets down a vimrc, then it
would be pertinent to make sure that the vimrc file would only be set down if
the vim package has been installed:
.. code-block:: yaml
vim:
pkg:
- installed
file:
- managed
- source: salt://vim/vimrc
- require:
- pkg: vim
In this case, the vimrc file will only be applied by Salt if and after the vim
package is installed.
The Watch Requisite
-------------------
The ``watch`` requisite is more advanced than the ``require`` requisite. The
watch requisite executes the same logic as require (therefore if something is
watched it does not need to also be required) with the addition of executing
logic if the required states have changed in some way.
The watch requisite checks to see if the watched states have returned any
changes. If the watched state returns changes, and the watched states execute
successfully, then the watching state will execute a function that reacts to
the changes in the watched states.
Perhaps an example can better explain the behavior:
.. code-block:: yaml
redis:
pkg:
- latest
file:
- managed
- source: salt://redis/redis.conf
- name: /etc/redis.conf
- require:
- pkg: redis
service:
- running
- enable: True
- watch:
- file: /etc/redis.conf
- pkg: redis
In this example the redis service will only be started if the file
/etc/redis.conf is applied, and the file is only applied if the package is
installed. This is normal require behavior, but if the watched file changes,
or the watched package is installed or upgraded, then the redis service is
restarted.
Watch and the Watcher Function
------------------------------
The watch requisite is based on the ``watcher`` function, state python
modules can include a function called watcher, this function is then called
if the watch call is invoked. In the case of the service module the underlying
service is restarted. In the case of the cmd state the command is executed.
The watcher function for the service state looks like this:
.. code-block:: python
def watcher(name, sig=None):
'''
The service watcher, called to invoke the watch command.
name
The name of the init or rc script used to manage the service
sig
The string to search for when looking for the service process with ps
'''
if __salt__['service.status'](name, sig):
changes = {name: __salt__['service.restart'](name)}
return {'name': name,
'changes': changes,
'result': True,
'comment': 'Service restarted'}
return {'name': name,
'changes': {},
'result': True,
'comment': 'Service {0} started'.format(name)}
The watch requisite only works if the state that is watching has a watcher
function written. If watch is set on a state that does not have a watcher
function (like pkg), then the listed states will behave only as if they were
under a ``require`` statement.
The Order Option
================
Before using the order option, remember that the majority of state ordering
should be done with requisite statements, and that a requisite statement
will override an order option.
should be done with a :term:`requisite declaration`, and that a requisite
declaration will override an order option.
The order option is used by adding an order number to a state declaration
with the option `order`:
@ -32,7 +208,7 @@ installed in tandem with any other state declaration set to the order `1`.
Any state declared without an order option will be executed after all states
with order options are executed.
But this construct can only handle ordering states from the beggining.
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``:

47
doc/ref/states/providers.rst Normal file
View File

@ -0,0 +1,47 @@
===============
State Providers
===============
.. versionadded:: 0.9.8
Salt predetermines what modules should be mapped to what uses based on the
properties of a system. These determinations are generally made for modules
that provide things like package and service management.
Sometimes in states it may be needed for an alternative module to be used
to provide the functionality needed. For instance, an Arch Linux system may
have been set up with systemd support, so instead of using the default service
module detected for Arch Linux, the systemd module can be used:
.. code-block:: yaml
httpd:
service:
- running
- enable: True
- provider: systemd
In this instance the systemd module will replace the service virtual module
which is used by default on Arch Linux, and the httpd service will be set up
using systemd.
Arbitrary Module Redirects
===========================
The provider statement can also be used for more powerful means, instead of
overwriting or extending the module used for the named service an arbitrary
module can be used to provide certain functionality.
.. code-block:: yaml
emacs:
pkg:
- installed
- provider:
- pkg: yumpkg5
- cmd: customcmd
In this example the default pkg module is being redirected to use the yumpkg5
module (yum via shelling out instead of via the yum api), but is also using
a custom module to invoke commands. This could be used to dramatically change
the behavior of a given state.

2
doc/ref/states/top.rst
View File

@ -121,7 +121,7 @@ A clean and recommended setup for multiple environments would look like this:
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:
.. code-block:: yaml
dev:

75
doc/ref/states/writing.rst
View File

@ -34,8 +34,11 @@ directly define the user interface.
Using Custom State Modules
==========================
Place your custom state modules inside a ``_states`` directory within the
``file_roots`` specified by the master config file.
Place your custom state modules inside a ``_states`` directory within the
``file_roots`` specified by the master config file. These custom state modules
can then be distributed in a number of ways. Custom state modules are
distributed when state.highstate is run, or via the saltutil.sync_states
function.
Cross Calling Modules
=====================
@ -69,3 +72,71 @@ A State Module must return a dict containing the following keys/values:
- **result:** A boolean value. *True* if the action was successful, otherwise
*False*.
- **comment:** A string containing a summary of the result.
Watcher Function
================
If the state being written should support the watch requisite then a watcher
function needs to be declared. The watcher function is called whenever the
watch requisite is invoked and should be generic to the behavior of the state
itself.
The watcher function should accept all of the options that the normal state
functions accept (as they will be passed into the watcher function).
A watcher function typically is used to execute state specific reactive
behavior, for instance, the watcher for the service module restarts the
named service and makes it useful for the watcher to make the service
react to changes in the environment.
The watcher function also needs to return the same data that a normal state
function returns.
Mod_init Interface
==================
Some states need to execute something only once to ensure that an environment
has been set up, or certain conditions global to the state behavior can be
predefined. This is the realm of the mod_init interface.
A state module can have a function called **mod_init** which executes when the
first state of this type is called. This interface was created primarily to
improve the pkg state. When packages are installed the package metadata needs
to be refreshed, but refreshing the package metadata every time a package is
installed is wasteful. The mod_init function for the pkg state sets a flag down
so that the first, and only the first, package installation attempt will refresh
the package database (the package database can of course be manually called to
refresh via the ``refresh`` option in the pkg state).
The mod_init function must accept the **Low State Data** for the given
executing state as an argument. The low state data is a dict and can be seen by
executing the state.show_lowstate function. Then the mod_init function must
return a bool. If the return value is True, then the mod_init function will not
be executed again, meaning that the needed behavior has been set up. Otherwise,
if the mod_init function returns False, then the function will be called the
next time.
A good example of the mod_init function is found in the pkg state module:
.. code-block:: python
def mod_init(low):
'''
Refresh the package database here so that it only needs to happen once
'''
if low['fun'] == 'installed' or low['fun'] == 'latest':
rtag = __gen_rtag()
if not os.path.exists(rtag):
open(rtag, 'w+').write('')
return True
else:
return False
The mod_init function in the pkg state accepts the low state data as ``low``
and then checks to see if the function being called is going to install
packages, if the function is not going to install packages then there is no
need to refresh the package database. Therefore if the package database is
prepared to refresh, then return True and the mod_init will not be called
the next time a pkg state is evaluated, otherwise return False and the mod_init
will be called next time a pkg state is evaluated.

8
doc/ref/syndic.rst
View File

@ -6,7 +6,7 @@ The Salt Syndic interface is a powerful tool which allows for the construction
of Salt command topologies. A basic Salt setup has a Salt Master commanding a
group of Salt Minions. The Syndic interface is a special passthrough
minion, it is run on a master and connects to another master, then the master
that the Syndic minion is listening to can control the minions attatched to
that the Syndic minion is listening to can control the minions attached to
the master running the syndic.
The intent for supporting many layouts is not presented with the intent of
@ -16,7 +16,7 @@ of controlling many systems.
Configuring the Syndic
======================
Since the Syndic only needs to be attatched to a higher level master the
Since the Syndic only needs to be attached to a higher level master the
configuration is very simple. On a master that is running a syndic to connect
to a higher level master the syndic_master option needs to be set in the
master config file. The syndic_master option contains the hostname or ip
@ -25,7 +25,7 @@ running on.
The master that the syndic connects to sees the syndic as an ordinary minion,
and treats it as such. the higher level master will need to accept the syndic's
minion key like any other minion. This master will also need to set the
minion key like any other minion. This master will also need to set the
order_masters value in the configuration to True. The order_masters option in
the config on the higher level master is very important, to control a syndic
extra information needs to be sent with the publications, the order_masters
@ -34,7 +34,7 @@ option makes sure that the extra data is sent out.
Running the Syndic
==================
The Syndic is a seperate daemon that needs to be started on the master that is
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.

12
doc/topics/community.rst
View File

@ -29,8 +29,11 @@ IRC
The ``#salt`` IRC channel is hosted on the popular `Freenode`__ network. You
can use the `Freenode webchat client`__ right from your browser.
`Logs of the IRC channel activity`__ are being collected courtesy of Moritz Lenz.
.. __: http://freenode.net/irc_servers.shtml
.. __: http://webchat.freenode.net/?channels=salt&uio=Mj10cnVlJjk9dHJ1ZSYxMD10cnVl83
.. __: http://irclog.perlgeek.de/salt/
.. _community-github:
@ -54,6 +57,15 @@ http://red45.wordpress.com/
.. _`The Red45`: http://red45.wordpress.com/
Example Salt States
===================
The official ``salt-states`` repository is:
https://github.com/saltstack/salt-states
Another good example from one of our users is:
https://github.com/blast-hardcheese/blast-salt-states
Follow on ohloh
===============

4
doc/topics/configuration.rst
View File

@ -54,6 +54,10 @@ Running Salt
line or assign ``user`` in the
:doc:`configuration file</ref/configuration/master>`.
There is also a full :doc:`troubleshooting guide</topics/troubleshooting/index>`
available.
Manage Salt public keys
=======================

2
doc/topics/index.rst
View File

@ -31,7 +31,7 @@ Parallel execution
The core function of Salt is to enable remote commands to be called in parallel
rather than in serial, to use a secure and encrypted protocol, the smallest and
fastest network payloads possible, and with a simple programmer interface. Salt
fastest network payloads possible, and with a simple programming interface. Salt
also introduces more granular controls to the realm of remote execution,
allowing for commands to be executed in parallel and for systems to be targeted
based on more than just hostname, but by system properties.

272
doc/topics/installation/arch.rst Normal file
View File

@ -0,0 +1,272 @@
==========
Arch Linux
==========
Salt has primarily been developed on Arch Linux, meaning it is known to
work very well on that distribution. The lead developer, Thomas S. Hatch
(thatch45) has been a TU (Trusted User) for the Arch Linux distribution,
and has written a number of Arch-specific tools in the past.
Salt, while not Arch-specific, is packaged for and works well on Arch Linux.
Installation
============
Salt is currently available via the Arch User Repository (AUR). There are
currently stable and -git packages available.
Stable Release
--------------
To install Salt stable releases from the Arch Linux AUR, use the commands:
.. code-block:: bash
wget https://aur.archlinux.org/packages/sa/salt/salt.tar.gz
tar xf salt.tar.gz
cd salt/
makepkg -is
A few of Salt's dependencies are currently only found within the AUR, so you'll
need to download and run ``makepkg -is`` on these as well. As a reference, Salt
currently relies on the following packages only available via the AUR:
* https://aur.archlinux.org/packages/py/python2-msgpack/python2-msgpack.tar.gz
* https://aur.archlinux.org/packages/py/python2-psutil/python2-psutil.tar.gz
.. note:: yaourt
If you chose to use a tool such as Yaourt_ the dependencies will be
gathered and built for you automatically.
The command to install salt using the yaourt tool is:
.. code-block:: bash
yaourt salt
.. _Yaourt: https://aur.archlinux.org/packages.php?ID=5863
Tracking develop
----------------
To install the bleeding edge version of Salt (**may include bugs!**),
you can use the -git package. Installing the -git package can be done
using the commands:
.. code-block:: bash
wget https://aur.archlinux.org/packages/sa/salt-git/salt-git.tar.gz
tar xf salt-git.tar.gz
cd salt-git/
makepkg -is
A few of Salt's dependencies are currently only found within the AUR, so you'll
need to download and run ``makepkg -is`` on these as well. As a reference, Salt
currently relies on the following packages only available via the AUR:
* https://aur.archlinux.org/packages/py/python2-msgpack/python2-msgpack.tar.gz
* https://aur.archlinux.org/packages/py/python2-psutil/python2-psutil.tar.gz
.. note:: yaourt
If you chose to use a tool such as Yaourt_ the dependencies will be
gathered and built for you automatically.
The command to install salt using the yaourt tool is:
.. code-block:: bash
yaourt salt-git
.. _Yaourt: https://aur.archlinux.org/packages.php?ID=5863
Configuration
=============
In the sections below I'll outline configuration options for both the Salt
Master and Salt Minions.
The Salt package installs two template configuration files,
``/etc/salt/master.template`` and ``/etc/salt/minion.template``. You'll need
to copy these .template files into place and make a few edits. First, copy
them into place as seen here:
.. code-block:: bash
cp /etc/salt/master.template /etc/salt/master
cp /etc/salt/minion.template /etc/salt/minion
Note: You'll only need to copy the config for the service you're going to run.
Once you've copied the config into place you'll need to make changes specific
to your setup. Below I'll outline suggested configuration changes to the
Master, after which I'll outline configuring the Minion.
Master Configuration
====================
This section outlines configuration of a Salt Master, which is used to control
other machines known as "minions" (see "Minion Configuration" for instructions
on configuring a minion). This will outline IP configuration, and a few key
configuration paths.
**Interface**
By default the Salt master listens on ports 4505 and 4506 on all interfaces
(0.0.0.0). If you have a need to bind Salt to a specific IP, redefine the
"interface" directive as seen here:
.. code-block:: diff
- #interface: 0.0.0.0
+ interface: 10.0.0.1
**rc.conf**
You'll need to activate the Salt Master in your rc.conf file. Using your
favorite editor, open ``/etc/rc.conf`` and add the salt-master.
.. code-block:: diff
-DAEMONS=(syslog-ng network crond)
+DAEMONS=(syslog-ng network crond @salt-master)
**Start the Master**
Once you've completed all of these steps you're ready to start your Salt
Master. You should be able to start your Salt Master now using the command
seen here:
.. code-block:: bash
rc.d start salt-master
If your Salt Master doesn't start successfully, go back through each step and
see if anything was missed. Salt doesn't take much configuration (part of its
beauty!), and errors are usually simple mistakes.
Minion Configuration
====================
Configuring a Salt Minion is surprisingly simple. Unless you have a real need
for customizing your minion configuration (which there are plenty of options if
you are so inclined!), there is one simple directive that needs to be updated.
That option is the location of the master.
By default a Salt Minion will try to connect to the dns name "salt". If you
have the ability to update DNS records for your domain you might create an A or
CNAME record for "salt" that points to your Salt Master. If you are able to do
this you likely can do without any minion configuration at all.
If you are not able to update DNS, you'll simply need to update one entry in
the configuration file. Using your favorite editor, open the minion
configuration file and update the "master" entry as seen here.
.. code-block:: diff
- #master: salt
+ master: 10.0.0.1
Simply update the master directive to the IP or hostname of your Salt Master.
Save your changes and you're ready to start your Salt Minion. Advanced
configuration options are covered in another chapter.
**rc.conf**
Before you're able to start the Salt Minion you'll need to update your rc.conf
file. Using your favorite editor open ``/etc/rc.conf`` and add this line:
.. code-block:: diff
-DAEMONS=(syslog-ng network crond)
+DAEMONS=(syslog-ng network crond @salt-minion)
**Start the Minion**
Once you've completed all of these steps you're ready to start your Salt
Minion. You should be able to start your Salt Minion now using the command
seen here:
.. code-block:: bash
rc.d start salt-minion
If your Salt Minion doesn't start successfully, go back through each step and
see if anything was missed. Salt doesn't take much configuration (part of its
beauty!), and errors are usually simple mistakes.
Tying It All Together
======================
If you've successfully completed each of the steps above you should have a
running Salt Master and a running Salt Minion. The Minion should be configured
to point to the Master. To verify that there is communication flowing between
the Minion and Master we'll run a few initial ``salt`` commands. These commands
will validate the Minions RSA encryption key, and then send a test command to
the Minion to ensure that commands and responses are flowing as expected.
**Key Management**
Salt uses AES encryption for all communication between the Master and the
Minion. This ensures that the commands you send to your Minions (your cloud)
can not be tampered with, and that communication between Master and Minion is
only done through trusted, accepted keys.
Before you'll be able to do any remote execution or configuration management you'll
need to accept any pending keys on the Master. Run the ``salt-key`` command to
list the keys known to the Salt Master.
.. code-block:: bash
[root@master ~]# salt-key -L
Unaccepted Keys:
alpha
bravo
charlie
delta
Accepted Keys:
This example shows that the Salt Master is aware of four Minions, but none of
the keys have been accepted. To accept the keys and allow the Minions to be
controlled by the Master, again use the ``salt-key`` command:
.. code-block:: bash
[root@master ~]# salt-key -A
[root@master ~]# salt-key -L
Unaccepted Keys:
Accepted Keys:
alpha
bravo
charlie
delta
The ``salt-key`` command allows for signing keys individually or in bulk. The
example above, using ``-A`` bulk-accepts all pending keys. To accept keys
individually use the lowercase of the same option, ``-a keyname``.
Sending Commands
================
Everything should be set for you to begin remote management of your Minions.
Whether you have a few or a few-dozen, Salt can help you manage them easily!
For final verification, send a test function from your Salt Master to your
minions. If all of your minions are properly communicating with your Master,
you should "True" responses from each of them. See the example below to send
the ``test.ping`` remote command:
.. code-block:: bash
[root@master ~]# salt '*' test.ping
{'alpha': True}
Where Do I Go From Here
========================
Congratulations! You've successfully configured your first Salt Minions and are
able to send remote commands. I'm sure you're eager to learn more about what
Salt can do. Depending on the primary way you want to manage your machines you
may either want to visit the section regarding Salt States, or the section on
Modules.

40
doc/topics/installation/debian.rst Normal file
View File

@ -0,0 +1,40 @@
===============
Debian & Ubuntu
===============
Ubuntu
------
We are working to get Salt into apt. In the meantime we have a PPA available
for Lucid:
.. code-block:: bash
aptitude -y install python-software-properties
add-apt-repository ppa:saltstack/salt
aptitude update
aptitude install salt-master # on the master
aptitude install salt-minion # on the minion
aptitude install salt-syndic # instead of a slaved master
Debian
------
`A deb package is currently in testing`__ for inclusion in apt. Until that is
accepted you can install Salt by downloading the latest ``.deb`` in the
`downloads section on GitHub`__ and installing that manually using ``dpkg -i``.
.. __: http://mentors.debian.net/package/salt
.. __: https://github.com/saltstack/salt/downloads
.. admonition:: Installing ZeroMQ on Squeeze (Debian 6)
There is a `python-zmq`__ package available in Debian \"wheezy (testing)\".
If you don't have that repo enabled the best way to install Salt and pyzmq
is by using ``pip`` (or ``easy_install``):
.. code-block:: bash
pip install pyzmq salt
.. __: http://packages.debian.org/search?keywords=python-zmq

209
doc/topics/installation/fedora.rst Normal file
View File

@ -0,0 +1,209 @@
==================================
Fedora & CentOS / Enterprise Linux
==================================
Beginning with version 0.9.4, Salt has been available in the primary Fedora
repositories and is available for installation 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!
.. admonition:: CentOS/EL 5
We are still working to get msgpack packaged for Python 2.6 so Salt is not
yet (but nearly) in EPEL 5. In the meantime you can install Salt via our
Fedora People repository:
.. code-block:: bash
wget -O /etc/yum.repos.d/epel-salt.repo \\
http://repos.fedorapeople.org/repos/herlo/salt/epel-salt.repo
Installation
============
Salt can be installed using ``yum`` and is available in the standard Fedora
repositories.
Stable Release
--------------
Salt is packaged separately for the minion and the master. You'll only need to
install the appropriate package for the role you need the machine to play. This
means you're going to want one master and a whole bunch of minions!
.. code-block:: bash
yum install salt-master
yum install salt-minion
Configuration
=============
In the sections below I'll outline configuration options for both the Salt
Master and Salt Minions.
Master Configuration
====================
This section outlines configuration of a Salt Master, which is used to control
other machines known as "minions" (see "Minion Configuration" for instructions
on configuring a minion). This will outline IP configuration, and a few key
configuration paths.
**Interface**
By default the Salt master listens on ports 4505 and 4506 on all interfaces
(0.0.0.0). If you have a need to bind Salt to a specific IP, redefine the
"interface" directive as seen here:
.. code-block:: diff
- #interface: 0.0.0.0
+ interface: 10.0.0.1
**Enable the Master**
You'll also likely want to activate the Salt Master in systemd, configuring the
Salt Master to start automatically at boot.
.. code-block:: bash
systemctl enable salt-master.service
**Start the Master**
Once you've completed all of these steps you're ready to start your Salt
Master. You should be able to start your Salt Master now using the command
seen here:
.. code-block:: bash
systemctl start salt-master.service
If your Salt Master doesn't start successfully, go back through each step and
see if anything was missed. Salt doesn't take much configuration (part of its
beauty!), and errors are usually simple mistakes.
Minion Configuration
====================
Configuring a Salt Minion is surprisingly simple. Unless you have a real need
for customizing your minion configuration (which there are plenty of options if
you are so inclined!), there is one simple directive that needs to be updated.
That option is the location of the master.
By default a Salt Minion will try to connect to the dns name "salt". If you
have the ability to update DNS records for your domain you might create an A or
CNAME record for "salt" that points to your Salt Master. If you are able to do
this you likely can do without any minion configuration at all.
If you are not able to update DNS, you'll simply need to update one entry in
the configuration file. Using your favorite editor, open the minion
configuration file and update the "master" entry as seen here:
.. code-block:: diff
- #master: salt
+ master: 10.0.0.1
Simply update the master directive to the IP or hostname of your Salt Master.
Save your changes and you're ready to start your Salt Minion. Advanced
configuration options are covered in another chapter.
**Enable the Minion**
You'll need to configure the minion to auto-start at boot. You can toggle
that option through systemd.
.. code-block:: bash
systemctl enable salt-minion.service
**Start the Minion**
Once you've completed all of these steps you're ready to start your Salt
Minion. You should be able to start your Salt Minion now using the command
here:
.. code-block:: bash
systemctl start salt-minion.service
If your Salt Minion doesn't start successfully, go back through each step and
see if anything was missed. Salt doesn't take much configuration (part of its
beauty!), and errors are usually simple mistakes.
Tying It All Together
======================
If you've successfully completed each of the steps above you should have a
running Salt Master and a running Salt Minion. The Minion should be configured
to point to the Master. To verify that there is communication flowing between
the Minion and Master we'll run a few initial ``salt`` commands. These commands
will validate the Minions RSA encryption key, and then send a test command to
the Minion to ensure that commands and responses are flowing as expected.
**Key Management**
Salt uses AES encryption for all communication between the Master and the
Minion. This ensures that the commands you send to your Minions (your cloud)
can not be tampered with, and that communication between Master and Minion is
only done through trusted, accepted keys.
Before you'll be able to do any remote execution or configuration management
you'll need to accept any pending keys on the Master. Run the ``salt-key``
command to list the keys known to the Salt Master:
.. code-block:: bash
[root@master ~]# salt-key -L
Unaccepted Keys:
alpha
bravo
charlie
delta
Accepted Keys:
This example shows that the Salt Master is aware of four Minions, but none of
the keys have been accepted. To accept the keys and allow the Minions to be
controlled by the Master, again use the ``salt-key`` command:
.. code-block:: bash
[root@master ~]# salt-key -A
[root@master ~]# salt-key -L
Unaccepted Keys:
Accepted Keys:
alpha
bravo
charlie
delta
The ``salt-key`` command allows for signing keys individually or in bulk. The
example above, using ``-A`` bulk-accepts all pending keys. To accept keys
individually use the lowercase of the same option, ``-a keyname``.
Sending Commands
================
Everything should be set for you to begin remote management of your Minions.
Whether you have a few or a few-dozen, Salt can help you manage them easily!
For final verification, send a test function from your Salt Master to your
minions. If all of your minions are properly communicating with your Master,
you should "True" responses from each of them. See the example below to send
the ``test.ping`` remote command:
.. code-block:: bash
[root@master ~]# salt '*' test.ping
{'alpha': True}
Where Do I Go From Here
========================
Congratulations! You've successfully configured your first Salt Minions and are
able to send remote commands. I'm sure you're eager to learn more about what
Salt can do. Depending on the primary way you want to manage your machines you
may either want to visit the section regarding Salt States, or the section on
Modules.

137
doc/topics/tutorials/freebsd.rst → doc/topics/installation/freebsd.rst
View File

@ -1,27 +1,27 @@
.. _introduction:
Introduction
============
=======
FreeBSD
=======
Salt was added to the FreeBSD ports tree Dec 26th, 2011 by Christer Edwards
<christer.edwards@gmail.com>. It has been tested on FreeBSD 8.2 and 9.0RC
<christer.edwards@gmail.com>. It has been tested on FreeBSD 7.4, 8.2 and 9.0
releases.
Salt is dependent on the following additional ports. These will be installed as
dependencies of the ``sysutils/salt`` port::
dependencies of the ``sysutils/salt`` port. ::
/devel/py-yaml
/devel/py-pyzmq
/devel/py-Jinja2
/devel/py-msgpack
/security/py-pycrypto
/security/py-m2crypto
.. _installation:
Installation
============
To install Salt from the FreeBSD ports tree, use the command::
To install Salt from the FreeBSD ports tree, use the command:
.. code-block:: bash
cd /usr/ports/sysutils/salt && make install clean
@ -29,18 +29,19 @@ Once the port is installed you'll need to make a few configuration changes.
These include defining the IP to bind to (optional), and some configuration
path changes to make salt fit more natively into the FreeBSD filesystem tree.
.. _configuration:
Configuration
=============
In the sections below I'll outline configuration options for both the Salt
Master and Salt Minions.
The Salt port installs two sample configuration files, salt/master.sample and
salt/minion.sample (these should be installed in /usr/local/etc/, unless you use a
different %%PREFIX%%). You'll need to copy these .sample files into place and
make a few edits. First, copy them into place as seen here::
The Salt port installs two sample configuration files, ``salt/master.sample``
and ``salt/minion.sample`` (these should be installed in ``/usr/local/etc/``,
unless you use a different ``%%PREFIX%%``). You'll need to copy these
.sample files into place and make a few edits. First, copy them into place
as seen here:
.. code-block:: bash
cp /usr/local/etc/salt/master.sample /usr/local/etc/salt/master
cp /usr/local/etc/salt/minion.sample /usr/local/etc/salt/minion
@ -51,8 +52,6 @@ Once you've copied the config into place you'll need to make changes specific
to your setup. Below I'll outline suggested configuration changes to the
Master, after which I'll outline configuring the Minion.
.. _master_configuration:
Master Configuration
====================
@ -65,47 +64,31 @@ configuration paths.
By default the Salt master listens on ports 4505 and 4506 on all interfaces
(0.0.0.0). If you have a need to bind Salt to a specific IP, redefine the
"interface" directive as seen here::
"interface" directive as seen here.
.. code-block:: diff
- #interface: 0.0.0.0
+ interface: 10.0.0.1
**pki_dir**
Salt is primarily developed on Linux, and as such carries some Linux-isms in
its development and configuration. These are all very easily remedied to more
seamlessly fit into FreeBSD. One such configuration option is the *pki_dir:*
directive. To ensure all of Salts files end up where you expect, you'll likely
want to update this line as seen here::
- #pki_dir: /etc/salt/pki
+ pki_dir: /usr/local/etc/salt/pki
**file_roots**
Finally, if you plan on using Salts state-management features, you'll want to
update the *file_roots:* directive. This directive defines the location of the
state files. I suggest updating this directive as seen here::
- #file_roots:
- # base:
- # - /srv/salt
+ file_roots:
+ base:
+ - /usr/local/etc/salt/states
**rc.conf**
Last but not least you'll need to activate the Salt Master in your rc.conf
file. Using your favorite editor, open /etc/rc.conf or /etc/rc.conf.local and
add this line::
file. Using your favorite editor, open ``/etc/rc.conf`` or
``/etc/rc.conf.local`` and add this line.
.. code-block:: diff
+ salt_master_enable="YES"
**Start the Master**
Once you've completed all of these steps you're ready to start your Salt
Master. The Salt port installs an rc script which should be used to manage your
Salt Master. You should be able to start your Salt Master now using the command
seen here::
seen here:
.. code-block:: bash
service salt_master start
@ -113,8 +96,6 @@ If your Salt Master doesn't start successfully, go back through each step and
see if anything was missed. Salt doesn't take much configuration (part of its
beauty!), and errors are usually simple mistakes.
.. _ minion_configuration:
Minion Configuration
====================
@ -130,7 +111,9 @@ this you likely can do without any minion configuration at all.
If you are not able to update DNS, you'll simply need to update one entry in
the configuration file. Using your favorite editor, open the minion
configuration file and update the "master" entry as seen here::
configuration file and update the "master" entry as seen here.
.. code-block:: diff
- #master: salt
+ master: 10.0.0.1
@ -139,29 +122,22 @@ Simply update the master directive to the IP or hostname of your Salt Master.
Save your changes and you're ready to start your Salt Minion. Advanced
configuration options are covered in another chapter.
**pki_dir**
Salt is primarily developed on Linux, and as such carries some Linux-isms in
its development and configuration. These are all very easily remedied to more
seamlessly fit into FreeBSD. One such configuration option is the *pki_dir:*
directive. To ensure all of Salts files end up where you expect, you'll likely
want to update this line as seen here::
- #pki_dir: /etc/salt/pki
+ pki_dir: /usr/local/etc/salt/pki
**rc.conf**
Before you're able to start the Salt Minion you'll need to update your rc.conf
file. Using your favorite editor open /etc/rc.conf or /etc/rc.conf.local and
add this line::
file. Using your favorite editor open ``/etc/rc.conf`` or
``/etc/rc.conf.local`` and add this line.
.. code-block:: diff
+ salt_minion_enable="YES"
Once you've completed all of these steps you're ready to start your Salt
Minion. The Salt port installs an rc script which should be used to manage your
Salt Minion. You should be able to start your Salt Minion now using the command
seen here::
seen here.
.. code-block:: bash
service salt_minion start
@ -169,8 +145,6 @@ If your Salt Minion doesn't start successfully, go back through each step and
see if anything was missed. Salt doesn't take much configuration (part of its
beauty!), and errors are usually simple mistakes.
.. _tying_it_all_together:
Tying It All Together
======================
@ -190,35 +164,37 @@ only done through trusted, accepted keys.
Before you'll be able to do any remote execution or state management you'll
need to accept any pending keys on the Master. Run the ``salt-key`` command to
list the keys known to the Salt Master::
list the keys known to the Salt Master:
.. code-block:: bash
[root@master ~]# salt-key -L
Unaccepted Keys:
avon
bodie
bubbles
marlo
alpha
bravo
charlie
delta
Accepted Keys:
This example shows that the Salt Master is aware of four Minions, but none of
the keys have been accepted. To accept the keys and allow the Minions to be
controlled by the Master, again use the ``salt-key`` command::
controlled by the Master, again use the ``salt-key`` command:
.. code-block:: bash
[root@master ~]# salt-key -A
[root@master ~]# salt-key -L
Unaccepted Keys:
Accepted Keys:
avon
bodie
bubbles
marlo
alpha
bravo
charlie
delta
The ``salt-key`` command allows for signing keys individually or in bulk. The
example above, using ``-A`` bulk-accepts all pending keys. To accept keys
individually use the lowercase of the same option, ``-a keyname``.
.. _sending_commands:
Sending Commands
================
@ -228,12 +204,10 @@ Whether you have a few or a few-dozen, Salt can help you manage them easily!
For final verification, send a test function from your Salt Master to your
minions. If all of your minions are properly communicating with your Master,
you should "True" responses from each of them. See the example below to send
the ``test.ping`` remote command::
the ``test.ping`` remote command. ::
[root@avon ~]# salt '*' test.ping
{'avon': True}
.. _where_do_i_go_from_here:
[root@master ~]# salt 'alpha' test.ping
{'alpha': True}
Where Do I Go From Here
========================
@ -243,3 +217,4 @@ able to send remote commands. I'm sure you're eager to learn more about what
Salt can do. Depending on the primary way you want to manage your machines you
may either want to visit the section regarding Salt States, or the section on
Modules.

24
doc/topics/installation/gentoo.rst Normal file
View File

@ -0,0 +1,24 @@
======
Gentoo
======
Salt can be easily installed on Gentoo:
.. code-block:: bash
emerge pyyaml m2crypto pycrypto jinja pyzmq
Then download and install from source:
1. Download the latest source tarball from the `GitHub downloads`_ directory for
the Salt project.
2. Untar the tarball and run the ``setup.py`` as root:
.. code-block:: bash
tar xf salt-<version>.tar.gz
cd salt-<version>
python setup.py install
.. _GitHub downloads: https://github.com/saltstack/salt/downloads

48
doc/topics/installation/index.rst Normal file
View File

@ -0,0 +1,48 @@
============
Installation
============
The Salt system setup is amazingly simple, as this is one of the central design
goals of Salt.
Dependencies
------------
Salt should run on any Unix-like platform so long as the dependencies are met.
* `Python 2.6`_
* `ZeroMQ`_ >= 2.1.9
* `pyzmq`_ >= 2.1.9 - ZeroMQ Python bindings
* `M2Crypto`_ - Python OpenSSL wrapper
* `PyCrypto`_ - The Python cryptography toolkit
* `msgpack-python`_ - High-performance message interchange format
* `YAML`_ - Python YAML bindings
Optional Dependencies
---------------------
* `Jinja2`_ - parsing Salt States (configurable in the master settings)
* gcc - dynamic `Cython`_ module compiling
.. _`Python 2.6`: http://python.org/download/
.. _`ZeroMQ`: http://www.zeromq.org/
.. _`pyzmq`: https://github.com/zeromq/pyzmq
.. _`M2Crypto`: http://chandlerproject.org/Projects/MeTooCrypto
.. _`msgpack-python`: http://pypi.python.org/pypi/msgpack-python/0.1.12
.. _`YAML`: http://pyyaml.org/
.. _`PyCrypto`: http://www.dlitz.net/software/pycrypto/
.. _`Cython`: http://cython.org/
.. _`Jinja2`: http://jinja.pocoo.org/
Platform-specific installation instructions
-------------------------------------------
.. toctree::
:maxdepth: 1
arch
debian
fedora
freebsd
gentoo
windows

146
doc/topics/installation/windows.rst Normal file
View File

@ -0,0 +1,146 @@
==========
Windows
==========
Salt currently has experimental support for Salt Minions on Windows.
There are no plans for the forseeable future to develop a Salt
Master on Windows. For now you must run your Salt Master on a
supported operating system to control your Salt Minions on Windows.
Many of the standard Salt modules have been ported to work on Windows
and many of the Salt States currently work on Windows, as well.
Installation from source
============
Work is under way to create a Windows installer for Salt, but for now
one must install each dependency separately and configure Salt to
run on your Windows host.
Rather than send you on a wild goose chase across the internet, we've
collected some of the more difficult to find installers in our github repo for you.
Install on Windows XP 32bit
===========================
1. Install `msysgit`_
1. Clone the Salt git repository from github
.. code-block:: bash
git clone git://github.com/saltstack/salt.git
2. Install `Microsoft Visual Studio 2008 Express`_ with the web installer.
Or `download a full iso with the installer`_ .
You must use Visual Studio 2008 Express, **not** Visual Studio 2010 Express.
3. Install `Python 2.7.x`_
4. Add c:\\Python27 to your system path
5. Install the Microsoft Visuall C++ 2008 SP1 Redistributable, `vcredist_x86`_.
6. Install `Win32OpenSSL-1_0_0e.exe`_
#. Choose first option to install in Windows system directory
7. Install `pyzmq-2.1.11.win32-py2.7.msi`_
8. Install `M2Crypto-0.21.1.win32-py2.7.msi`_
9. Install `pycrypto-2.3.win32-py2.7.msi`_
10. Install `PyYAML-3.10.win32-py2.7.msi`_
11. Install `Cython-0.15.1.win32-py2.79.exe`_
12. Download and run `distribute_setup.py`_
.. code-block:: bash
python distribute_setup.py
13. Download and run `pip`_
.. code-block:: bash
python get-pip.py
14. Add c:\\python27\\scripts to your path
15. Close terminal window and open a new terminal window (cmd)
16. Install jinja2
.. code-block:: bash
pip install jinja2
17. Install Messagepack
.. code-block:: bash
pip install msgpack-python
18. Install Salt
.. code-block:: bash
cd ./salt
python setup.py install
19. Edit c:\\etc\\salt\\minon
.. code-block:: bash
master: ipaddress or hostname of your salt-master
master_port: 4506
root_dir: c:\
pki_dir: /etc/salt/pki
cachedir: /var/cache/salt
renderer: yaml_jinja
open_mode: False
multiprocessing: False
20. Start the salt-minion
.. code-block:: bash
cd c:\python27\scripts
python salt-minion
21. On the salt-master accept the new minion's key
.. code-block:: bash
sudo salt-key -A
(This accepts all unaccepted keys. If you're concerned about security just accept the key for this specific minion)
22. Test that your minion is responding
a. On the salt-master run:
.. code-block:: bash
sudo salt '*' test.ping
You should get the following response: {'your minion hostname': True}
.. _msysgit: http://code.google.com/p/msysgit/downloads/list?can=3
.. _Microsoft Visual Studio 2008 Express: http://www.microsoft.com/visualstudio/en-us/products/2008-editions/express
.. _download a full iso with the installer: http://www.microsoft.com/download/en/details.aspx?id=20682
.. _Python 2.7.x: http://www.python.org
.. _vcredist_x86: http://www.microsoft.com/download/en/details.aspx?id=5582
.. _Win32OpenSSL-1_0_0e.exe: http://www.slproweb.com/products/Win32OpenSSL.html
.. _pyzmq-2.1.11.win32-py2.7.msi: https://github.com/zeromq/pyzmq/downloads
.. _M2Crypto-0.21.1.win32-py2.7.msi: http://chandlerproject.org/Projects/MeTooCrypto#Downloads
.. _pycrypto-2.3.win32-py2.7.msi: http://www.voidspace.org.uk/python/modules.shtml#pycrypto
.. _PyYAML-3.10.win32-py2.7.msi: http://pyyaml.org/wiki/PyYAML
.. _Cython-0.15.1.win32-py2.79.exe: http://www.lfd.uci.edu/~gohlke/pythonlibs/#cython
.. _distribute_setup.py: http://python-distribute.org/distribute_setup.py
.. _pip: https://raw.github.com/pypa/pip/master/contrib/get-pip.py

18
doc/topics/jobs/index.rst
View File

@ -20,18 +20,24 @@ cachedir, with a default configuration it is under /var/cache/salt/proc.
Functions in the saltutil Module
================================
Salt 0.9.7 introduced a few new functions to the saltutil module for managing
Salt 0.9.7 introduced a few new functions to the
:doc:`saltutil</ref/modules/all/salt.modules.saltutil>` module for managing
jobs. These functions are:
1. running
1. ``running``
Returns the data of all running jobs that are found in the proc directory.
2. find_job
2. ``find_job``
Returns specific data about a certain job based on job id.
3. signal_job
3. ``signal_job``
Allows for a given jid to be sent a signal.
4. term_job
4. ``term_job``
Sends a termination signal (SIGTERM, 15) to the process controlling the
specified job.
5. kill_job
5. ``kill_job``
Sends a kill signal (SIGKILL, 9) to the process controlling the
specified job.

68
doc/topics/pillar/index.rst Normal file
View File

@ -0,0 +1,68 @@
==============
Pillar of Salt
==============
Pillar is an interface for Salt designed to offer global values to be
distributed to all minions. Pillar data is managed in a similar way to
the salt state tree.
Pillar was added to Salt in version 0.9.8 as an experimental add on.
Declaring the Master Pillar
===========================
The Salt Master server maintains a pillar_roots setup that matches the
structure of the file_roots used in the Salt file server. Like the
Salt file server the ``pillar_roots`` option in the master config is based
on environments mapping to directories. The pillar data is then mapped to
minions based on matchers in a top file which is laid out in the same way
as the state top file.
The configuration for the pillar_roots in the master config is identical in
behavior and function as the file_roots configuration:
.. code-block:: yaml
pillar_roots:
base:
- /srv/pillar
This example configuration declares that the base environment will be located
in the /srv/pillar directory. The top file used matches the name of the top file
used for states, and has the same structure:
.. code-block:: yaml
base:
'*':
- packages
This simple pillar top file declares that information for all minions can be
found in the package's sls file:
.. code-block:: yaml
{% if grains['os'] == 'RedHat' %}
apache: httpd
git: git
{% elif grains['os'] == 'Debian' %}
apache: apache2
git: git-core
{% endif %}
Now this data can be used from within modules, renderers, state sls files and
more via the shared pillar dict:
.. code-block:: yaml
apache:
pkg:
- installed
- name: {{ pillar['apache'] }}
.. code-block:: yaml
git:
pkg:
- installed
- name: {{ pillar['git'] }}

179
doc/topics/releases/0.9.7.rst Normal file
View File

@ -0,0 +1,179 @@
========================
Salt 0.9.7 Release Notes
========================
Salt 0.9.7 is here! The latest iteration of Salt brings more features and many
fixes. This release is a great refinement over 0.9.6, adding many conveniences
under the hood, as well as some features that make working with Salt much
better.
A few highlights include the new Job system, refinements to the requisite
system in states, the ``mod_init`` interface for states, external node
classification, search path to managed files in the file state, and refinements
and additions to dynamic module loading.
0.9.7 also introduces the long developed (and oft changed) unit test framework
and the initial unit tests.
Major Features
==============
Salt Jobs Interface
-------------------
The new jobs interface makes the management of running executions much cleaner
and more transparent. Building on the existing execution framework the jobs
system allows clear introspection into the active running state of the
running Salt interface.
The Jobs interface is centered in the new minion side proc system. The
minions now store msgpack serialized files under ``/var/cache/salt/proc``.
These files keep track of the active state of processes on the minion.
Functions in the saltutil Module
````````````````````````````````
A number of functions have been added to the saltutil module to manage and
view the jobs:
``running`` - Returns the data of all running jobs that are found in the proc
directory.
``find_job`` - Returns specific data about a certain job based on job id.
``signal_job`` - Allows for a given jid to be sent a signal.
``term_job`` - Sends a termination signal (``SIGTERM, 15``) to the process
controlling the specified job.
``kill_job`` Sends a kill signal (``SIGKILL, 9``) to the process controlling the
specified job.
The jobs Runner
---------------
A convenience runner front end and reporting system has been added as well.
The jobs runner contains functions to make viewing data easier and cleaner.
The jobs runner contains a number of functions...
active
``````
The active function runs ``saltutil.running`` on all minions and formats the
return data about all running jobs in a much more usable and compact format.
The active function will also compare jobs that have returned and jobs that
are still running, making it easier to see what systems have completed a job
and what systems are still being waited on.
lookup_jid
``````````
When jobs are executed the return data is sent back to the master and cached.
By default is is cached for 24 hours, but this can be configured via the
``keep_jobs`` option in the master configuration.
Using the ``lookup_jid`` runner will display the same return data that the
initial job invocation with the salt command would display.
list_jobs
`````````
Before finding a historic job, it may be required to find the job id.
``list_jobs`` will parse the cached execution data and display all of the job
data for jobs that have already, or partially returned.
External Node Classification
----------------------------
Salt can now use external node classifiers like Cobbler's
``cobbler-ext-nodes``.
Salt uses specific data from the external node classifier. In particular the
classes value denotes which sls modules to run, and the environment value sets
to another environment.
An external node classification can be set in the master configuration file via
the ``external_nodes`` option:
http://salt.readthedocs.org/en/latest/ref/configuration/master.html#external-nodes
External nodes are loaded in addition to the top files. If it is intended to
only use external nodes, do not deploy any top files.
State Mod Init System
---------------------
An issue arose with the pkg state. Every time a package was run Salt would
need to refresh the package database. This made systems with slower package
metadata refresh speeds much slower to work with. To alleviate this issue the
``mod_init`` interface has been added to salt states.
The ``mod_init`` interface is a function that can be added to a state file.
This function is called with the first state called. In the case of the pkg
state, the ``mod_init`` function sets up a tag which makes the package database
only refresh on the first attempt to install a package.
In a nutshell, the ``mod_init`` interface allows a state to run any command that
only needs to be run once, or can be used to set up an environment for working
with the state.
Source File Search Path
-----------------------
The file state continues to be refined, adding speed and capabilities. This
release adds the ability to pass a list to the source option. This list is then
iterated over until the source file is found, and the first found file is used.
The new syntax looks like this:
.. code-block:: yaml
/etc/httpd/conf/httpd.conf:
file:
- managed
- source:
- salt://httpd/httpd.conf
- http://myserver/httpd.conf: md5=8c1fe119e6f1fd96bc06614473509bf1
The source option can take sources in the list from the salt file server
as well as an arbitrary web source. If using an arbitrary web source the
checksum needs to be passed as well for file verification.
Refinements to the Requisite System
-----------------------------------
A few discrepancies were still lingering in the requisite system, in
particular, it was not possible to have a ``require`` and a ``watch`` requisite
declared in the same state declaration.
This issue has been alleviated, as well as making the requisite system run
more quickly.
Initial Unit Testing Framework
------------------------------
Because of the module system, and the need to test real scenarios, the
development of a viable unit testing system has been difficult, but unit
testing has finally arrived. Only a small amount of unit testing coverage
has been developed, much more coverage will be in place soon.
A huge thanks goes out to those who have helped with unit testing, and the
contributions that have been made to get us where we are. Without these
contributions unit tests would still be in the dark.
Compound Targets Expanded
-------------------------
Originally only support for ``and`` and ``or`` were available in the compound
target. 0.9.7 adds the capability to negate compound targets with ``not``.
Nodegroups in the Top File
--------------------------
Previously the nodegroups defined in the master configuration file could not
be used to match nodes for states. The nodegroups support has been expanded
and the nodegroups defined in the master configuration can now be used to
match minions in the top file.

397
doc/topics/releases/0.9.8.rst Normal file
View File

@ -0,0 +1,397 @@
========================
Salt 0.9.8 Release Notes
========================
Salt 0.9.8 is a big step forward, with many additions and enhancements, as
well as a number of precursors to advanced future developments.
This version of Salt adds much more power to the command line, making the
old hard timeout issues a thing of the past and adds keyword argument
support. These additions are also available in the salt client api, making
the available api tools much more powerful.
The new pillar system allows for data to be stored on the master and
assigned to minions in a granular way similar to the state system. It also
allows flexibility for users who want to keep data out of their state tree
similar to 'external lookup' functionality in other tools.
A new way to extend requisites was added, the "requisite in" statement.
This makes adding requires or watch statements to external state decs
much easier.
Additions to requisites making them much more powerful have been added as well
as improved error checking for sls files in the state system. A new provider
system has been added to allow for redirecting what modules run in the
background for individual states.
Support for OpenSUSE has been added and support for Solaris has begun
serious development. Windows support has been significantly enhanced as well.
The matcher and target systems have received a great deal of attention. The
default behavior of grain matching has changed slightly to reflect the rest
of salt and the compound matcher system has been refined.
A number of impressive features with keyword arguments have been added to both
the cli and to the state system. This makes states much more powerful and
flexible while maintaining the simple configuration everyone loves.
The new batch size capability allows for executions to be rolled through a
group of targeted minions a percentage or specific number at a time. This
was added to prevent the "thundering herd" problem when targeting large
numbers of minions for things like service restarts or file downloads.
Upgrade Considerations
======================
Upgrade Issues
--------------
There was a previously missed oversight which could cause a newer minion to
crash an older master. That oversight has been resolved so the version
incompatibility issue will no longer occur. When upgrading to 0.9.8 make
sure to upgrade the master first, followed by the minions.
Debian/Ubuntu Packages
----------------------
The original Debian/Ubuntu packages were called salt and included all salt
applications. New packages in the ppa are split by function. If an old salt
package is installed then it should be manually removed and the new split
packages need to be freshly installed.
On the master:
.. code-block:: sh
# apt-get purge salt
# apt-get install salt-{master,minion}
On the minions:
.. code-block:: sh
# apt-get purge salt
# apt-get install salt-minion
And on any Syndics:
.. code-block:: sh
# apt-get install salt-syndic
The official salt stack ppa for Ubuntu is located at:
https://launchpad.net/~saltstack/+archive/salt
Major Features
==============
Pillar
------
:doc:`Pillar </topics/pillar/index>` offers an interface to declare variable data on the master that is then
assigned to the minions. The pillar data is made available to all modules,
states, sls files etc. It is compiled on the master and is declared using the
existing renderer system. This means that learning pillar should be fairly
trivial to those already familiar with salt states.
CLI Additions
-------------
The ``salt`` command has received a serious overhaul and is more powerful
than ever. Data is returned to the terminal as it is received, and the salt
command will now wait for all running minions to return data before stopping.
This makes adding very large *--timeout* arguments completely unnecessary and
gets rid of long running operations returning empty ``{}`` when the timeout is
exceeded.
When calling salt via sudo, the user originally running salt is saved to the
log for auditing purposes. This makes it easy to see who ran what by just
looking through the minion logs.
The *salt-key* command gained the *-D* and *--delete-all* arguments for
removing all keys. Be careful with this one!
Running States Without a Master
-------------------------------
The addition of running states without a salt-master has been added
to 0.9.8. This feature allows for the unmodified salt state tree to be
read locally from a minion. The result is that the UNMODIFIED state tree
has just become portable, allowing minions to have a local copy of states
or to manage states without a master entirely.
This is accomplished via the new file client interface in Salt that allows
for the ``salt://`` uri to be redirected to custom interfaces. This means that
there are now two interfaces for the salt file server, calling the master
or looking in a local, minion defined ``file_roots``.
This new feature can be used by modifying the minion config to point to a
local ``file_roots`` and setting the ``file_client`` option to ``local``.
Keyword Arguments and States
----------------------------
State modules now accept the ``**kwargs`` argument. This results in all data
in a sls file assigned to a state being made available to the state function.
This passes data in a transparent way back to the modules executing the logic.
In particular, this allows adding arguments to the ``pkg.install`` module that
enable more advanced and granular controls with respect to what the state is
capable of.
An example of this along with the new debconf module for installing ldap
client packages on Debian:
.. code-block:: yaml
ldap-client-packages:
pkg:
- debconf: salt://debconf/ldap-client.ans
- installed
- names:
- nslcd
- libpam-ldapd
- libnss-ldapd
Keyword Arguments and the CLI
-----------------------------
In the past it was required that all arguments be passed in the proper order to
the *salt* and *salt-call* commands. As of 0.9.8, keyword arguments can be
passed in the form of ``kwarg=argument``.
.. code-block:: sh
# salt -G 'type:dev' git.clone \
repository=https://github.com/saltstack/salt.git cwd=/tmp/salt user=jeff
Matcher Refinements and Changes
-------------------------------
A number of fixes and changes have been applied to the Matcher system. The
most noteworthy is the change in the grain matcher. The grain matcher used to
use a regular expression to match the passed data to a grain, but now defaults
to a shell glob like the majority of match interfaces in Salt. A new option
is available that still uses the old style regex matching to grain data called
``grain-pcre``. To use regex matching in compound matches use the letter *P*.
For example, this would match any ArchLinux or Fedora minions:
.. code-block:: sh
# salt --grain-pcre 'os:(Arch:Fed).*' test.ping
And the associated compound matcher suitable for ``top.sls`` is *P*:
.. code-block:: sh
P@os:(Arch|Fed).*
**NOTE**: Changing the grains matcher from pcre to glob is backwards
incompatible.
Support has been added for matching minions with Yahoo's range library. This
is handled by passing range syntax with *-R* or *--range* arguments to salt.
More information at:
https://github.com/grierj/range/wiki/Introduction-to-Range-with-YAML-files
Requisite "in"
--------------
A new means to updating requisite statements has been added to make adding
watchers and requires to external states easier. Before 0.9.8 the only way
to extend the states that were watched by a state outside of the sls was to
use an extend statement:
.. code-block:: yaml
include:
- http
extend:
apache:
service:
- watch:
- pkg: tomcat
tomcat:
pkg:
- installed
But the new ``Requisite in`` statement allows for easier extends for
requisites:
.. code-block:: yaml
include:
- http
tomcat:
pkg:
- installed
- watch_in:
- service: apache
Requisite in is part of the extend system, so still remember to always include
the sls that is being extended!
Providers
---------
Salt predetermines what modules should be mapped to what uses based on the
properties of a system. These determinations are generally made for modules
that provide things like package and service management. The apt module
maps to pkg on Debian and the yum module maps to pkg on Fedora for instance.
Sometimes in states, it may be necessary for a non-default module to be used
for the desired functionality. For instance, an Arch Linux system may have
been set up with systemd support. Instead of using the default service module
detected for Arch Linux, the systemd module can be used:
.. code-block:: yaml
http:
service:
- running
- enable: True
- provider: systemd
Default providers can also be defined in the minion config file:
.. code-block:: yaml
providers:
pkg: yumpkg5
service: systemd
When default providers are passed in the minion config, then those providers
will be applied to all functionality in Salt, this means that the functions
called by the minion will use these modules, as well as states.
Requisite Glob Matching
-----------------------
Requisites can now be defined with glob expansion. This means that if there are
many requisites, they can be defined on a single line.
To watch all files in a directory:
.. code-block:: yaml
http:
service:
- running
- enable: True
- watch:
- file: /etc/http/conf.d/*
This example will watch all defined files that match the glob
``/etc/http/conf.d/*``
Batch Size
----------
The new batch size option allows commands to be executed while maintaining that
only so many hosts are executing the command at one time. This option can
take a percentage or a finite number:
.. code-block:: bash
salt \* -b 10 test.ping
salt -G 'os:RedHat' --batch-size 25% apache.signal restart
This will only run test.ping on 10 of the targeted minions at a time and then
restart apache on 25% of the minions matching ``os:RedHat`` at a time and work
through them all until the task is complete. This makes jobs like rolling web
server restarts behind a load balancer or doing maintenance on BSD firewalls
using carp much easier with salt.
Module Updates
---------------
This is a list of notable, but non-exhaustive updates with new and existing
modules.
Windows support has seen a flurry of support this release cycle. We've gained
all new :doc:`file </ref/modules/all/salt.modules.win_file>`,
:doc:`network </ref/modules/all/salt.modules.win_network>`, and
:doc:`shadow </ref/modules/all/salt.modules.win_shadow>` modules. Please note
that these are still a work in progress.
For our ruby users, new :doc:`rvm </ref/modules/all/salt.modules.rvm>` and
:doc:`gem </ref/modules/all/salt.modules.gem>` modules have been added along
with the :doc:`associated </ref/states/all/salt.states.rvm>`
:doc:`states </ref/states/all/salt.states.gem>`
The :doc:`virt </ref/modules/all/salt.modules.virt>` module gained basic Xen support.
The :doc:`yum </ref/modules/all/salt.modules.yumpkg5>`
:doc:`pkg </ref/modules/all/salt.modules.yumpkg>` modules gained Scientific
Linux support.
The :doc:`pkg </ref/modules/all/salt.modules.apt>` module on Debian, Ubuntu,
and derivatives force apt to run in a non-interactive mode. This prevents
issues when package installation waits for confirmation.
A :doc:`pkg </ref/modules/all/salt.modules.zypper>` module for OpenSUSE's
zypper was added.
The :doc:`service </ref/modules/all/salt.modules.upstart>` module on ubuntu
natively supports upstart.
A new :doc:`debconf </ref/modules/all/salt.modules.debconfmod>` module was
contributed by our community for more advanced control over deb package
deployments on Debian based distributions.
The :doc:`mysql.user </ref/states/all/salt.states.mysql_user>` state and
:doc:`mysql </ref/modules/all/salt.modules.mysql>` module gained a
*password_hash* argument.
The :doc:`cmd </ref/modules/all/salt.modules.cmdmod>` module and state gained
a *shell* keyword argument for specifying a shell other than ``/bin/sh`` on
Linux / Unix systems.
New :doc:`git </ref/modules/all/salt.modules.git>` and
:doc:`mercurial </ref/modules/all/salt.modules.hg>` modules have been added
for fans of distributed version control.
In Progress Development
=======================
Master Side State Compiling
---------------------------
While we feel strongly that the advantages gained with minion side state
compiling are very critical, it does prevent certain features that may be
desired. 0.9.8 has support for initial master side state compiling, but many
more components still need to be developed, it is hoped that these can be
finished for 0.9.9.
The goal is that states can be compiled on both the master and the minion
allowing for compilation to be split between master and minion. Why will
this be great? It will allow storing sensitive data on the master and sending
it to some minions without all minions having access to it. This will be
good for handling ssl certificates on front-end web servers for instance.
Solaris Support
---------------
Salt 0.9.8 sees the introduction of basic Solaris support. The daemon runs
well, but grains and more of the modules need updating and testing.
Windows Support
---------------
Salt states on windows are now much more viable thanks to contributions from
our community! States for file, service, local user, and local group management are more fully
fleshed out along with network and disk modules. Windows users can also now manage
registry entries using the new "reg" module.

4
doc/topics/roadmap/index.rst
View File

@ -17,7 +17,7 @@ appear in the web interface.
The features listed here are only listed based on major version releases, the
plan is to have a clear long term goal but not to overly dictate the flow
of development. The project needs to be flexible enough to be able to receive
now features at a moment's notice. This model should spur ideas and make
new features at a moment's notice. This model should spur ideas and make
allowing new community developers to join without issue. So just because
something is slated for a later reason does not mean that a developer is
going to have their code rejected or stalled.
@ -40,7 +40,7 @@ Module Cross Calls
Many instances of using functions when we should be using module cross calls
exist in the code. Mostly from modules which were written before cross calls
were around. The big thing to look for are subprocess calls, since they should
all be running with the cms module.
all be running with the cmd module.
State Return Data Cleanup
`````````````````````````

2
doc/topics/specs/salt_auth_proto.rst
View File

@ -4,7 +4,7 @@ Salt Authentication Protocol
The Salt Authentication Protocol (SAP) defines a viable mechanism to create an
authenticated, encrypted communication channel. The SAP is used to create a
general purpose secure comunication channel.
general purpose secure communication channel.
Editor: Thomas S Hatch <thatch45@gmail.com>

30
doc/topics/specs/salt_auth_proto_abs.rst
View File

@ -2,10 +2,10 @@
Abstract on Salt Authentication and Encryption
==============================================
The Salt authentication and entcryption system uses Public Key authentication
and AES encryption to faciliate both authentication and high speed encryption.
The Salt authentication and encryption system uses Public Key authentication
and AES encryption to facilitate both authentication and high speed encryption.
The core components of this system can be seperated into a few sections,
The core components of this system can be separated into a few sections,
Message Formatting, PubKey Handshake, AES key management, and encryption.
Message Formatting
@ -21,10 +21,10 @@ The message itself is abstracted as a python dict in this fashion:
.. code-block:: python
{'enc': 'aes',
'load': <encrypted python pickle>}
'load': <encrypted msgpack binary data>}
When this message is received the load can be decrypted using the shared AES
key. The 'enc' dict ket can also be "pub" for pubkey encryption, or "clear"
key. The 'enc' dict key can also be "pub" for pubkey encryption, or "clear"
for passing messages in the clear.
PubKey Handshake
@ -32,13 +32,13 @@ PubKey Handshake
RSA Public keys are generated on the Salt master and on the Salt minion. When
A salt minion establishes an initial connection to the salt master the minion
sends its public key in the clear to the salt master, allong with the id of
sends its public key in the clear to the salt master, along with the id of
the minion, and the command to execute on the master, in this case "_auth":
.. code-block:: python
{'enc': 'clear',
'load':
'load':
{'cmd': '_auth',
'id': <minion id>,
'pub': <minion public key>}}
@ -53,17 +53,17 @@ information on how to connect to the salt master publish interface.
The returned AES key is encrypted with the minion's public key, and can
therefore only be decrypted by the minion that sent out the public key.
Once the minion has authenticated and is in possesion of the revolving master
AES key (The AES key is regererated when the master restarts) then it atatches
Once the minion has authenticated and is in possession of the revolving master
AES key (The AES key is regenerated when the master restarts) then it attaches
the minion subscriber to the master publisher.
All messages sent from the publisher are encypted using the revolving AES key,
All messages sent from the publisher are encrypted using the revolving AES key,
in the event that the master restarts the minions will all have an invalid
AES key because it has been regenerated on the master. The master will then
send out a publication that the minions cannot decrypt. If the minion receives
a publication that cannot be decrypted then the minion will re-authenticate,
obtain the correct AES key, and decrypt the message. This means that the
AES key on the salt master can safely revolve without inturupting the minion
AES key on the salt master can safely revolve without interrupting the minion
connection.
Regular Communication
@ -90,8 +90,6 @@ Conclusion
==========
In the end Salt uses formatted messages with clear header data to specify how
the message data is encrypted. Only uses pubkey encryption for authentication
and to securely retrive the master AES key. Then all regular communication
is sent in AES encrypted messages.
the message data is encrypted. Asymetric encryption via RSA keys is only used
for authentication and to securely retrieve the master AES key. All further
communications are are encrypted with 256 bit AES.

29
doc/topics/targeting/compound.rst Normal file
View File

@ -0,0 +1,29 @@
=================
Compound matchers
=================
.. glossary::
Compound matcher
A combination of many target definitions that can be combined with
boolean operators.
Compound matchers allow very granular minion targeting using any of the
previously discussed matchers. The default matcher is a glob, as usual. If
something other than a glob is used preface it with the letter denoting the
type. Matchers can be joined using boolean ``and``, ``or``, and ``not``
operators.
For example, the following command matches all minions that have a hostname
that begins with "webserv" and that are running Debian or it matches any
minions that have a hostname that matches the regular expression
``web-dc1-srv.*``::
salt -C 'webserv* and G@os:Debian or E@web-dc1-srv.*' test.ping
That same example expressed in a :term:`top file` looks like the following::
base:
'webserv* and G@os:Debian or E@web-dc1-srv.*':
- match: compound
- webserver

81
doc/topics/targeting/globbing.rst Normal file
View File

@ -0,0 +1,81 @@
==========================
Matching the ``minion id``
==========================
.. glossary::
minion id
A unique identifier for a given minion. By default the minion id is the
FQDN of that host but this can be overridden.
Each minion needs a unique identifier. By default when a minion starts for the
first time it chooses its :abbr:`FQDN (fully qualified domain name)` as that
identifier. The minion id can be overridden via the minion's :conf_minion:`id`
configuration setting.
.. tip:: minion id and minion keys
The :term:`minion id` is used to generate the minion's public/private keys
and if it ever changes the master must then accept the new key as though
the minion was a new host.
Globbing
========
The default matching that Salt utilizes is shell-style globbing around the
:term:`minion id`. This also works for states in the :term:`top file`.
.. note::
You must wrap :command:`salt` calls that use globbing in single-quotes to
prevent the shell from expanding the globs before Salt is invoked.
Match all minions::
salt '*' test.ping
Match all minions in the example.net domain or any of the example domains::
salt '*.example.net' test.ping
salt '*.example.*' test.ping
Match all the ``webN`` minions in the example.net domain
(``web1.example.net``, ``web2.example.net`` … ``webN.example.net``)::
salt 'web?.example.net test.ping
Match the ``web1`` through ``web5`` minions::
salt 'web[1-5]' test.ping
Match the ``web-x``, ``web-y``, and ``web-z`` minions::
salt 'web-[x-z]' test.ping
Regex
=====
Minions can be matched using Perl-compatible regular expressions (which is
globbing on steroids and a ton of caffeine).
Match both ``web1-prod`` and ``web1-devel`` minions::
salt -E 'web1-(prod|devel)' test.ping
When using regex in a states :term:`top file` you must specify the matcher as
the first option. The following example executes the contents of
``webserver.sls`` on the above-mentioned minions.
.. code-block:: yaml
base:
'web1-(prod|devel)':
- match: pcre
- webserver
Lists
=====
At the most basic you can specify a flat list of minion ids::
salt -L 'web1,web2,web3' test.ping

20
doc/ref/grains.rst → doc/topics/targeting/grains.rst
View File

@ -25,29 +25,29 @@ Just add the option ``grains`` and pass options to it:
.. code-block:: yaml
grains:
roles:
roles:
- webserver
- memcache
deployment: datacenter4
cabinet: 13
cab_u: 14-15
Then statis data specific to your servers can be retrived via Salt, or used
Then status data specific to your servers can be retrieved via Salt, or used
inside of the state system for matching. It also makes targeting, in the case
of the example above, simply based on specific data about your deployment.
Writing Grains
==============
Grains are easy to write. The grains interface is derived by executing all of
the "public" functions found in the modules located in the grains package or
the custom grains directory. The functions in the modules of the grains must
return a python dict, where the keys in the dict are the names of the grains and
the values are the values.
Grains are easy to write. The grains interface is derived by executing
all of the "public" functions found in the modules located in the grains
package or the custom grains directory. The functions in the modules of
the grains must return a python dict, where the keys in the dict are the
names of the grains and the values are the values.
Custom grains should be placed in a ``_grains`` directory located under your
:conf_master:`file_roots`. Before adding a grain to salt, consider what the grain
is and remember that grains need to be static data.
Custom grains should be placed in a ``_grains`` directory located under
your :conf_master:`file_roots`. Before adding a grain to salt, consider
what the grain is and remember that grains need to be static data.
Examples of Grains
------------------

33
doc/topics/targeting/index.rst Normal file
View File

@ -0,0 +1,33 @@
=========
Targeting
=========
.. glossary::
Targeting
Specifying which minions should run a command or execute a state by
matching against hostnames, or system information, or defined groups,
or even combinations thereof.
For example the command ``salt web1 apache.signal restart`` to restart the
Apache httpd server specifies the machine ``web1`` as the target and the
command will only be run on that one minion.
Similarly when using states, the following :term:`top file` specifies that only
the ``web1`` minion should execute the contents of ``webserver.sls``:
.. code-block:: yaml
base:
'web1':
- webserver
There are many ways to target individual minions or groups of minions in Salt:
.. toctree::
:maxdepth: 2
globbing
grains
nodegroups
compound

26
doc/topics/targeting/nodegroups.rst Normal file
View File

@ -0,0 +1,26 @@
===========
Node groups
===========
.. glossary::
Node group
A predefined group of minions declared in the master configuration file
:conf_master:`nodegroups` setting as a :term:`compound target`.
For example, in the master config file :conf_master:`nodegroups` setting::
nodegroups:
group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com'
group2: 'G@os:Debian and foo.domain.com'
Specify a nodegroup via the ``-N`` option at the command-line::
salt -N group1 test.ping
Specify a nodegroup with ``- match: nodegroup`` in a :term:`top file`::
base:
group1:
- match: nodegroup
- webserver

132
doc/topics/troubleshooting/index.rst Normal file
View File

@ -0,0 +1,132 @@
===============
Troubleshooting
===============
The intent of the troubleshooting section is to introduce solutions to a
number of common issues encountered by users and the tools that are available
to aid in developing states and salt code.
Running in the Foreground
=========================
A great deal of information is available via the debug logging system, if you
are having issues with minions connecting or not starting run the minion and/or
master in the foreground:
.. code-block:: sh
# salt-master -l debug
# salt-minion -l debug
What Ports do the Master and Minion Need Open?
==============================================
No ports need to be opened up on each minion. For the master, tcp ports 4505
and 4506 need to be open. If you've put your salt master and minion both in
debug mode and don't see an acknowledgement that your minion has connected,
it could very well be a firewall.
You can check port connectivity from the minion with the nc command:
.. code-block:: sh
# nc -v -z salt.master.ip 4505
# nc -v -z salt.master.ip 4506
There is also a :doc:`firewall configuration</topics/tutorials/firewall>`
document that might help as well.
Using salt-call
===============
The ``salt-call`` command was originally developed for aiding in the development
of new salt modules. Since then many applications have arisen for the salt-call
command that is bundled with the salt minion. These range from the original
intent of the salt-call, development assistance, to gathering large amounts of
data from complex calls like
:doc:`state.highstate</ref/modules/all/salt.modules.state>`.
When developing the state tree it is generally recommended to invoke
state.highstate with salt-call, this displays a great deal more information
about the highstate execution than if it is called remotely.
Too many open files
===================
The salt-master needs at least 2 sockets per host that connects to it, one for
the Publisher and one for response port. Thus, large installations may upon
scaling up the number of minions accessing a given master, encounter:
.. code-block:: sh
12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38
Too many open files
sock != -1 (tcp_listener.cpp:335)
The solution to this would be to check the number of files allowed to be
opened by the user running salt-master (root by default):
.. code-block:: sh
[root@salt-master ~]# ulimit -n
1024
And modify that value to be at least equal to the number of minions x 2.
This setting can be changed in limits.conf as the nofile value(s),
and activated upon new a login of the specified user.
So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum.
Salt Master Stops Responding
============================
There are known bugs with ZeroMQ less than 2.1.11 which can cause the salt
master to not respond properly. If you're running ZeroMQ greater than or equal
to 2.1.9, you can work around the bug by setting the sysctls
``net.core.rmem_max`` and ``net.core.wmem_max`` to 16777216. Next set the third
field in ``net.ipv4.tcp_rmem`` and ``net.ipv4.tcp_wmem`` to at least 16777216.
You can do it manually with something like:
.. code-block:: sh
# echo 16777216 > /proc/sys/net/core/rmem_max
# echo 16777216 > /proc/sys/net/core/wmem_max
# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem
# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem
Or with the following salt state:
.. code-block:: yaml
:linenos:
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
Common YAML Gotchas
===================
An extensive list of
:doc:`yaml idiosyncrasies</topics/troubleshooting/yaml_idiosyncrasies>`
has been compiled.

104
doc/topics/troubleshooting/yaml_idiosyncrasies.rst Normal file
View File

@ -0,0 +1,104 @@
===================
YAML Idiosyncrasies
===================
One of Salt's strengths, the use of existing serialization systems for
representing sls data, can also backfire. YAML is a general purpose system
and there are a number of things that would seem to make sense in an sls
file that cause YAML issues. It is wise to be aware of these issues. While
reports or running into them are generally rare they can still crop up at
unexpected times.
Spaces vs Tabs
==============
Yaml uses spaces, period. Do not use tabs in your sls files! If strange
errors are coming up in rendering sls files, make sure to check that
no tabs have crept in! In vi / vim, you can check with ``:se spell``.
Indentation
===========
The suggested syntax for YAML files is to use 2 spaces for indentation,
but YAML will follow whatever indentation system that the individual file
uses. Indentation of two spaces works very well for sls files given the
fact that the data is uniform and not deeply nested.
Nested Dicts (key=value)
------------------------
When dicts are more deeply nested they no longer follow the same indentation
logic. This is rarely something that comes up in Salt, since deeply nested
options like these are discouraged when making state modules, but some do
exist. A good example is the context and default options in the
:doc:`file.managed</ref/states/all/salt.states.file>` state:
.. code-block:: yaml
/etc/http/conf/http.conf:
file:
- managed
- source: salt://apache/http.conf
- user: root
- group: root
- mode: 644
- template: jinja
- context:
custom_var: "override"
- defaults:
custom_var: "default value"
other_var: 123
Notice that the spacing used is 2 spaces, and that when defining the context
and defaults options there is a 4 space indent. If only a 2 space indent is
used then the information will not be loaded correctly. If using double spacing
is not desirable, then a deeply nested dict can be declared with curly braces:
.. code-block:: yaml
/etc/http/conf/http.conf:
file:
- managed
- source: salt://apache/http.conf
- user: root
- group: root
- mode: 644
- template: jinja
- context: {
custom_var: "override" }
- defaults: {
custom_var: "default value"
other_var: 123 }
Integers are Parsed as Integers
===============================
When passing integers into an sls file, they are passed as integers. This means
that if a state accepts a string value and an integer is passed, that an
integer will be sent. The solution here is to send the integer as a string.
This is best explained when setting the mode for a file:
.. code-block:: yaml
/etc/vimrc:
file:
- managed
- source: salt://edit/vimrc
- user: root
- group: root
- mode: 644
Salt manages this well, since the mode is passed as 644, but if the mode is
zero padded as 0644, then it is read by YAML as an integer and evaluated as
a hexadecimal value, 0644 becomes 420. Therefore, if the file mode is
preceded by a 0 then it needs to be passed as a string:
.. code-block:: yaml
/etc/vimrc:
file:
- managed
- source: salt://edit/vimrc
- user: root
- group: root
- mode: '0644'

24
doc/topics/tutorials/bootstrap_ec2.rst
View File

@ -2,9 +2,16 @@
Boostrapping Salt on Linux EC2 with Cloud-Init
==============================================
`Salt <http://saltstack.org>`_ is a great tool for remote execution and configuration management, however you will still need to bootstrap the daemon when spinning up a new node. One option is to create and save a custom AMI, but this creates another resource to maintain and document.
`Salt <http://saltstack.org>`_ is a great tool for remote execution and
configuration management, however you will still need to bootstrap the
daemon when spinning up a new node. One option is to create and save a
custom AMI, but this creates another resource to maintain and document.
A better method for Linux machines uses Canonical's `CloudInit <https://help.ubuntu.com/community/CloudInit>`_ to run a bootstrap script during an EC2 Instance initialization. Cloud-init takes the ``user_data`` string passed into a new AWS instance and runs it in a manner similar to rc.local. The bootstrap script needs to:
A better method for Linux machines uses Canonical's `CloudInit
<https://help.ubuntu.com/community/CloudInit>`_ to run a bootstrap script
during an EC2 Instance initialization. Cloud-init takes the ``user_data``
string passed into a new AWS instance and runs it in a manner similar to
rc.local. The bootstrap script needs to:
#. Install `Salt`_ with dependencies
#. Point the minion to the master
@ -24,12 +31,17 @@ Here is a sample script::
sed -i '' -e 's/#master: salt/master: [salt_master_fqdn]' /etc/salt/minion
salt-minion -d
First the script adds the saltstack ppa and installs the package. Then we copy over the minion config template and tell it where to find the master. You will have to replace ``[salt_master_fqdn]`` with something that resolves to your salt master.
First the script adds the saltstack ppa and installs the package. Then
we copy over the minion config template and tell it where to find the
master. You will have to replace ``[salt_master_fqdn]`` with something
that resolves to your salt master.
Used With Boto
--------------
`Boto <https://github.com/boto/boto>`_ will accept a string for user data which can be used to pass our bootstrap script. If the script is saved to a file, you can read it into a string::
`Boto <https://github.com/boto/boto>`_ will accept a string for user data
which can be used to pass our bootstrap script. If the script is saved to
a file, you can read it into a string::
import boto
@ -47,4 +59,6 @@ Additional Notes
Sometime in the future the ppa will include and install an upstart file. In the meantime, you can use the bootstrap to `build one <https://gist.github.com/1617054>`_.
It may also be useful to set the node's role during this phase. One option would be saving the node's role to a file and then using a custom grain to select it.
It may also be useful to set the node's role during this phase. One option
would be saving the node's role to a file and then using a custom grain
to select it.

68
doc/topics/tutorials/firewall.rst Normal file
View File

@ -0,0 +1,68 @@
================================
Opening the Firewall up for Salt
================================
The Salt master communicates with the minions using an AES-encrypted ZeroMQ
connection. These communications are done over ports 4505 and 4506, which need
to be accessible on the master only. This document outlines suggested firewall
rules for allowing these incoming connections to the master.
.. note::
**No firewall configuration needs to be done on Salt minions. These changes
refer to the master only.**
iptables
========
Different Linux distributions store their iptables rules in different places,
which makes it difficult to standardize firewall documentation. I've included
some of the more common locations, but your mileage may vary.
**Fedora / Red Hat / CentOS** ::
/etc/sysconfig/iptables
**Arch Linux** ::
/etc/iptables/iptables.rules
**Debian**
Follow these instructions: http://wiki.debian.org/iptables
Once you've found your firewall rules, you'll need to add the two lines below
to allow traffic on ``tcp/4505`` and ``tcp/4506``:
.. code-block:: diff
+ -A INPUT -m state --state new -m tcp -p tcp --dport 4505 -j ACCEPT
+ -A INPUT -m state --state new -m tcp -p tcp --dport 4506 -j ACCEPT
**Ubuntu**
Create a file named ``/etc/ufw/applications.d/salt-master`` ::
[Salt Master]
title=Salt master
description=Salt is a remote execution and configuration management tool.
ports=4205,4206/tcp
pf.conf
=======
The BSD-family of operating systems uses packet filter (pf). The following
example describes the additions to ``pf.conf`` needed to access the Salt
master.
.. code-block:: diff
+ pass in on $int_if proto tcp from any to $int_if port 4505
+ pass in on $int_if proto tcp from any to $int_if port 4506
Once you've made these additions to your ``pf.conf`` you'll need to reload the
new rules with the new additions. This can be done using the ``pfctl`` command.
.. code-block:: bash
pfctl -vf /etc/pf.conf

2
doc/topics/tutorials/modules.rst
View File

@ -28,7 +28,7 @@ Targets can be based on minion system information using the grains system::
salt -G 'os:Ubuntu' test.ping
.. seealso:: :doc:`Grains system </ref/grains>`
.. seealso:: :doc:`Grains system </topics/targeting/grains>`
Targets can be filtered by regular expression::

108
doc/topics/tutorials/starting_states.rst
View File

@ -5,26 +5,25 @@ How Do I Use Salt States?
Simplicity, Simplicity, Simplicity
Many of the most powerful and useful engineering solutions are founded on
simple principals, the Salt SLS system strives to do just that.
simple principals, the Salt SLS system strives to do just that. K.I.S.S.
The core of the Salt State system is the SLS, or the SaLt State file. The SLS
is a representation of the state in which a system should be in, and is set up
to contain this data in the most simple way possible.
to contain this data simply. This is often called configuration management.
It is All Just Data
===================
Before delving into the particulars, it will help to understand that the SLS
is just a data structure under the hood. While understanding that the SLS is
just a data structure is not at all critical to understand to make use Salt States,
it should help bolster the understanding of where the real power is.
just a data structure is not at all critical to understand to make use Salt
States, it should help bolster the understanding of where the real power is.
SLS files are therefore, in reality, just dictionaries, lists strings and
numbers. By using this approach Salt can be much more flexible, and as someone
writes more SLS files it becomes clear exactly what is being written. The result
is a system that is easy to understand, yet grows with the needs of the admin
or developer, offering simple constructs that grow to encompass the most
complicated needs.
SLS files are therefore, in reality, just dictionaries, lists, strings and
numbers. By using this approach Salt can be much more flexible. As someone
writes more state files, it becomes clear exactly what is being written. The
result is a system that is easy to understand, yet grows with the needs of
the admin or developer.
In the section titled "State Data Structures" a reference exists, explaining
in depth how the data is laid out.
@ -35,9 +34,10 @@ Default Data - YAML
By default Salt represents the SLS data in what is one of the simplest
serialization formats available - YAML.
A typical, small SLS file will often look like this in YAML:
A typical SLS file will often look like this in YAML:
.. code-block:: yaml
:linenos:
apache:
pkg:
@ -51,7 +51,7 @@ This SLS data will ensure that the package named apache is installed, and
that the apache service is running. The components can be explained in a
simple way.
The first like it the ID for a set of data, and it is called the ID
The first line is the ID for a set of data, and it is called the ID
Declaration. This ID sets the name of the thing that needs to be manipulated.
The second and fourth lines are the start of the State Declarations, so they
@ -62,18 +62,19 @@ lines are the function to run. This function defines what state the named
package and service should be in. Here the package is to be installed, and
the service should be running.
Finally, on line 6, is the word ``require``, this is called a Requisite
Statement, and it makes sure that the apache service is only started after
Finally, on line 6, is the word ``require``. This is called a Requisite
Statement, and it makes sure that the Apache service is only started after
the successful installation of the apache package.
Adding Configs and Users
========================
When setting up a service like an apache server many more components may
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.
.. code-block:: yaml
:linenos:
apache:
pkg:
@ -128,20 +129,20 @@ config file will also trigger a restart of the respective service.
Moving Beyond a Single SLS
==========================
When setting up Salt States more than one SLS will need to be used, the above
When setting up Salt States, more than one SLS will need to be used. The above
examples were just in a single SLS file, but more than one SLS file can be
combined to build out a State Tree. The above example also references a file
with a strange source - salt://apache/httpd.conf, that file will need to be
available as well.
with a strange source - ``salt://apache/httpd.conf``. That file will need to
be available as well.
The SLS files are laid out in a directory on the salt master. Files are laid
out as just files, an sls is just a file and files to download are just files.
out as just files. A sls is just a file and files to download are just files.
The apache example would be laid out in the root of the salt file server like
this:
this: ::
/apache/init.sls
/apache/httpd.conf
/apache/init.sls
/apache/httpd.conf
So the httpd.conf is just a file in the apache directory, and is referenced
directly.
@ -149,14 +150,15 @@ directly.
But with more than a single SLS file, more components can be added to the
toolkit, consider this ssh example:
``/ssh/init.sls``
``/ssh/init.sls:``
.. code-block:: yaml
:linenos:
openssh-client:
pkg:
- installed
/etc/ssh/ssh_config
file:
- managed
@ -167,9 +169,10 @@ toolkit, consider this ssh example:
- require:
- pkg: openssh-client
``/ssh/server.sls``
``ssh/server.sls:``
.. code-block:: yaml
:linenos:
include:
- ssh
@ -206,15 +209,15 @@ toolkit, consider this ssh example:
- require:
- pkg: openssh-server
Now our State Tree looks like this:
Now our State Tree looks like this: ::
/apache/init.sls
/apache/httpd.conf
/ssh/init.sls
/ssh/server.sls
/ssh/banner
/ssh/ssh_config
/ssh/sshd_config
/apache/init.sls
/apache/httpd.conf
/ssh/init.sls
/ssh/server.sls
/ssh/banner
/ssh/ssh_config
/ssh/sshd_config
This example now introduces the ``include`` statement. The include statement
includes another SLS file so that components found in it can be required,
@ -233,9 +236,10 @@ needs to be placed.
These examples will add more watchers to apache and change the ssh banner.
``/ssh/custom-server.sls``
``/ssh/custom-server.sls:``
.. code-block:: yaml
:linenos:
include:
- ssh.server
@ -245,9 +249,10 @@ These examples will add more watchers to apache and change the ssh banner.
file:
- source: salt://ssh/custom-banner
``/python/mod_python.sls``
``/python/mod_python.sls:``
.. code-block:: yaml
:linenos:
include:
- apache
@ -262,7 +267,7 @@ These examples will add more watchers to apache and change the ssh banner.
pkg:
- installed
The custom-server.sls file uses the extend statement to overwrite where the
The ``custom-server.sls`` file uses the extend statement to overwrite where the
banner is being downloaded from, and therefore changing what file is being used
to configure the banner.
@ -281,7 +286,7 @@ with YAML. Salt defaults to YAML because it is very straightforward and easy
to learn and use. But the SLS files can be rendered from almost any imaginable
medium, so long as a renderer module is provided.
The default rendering system is the ``yaml_jinja`` renderer. The
The default rendering system is the ``yaml_jinja`` renderer. The
``yaml_jinja`` renderer will first pass the template through the jinja
templating system, and then through the YAML parser. The benefit here is that
full programming constructs are available when creating SLS files.
@ -292,22 +297,23 @@ python or ``py`` renderer. The ``py`` renderer allows for SLS files to be
written in pure python, allowing for the utmost level of flexibility and
power when preparing SLS data.
Geting to Know the Default - yaml_jinja
---------------------------------------
Getting to Know the Default - yaml_jinja
----------------------------------------
The default renderer - ``yaml_jinja``, allows for the use of the jinja
templating system. A guide to the jinja templating system can be found here:
<link to the jinga templating docs page>.
http://jinja.pocoo.org/docs
When working with renderers a few very useful bits of data are passed in. In
the case of templating engine based renderers two critical components are
available, ``salt`` and ``grains``. The salt object allows for any salt
function to be called from within the template, and grains allows for the
grains to be accessed from within the template. A few examples are in order:
available, ``salt``, ``grains``, and ``pillar``. The salt object allows for
any salt function to be called from within the template, and grains allows for
the grains to be accessed from within the template. A few examples:
``/apache/init.sls``
``/apache/init.sls:``
.. code-block:: yaml
:linenos:
apache:
pkg:
@ -346,15 +352,16 @@ grains to be accessed from within the template. A few examples are in order:
- group: root
- mode: 644
This example is simple, if the os grain states that the operating system is
This example is simple. If the ``os`` grain states that the operating system is
Red Hat, then the name of the apache package and service needs to be httpd.
A more aggressive way to use Jinja can be found here, in a module to set up
a MooseFS distributed filesystem chunkserver:
``/moosefs/chunk.sls``
``/moosefs/chunk.sls:``
.. code-block:: yaml
:linenos:
include:
- moosefs
@ -427,9 +434,10 @@ but a SLS file set to use another renderer can be easily added to the tree.
This example shows a very basic python SLS file:
``/python/django.sls``
``/python/django.sls:``
.. code-block:: python
:linenos:
#!py
@ -444,11 +452,12 @@ This is a very simple example, the first line has a SLS shebang line that
tells Salt to not use the default renderer, but to use the ``py`` renderer.
Then the run function is defined, the return value from the run function
must be a Salt friendly data structure, or better known as a Salt
``HighState`` data structure.
:doc:`HighState data structure</ref/states/highstate>`.
This python example would look like this if it were written in YAML:
.. code-block:: yaml
:linenos:
include:
- python
@ -461,3 +470,4 @@ This clearly illustrates, that not only is using the YAML renderer a wise
decision as the default, but that unbridled power can be obtained where
needed by using a pure python SLS.
Now onto the :doc:`States tutorial, part 1</topics/tutorials/states_pt1>`.

15
doc/topics/tutorials/states_pt1.rst
View File

@ -28,6 +28,11 @@ uncomment the following lines:
base:
- /srv/salt
.. note::
If you are deploying on FreeBSD via ports, the ``file_roots`` path defaults
to ``/usr/local/etc/salt/states``.
Restart the Salt master in order to pick up this change:
.. code-block:: bash
@ -55,7 +60,7 @@ minion matches is defined; for now simply specify all hosts (``*``).
The expressions can use any of the targeting mechanisms used by Salt —
minions can be matched by glob, pcre regular expression, or by :doc:`grains
</ref/grains>`. For example::
</topics/targeting/grains>`. For example::
base:
'os:Fedora':
@ -81,15 +86,11 @@ In this case it defines the name of the package to be installed. **NOTE:** the
package name for the Apache httpd web server may differ on your OS or distro —
for example, on Fedora it is ``httpd`` but on Debian/Ubuntu it is ``apache2``.
Additionally, an ID declaration should not contain a dot, as this will produce
unpredictable output in the summary returned from a call to
:func:`state.highstate <salt.modules.state.highstate>`.
The second line, called the :term:`state declaration`, defines which of the
Salt States we are using. In this example, we are using the :mod:`pkg state
<salt.states.pkg>` to ensure that a given package is installed.
The third line, called the :term:`function declaration` defines which function
The third line, called the :term:`function declaration`, defines which function
in the :mod:`pkg state <salt.states.pkg>` module to call.
.. admonition:: Renderers
@ -102,7 +103,7 @@ in the :mod:`pkg state <salt.states.pkg>` module to call.
Building the expected data structure is the job of Salt :doc:`renderers
</ref/renderers/index>` and they are dead-simple to write.
In this tutorial we will be using YAML in Jinja2 templates which is the
In this tutorial we will be using YAML in Jinja2 templates, which is the
default format. You can change the default by changing
:conf_master:`renderer` in the master configuration file.

22
doc/topics/tutorials/states_pt2.rst
View File

@ -40,9 +40,9 @@ directory named ``webserver`` and moving and renaming ``webserver.sls`` to
::
|- top.sls
`- webserver/
`- init.sls
|- top.sls
`- webserver/
`- init.sls
.. admonition:: Organizing SLS modules
@ -65,7 +65,7 @@ installed and running. Include the following at the bottom of your
.. code-block:: yaml
:linenos:
:emphasize-lines: 6,11
:emphasize-lines: 7,11
apache:
pkg:
@ -80,25 +80,25 @@ installed and running. Include the following at the bottom of your
- require: # requisite declaration
- pkg: apache # requisite reference
Again in **line 1** is the :term:`ID declaration`. In this example it is the
**line 7** is the :term:`ID declaration`. In this example it is the
location we want to install our custom HTML file. (**Note:** the default
location that Apache serves may differ from the above on your OS or distro.
``/srv/www`` could also be a likely place to look.)
**Line 2** the :term:`state declaration`. This example uses the Salt :mod:`file
**Line 8** the :term:`state declaration`. This example uses the Salt :mod:`file
state <salt.states.file>`.
**Line 3** is the :term:`function declaration`. The :func:`managed function
**Line 9** is the :term:`function declaration`. The :func:`managed function
<salt.states.file.managed>` will download a file from the master and install it
in the location specified.
**Line 4** is a :term:`function arg declaration` which, in this example, passes
**Line 10** is a :term:`function arg declaration` which, in this example, passes
the ``source`` argument to the :func:`managed function
<salt.states.file.managed>`.
<salt.states.file.managed>`.
**Line 5** is a :term:`requisite declaration`.
**Line 11** is a :term:`requisite declaration`.
**Line 6** is a :term:`requisite reference` which refers to a state and an ID.
**Line 12** is a :term:`requisite reference` which refers to a state and an ID.
In this example, it is referring to the ``ID declaration`` from our example in
:doc:`part 1 <states_pt1>`. This declaration tells Salt not to install the HTML
file until Apache is installed.

22
doc/topics/tutorials/states_pt3.rst
View File

@ -49,7 +49,7 @@ Using Grains in SLS modules
===========================
Often times a state will need to behave differently on different systems.
:doc:`Salt grains </ref/grains>` can be used from within sls modules. An object
:doc:`Salt grains </topics/targeting/grains>` can be used from within sls modules. An object
called ``grains`` is made available in the template context:
.. code-block:: yaml
@ -66,8 +66,8 @@ called ``grains`` is made available in the template context:
Calling Salt modules from templates
===================================
All of the Salt modules loaded by the minion ave available within the
templating system. This allows data to be gathered in real time, on the target
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.
@ -87,10 +87,10 @@ The Salt module functions are also made available in the template context as
- group: {{ usr }}
{% endfor %}
Below is another example that calls an arbitrary command in order to grab the
mac addr for eth0::
Below is an example that uses the ``network.hwaddr`` function to retrieve the
MAC address for eth0:
salt['cmd.run']('ifconfig eth0 | grep HWaddr | cut -d" " -f10')
salt['network.hwaddr']('eth0')
Advanced SLS module syntax
==========================
@ -103,7 +103,7 @@ trees.
You have seen an example of how to spread a Salt tree across several files but
in order to be able to have :term:`requisite references <requisite reference>`
span multiple files you must use a :term:`include declaration`. For example:
span multiple files you must use an :term:`include declaration`. For example:
``python-libs.sls``:
@ -129,7 +129,7 @@ span multiple files you must use a :term:`include declaration`. For example:
:term:`Extend declaration`
--------------------------
You can modify previous declarations by using a :term:`extend declaration`. For
You can modify previous declarations by using an :term:`extend declaration`. For
example the following modifies the Apache tree to also restart Apache when the
vhosts file is changed:
@ -164,8 +164,8 @@ vhosts file is changed:
------------------------
You can override the :term:`ID declaration` by using a :term:`name
declaration`. For example the previous example is a bit more maintainable if
rewritten as the following:
declaration`. For example, the previous example is a bit more maintainable if
rewritten as follows:
``mywebsite.sls``:
@ -208,7 +208,7 @@ can be rewritten without the loop:
Continue learning
=================
The best way to continue learing about Salt States is to read through the
The best way to continue learning about Salt States is to read through the
:doc:`reference documentation </ref/states/index>` and to look through examples
of existing :term:`state trees <state tree>`. You can find examples in the
`salt-states repository`_ and please send a pull-request on GitHub with any

1
pkg/rpm/salt.spec
View File

@ -93,7 +93,6 @@ Requires: salt = %{version}-%{release}
%description -n salt-master
The Salt master is the central server to which all minions connect.
Summary:
%package -n salt-minion
Summary: Client component for salt, a parallel remote execution system

132
salt/__init__.py
View File

@ -6,87 +6,19 @@ from salt.version import __version__
# Import python libs
import os
import sys
import stat
import optparse
import getpass
# Import salt libs, the try block bypasses an issue at build time so that c
# modules don't cause the build to fail
try:
import salt.config
import salt.utils.verify
from salt.utils.process import set_pidfile
from salt.utils.verify import check_user, verify_env
except ImportError as e:
if e.message != 'No module named _msgpack':
raise
def set_pidfile(pidfile):
'''
Save the pidfile
'''
pdir = os.path.dirname(pidfile)
if not os.path.isdir(pdir):
os.makedirs(pdir)
try:
open(pidfile, 'w+').write(str(os.getpid()))
except IOError:
err = ('Failed to commit the pid file to location {0}, please verify'
' that the location is available').format(pidfile)
log.error(err)
def verify_env(dirs):
'''
Verify that the named directories are in place and that the environment
can shake the salt
'''
for dir_ in dirs:
if not os.path.isdir(dir_):
try:
cumask = os.umask(63) # 077
os.makedirs(dir_)
os.umask(cumask)
except OSError, e:
sys.stderr.write('Failed to create directory path "{0}" - {1}\n'.format(dir_, e))
mode = os.stat(dir_)
# TODO: Should this log if it can't set the permissions
# to very secure for these PKI cert directories?
if not stat.S_IMODE(mode.st_mode) == 448:
if os.access(dir_, os.W_OK):
os.chmod(dir_, 448)
# Run the extra verification checks
salt.utils.verify.run()
def check_user(user, log):
'''
Check user and assign process uid/gid.
'''
if 'os' in os.environ:
if os.environ['os'].startswith('Windows'):
return True
if user == getpass.getuser():
return True
import pwd # after confirming not running Windows
try:
p = pwd.getpwnam(user)
try:
os.setgid(p.pw_gid)
os.setuid(p.pw_uid)
except OSError:
if user == 'root':
msg = 'Sorry, the salt must run as root. http://xkcd.com/838'
else:
msg = 'Salt must be run from root or user "{0}"'.format(user)
log.critical(msg)
return False
except KeyError:
msg = 'User not found: "{0}"'.format(user)
log.critical(msg)
return False
return True
class Master(object):
'''
Creates a master server
@ -97,8 +29,10 @@ class Master(object):
# command line overrides config
if self.cli['user']:
self.opts['user'] = self.cli['user']
# Send the pidfile location to the opts
self.opts['pidfile'] = self.cli['pidfile']
# Send the pidfile location to the opts
if self.cli['pidfile']:
self.opts['pidfile'] = self.cli['pidfile']
def __parse_cli(self):
'''
@ -111,7 +45,7 @@ class Master(object):
dest='daemon',
default=False,
action='store_true',
help='Run the master in a daemon')
help='Run the master as a daemon')
parser.add_option('-c',
'--config',
dest='config',
@ -120,12 +54,10 @@ class Master(object):
parser.add_option('-u',
'--user',
dest='user',
help='Specify user to run minion')
help='Specify user to run master')
parser.add_option('--pid-file',
dest='pidfile',
default='/var/run/salt-master.pid',
help=('Specify the location of the pidfile. Default'
' %default'))
help=('Specify the location of the pidfile.'))
parser.add_option('-l',
'--log-level',
dest='log_level',
@ -166,15 +98,18 @@ class Master(object):
import logging
log = logging.getLogger(__name__)
# Late import so logging works correctly
import salt.master
master = salt.master.Master(self.opts)
if self.cli['daemon']:
# Late import so logging works correctly
import salt.utils
salt.utils.daemonize()
set_pidfile(self.opts['pidfile'])
if check_user(self.opts['user'], log):
import salt.master
master = salt.master.Master(self.opts)
if self.cli['daemon']:
# Late import so logging works correctly
import salt.utils
salt.utils.daemonize()
set_pidfile(self.cli['pidfile'])
master.start()
try:
master.start()
except salt.master.MasterExit:
sys.exit()
class Minion(object):
@ -252,13 +187,13 @@ class Minion(object):
# Late import so logging works correctly
import salt.minion
log = logging.getLogger(__name__)
if self.cli['daemon']:
# Late import so logging works correctly
import salt.utils
salt.utils.daemonize()
set_pidfile(self.cli['pidfile'])
if check_user(self.opts['user'], log):
try:
if self.cli['daemon']:
# Late import so logging works correctly
import salt.utils
salt.utils.daemonize()
set_pidfile(self.cli['pidfile'])
minion = salt.minion.Minion(self.opts)
minion.tune_in()
except KeyboardInterrupt:
@ -302,7 +237,7 @@ class Syndic(object):
def __parse_cli(self):
'''
Parse the cli for options passed to a master daemon
Parse the cli for options passed to a syndic daemon
'''
import salt.log
parser = optparse.OptionParser(version="%%prog %s" % __version__)
@ -311,7 +246,7 @@ class Syndic(object):
dest='daemon',
default=False,
action='store_true',
help='Run the master in a daemon')
help='Run the syndic as a daemon')
parser.add_option('--master-config',
dest='master_config',
default='/etc/salt/master',
@ -323,7 +258,7 @@ class Syndic(object):
parser.add_option('-u',
'--user',
dest='user',
help='Specify user to run minion')
help='Specify user to run syndic')
parser.add_option('--pid-file',
dest='pidfile',
default='/var/run/salt-syndic.pid',
@ -345,6 +280,7 @@ class Syndic(object):
cli = {'daemon': options.daemon,
'minion_config': options.minion_config,
'master_config': options.master_config,
'pidfile': options.pidfile,
'user': options.user}
return cli
@ -368,14 +304,14 @@ class Syndic(object):
# Late import so logging works correctly
import salt.minion
log = logging.getLogger(__name__)
if self.cli['daemon']:
# Late import so logging works correctly
import salt.utils
salt.utils.daemonize()
set_pidfile(self.cli['pidfile'])
if check_user(self.opts['user'], log):
try:
syndic = salt.minion.Syndic(self.opts)
if self.cli['daemon']:
# Late import so logging works correctly
import salt.utils
salt.utils.daemonize()
set_pidfile(self.cli['pidfile'])
syndic.tune_in()
except KeyboardInterrupt:
log.warn('Stopping the Salt Syndic Minion')

288
salt/cli/__init__.py
View File

@ -11,10 +11,12 @@ import sys
import salt.cli.caller
import salt.cli.cp
import salt.cli.key
import salt.cli.batch
import salt.client
import salt.output
import salt.runner
from salt.utils.verify import verify_env
from salt import __version__ as VERSION
from salt.exceptions import SaltInvocationError, SaltClientError, \
SaltException
@ -43,6 +45,28 @@ class SaltCMD(object):
dest='timeout',
help=('Set the return timeout for batch jobs; '
'default=5 seconds'))
parser.add_option('-s',
'--static',
default=False,
dest='static',
action='store_true',
help=('Return the data from minions as a group after they '
'all return.'))
parser.add_option('-v',
'--verbose',
default=False,
dest='verbose',
action='store_true',
help=('Turn on command verbosity, display jid and active job '
'queries'))
parser.add_option('-b',
'--batch',
'--batch-size',
default='',
dest='batch',
help=('Execute the salt job in batch mode, pass either the '
'number of minions to batch at a time, or the '
'percentage of minions to have running'))
parser.add_option('-E',
'--pcre',
default=False,
@ -53,7 +77,7 @@ class SaltCMD(object):
parser.add_option('-L',
'--list',
default=False,
dest='list_',
dest='list',
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'servers, take a comma delimited list of servers.'))
@ -62,6 +86,14 @@ class SaltCMD(object):
default=False,
dest='grain',
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'use a grain value to identify targets, the syntax '
'for the target is the grain key followed by a glob'
'expression:\n"os:Arch*"'))
parser.add_option('--grain-pcre',
default=False,
dest='grain_pcre',
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'use a grain value to identify targets, the syntax '
'for the target is the grain key followed by a pcre '
@ -81,6 +113,14 @@ class SaltCMD(object):
help=('Instead of using shell globs to evaluate the target '
'use one of the predefined nodegroups to identify a '
'list of targets.'))
parser.add_option('-R',
'--range',
default=False,
dest='range',
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'use a range expression to identify targets. '
'Range expressions look like %cluster'))
parser.add_option('-C',
'--compound',
default=False,
@ -95,7 +135,7 @@ class SaltCMD(object):
'webser* or E@database.*\''))
parser.add_option('--return',
default='',
dest='return_',
dest='return',
metavar='RETURNER',
help=('Set an alternative return method. By default salt will '
'send the return data from the command back to the '
@ -104,9 +144,10 @@ class SaltCMD(object):
parser.add_option('-Q',
'--query',
dest='query',
default=False,
action='store_true',
help=('Execute a salt command query, this can be used to find '
help=('This option is deprecated and will be removed in a '
'future release, please use salt-run jobs instead\n'
'Execute a salt command query, this can be used to find '
'the results os a previous function call: -Q test.echo'))
parser.add_option('-c',
'--config',
@ -138,25 +179,22 @@ class SaltCMD(object):
action='store_true',
dest='json_out',
help='Print the output from the salt command in json.')
parser.add_option('--no-color',
default=False,
action='store_true',
dest='no_color',
help='Disable all colored output')
options, args = parser.parse_args()
opts = {}
for k, v in options.__dict__.items():
if v is not None:
opts[k] = v
if not options.timeout is None:
opts['timeout'] = int(options.timeout)
opts['pcre'] = options.pcre
opts['list'] = options.list_
opts['grain'] = options.grain
opts['exsel'] = options.exsel
opts['nodegroup'] = options.nodegroup
opts['compound'] = options.compound
opts['return'] = options.return_
opts['conf_file'] = options.conf_file
opts['raw_out'] = options.raw_out
opts['txt_out'] = options.txt_out
opts['yaml_out'] = options.yaml_out
opts['json_out'] = options.json_out
if options.query:
opts['query'] = options.query
@ -170,14 +208,14 @@ class SaltCMD(object):
# Catch invalid invocations of salt such as: salt run
if len(args) <= 1:
parser.print_help()
parser.exit()
parser.exit(1)
if opts['list']:
opts['tgt'] = args[0].split(',')
else:
opts['tgt'] = args[0]
if args[1].count(','):
if ',' in args[1]:
opts['fun'] = args[1].split(',')
opts['arg'] = []
for comp in ' '.join(args[2:]).split(','):
@ -203,6 +241,9 @@ class SaltCMD(object):
local = None
ret = exc
out = ''
self._output_ret(ret, out)
return
if 'query' in self.opts:
ret = local.find_cmd(self.opts['cmd'])
for jid in ret:
@ -223,7 +264,9 @@ class SaltCMD(object):
print 'Return data for job {0}:'.format(jid)
printout(ret[jid])
print ''
elif self.opts['batch']:
batch = salt.cli.batch.Batch(self.opts)
batch.run()
else:
if not 'timeout' in self.opts:
self.opts['timeout'] = local.opts['timeout']
@ -238,10 +281,14 @@ class SaltCMD(object):
args.append('list')
elif self.opts['grain']:
args.append('grain')
elif self.opts['grain_pcre']:
args.append('grain_pcre')
elif self.opts['exsel']:
args.append('exsel')
elif self.opts['nodegroup']:
args.append('nodegroup')
elif self.opts['range']:
args.append('range')
elif self.opts['compound']:
args.append('compound')
else:
@ -249,42 +296,53 @@ class SaltCMD(object):
if self.opts['return']:
args.append(self.opts['return'])
else:
args.append('')
try:
# local will be None when there was an error
if local:
full_ret = local.cmd_full_return(*args)
ret, out = self._format_ret(full_ret)
if self.opts['static']:
full_ret = local.cmd_full_return(*args)
ret, out = self._format_ret(full_ret)
self._output_ret(ret, out)
else:
if self.opts['verbose']:
args.append(True)
for full_ret in local.cmd_cli(*args):
ret, out = self._format_ret(full_ret)
self._output_ret(ret, out)
except SaltInvocationError as exc:
ret = exc
out = ''
# Handle special case commands
if self.opts['fun'] == 'sys.doc':
self._print_docs(ret)
else:
# Determine the proper output method and run it
get_outputter = salt.output.get_outputter
if isinstance(ret, list) or isinstance(ret, dict):
if self.opts['raw_out']:
printout = get_outputter('raw')
elif self.opts['json_out']:
printout = get_outputter('json')
elif self.opts['txt_out']:
printout = get_outputter('txt')
elif self.opts['yaml_out']:
printout = get_outputter('yaml')
elif out:
printout = get_outputter(out)
else:
printout = get_outputter(None)
# Pretty print any salt exceptions
elif isinstance(ret, SaltException):
printout = get_outputter("txt")
printout(ret)
# Always exit with a return code of 1 on issues
if isinstance(ret, Exception):
sys.exit(1)
def _output_ret(self, ret, out):
'''
Print the output from a single return to the terminal
'''
# Handle special case commands
if self.opts['fun'] == 'sys.doc':
self._print_docs(ret)
else:
# Determine the proper output method and run it
get_outputter = salt.output.get_outputter
if isinstance(ret, list) or isinstance(ret, dict):
if self.opts['raw_out']:
printout = get_outputter('raw')
elif self.opts['json_out']:
printout = get_outputter('json')
elif self.opts['txt_out']:
printout = get_outputter('txt')
elif self.opts['yaml_out']:
printout = get_outputter('yaml')
elif out:
printout = get_outputter(out)
else:
printout = get_outputter(None)
# Pretty print any salt exceptions
elif isinstance(ret, SaltException):
printout = get_outputter("txt")
color = not bool(self.opts['no_color'])
printout(ret, color=color)
def _format_ret(self, full_ret):
'''
@ -346,7 +404,7 @@ class SaltCP(object):
parser.add_option('-L',
'--list',
default=False,
dest='list_',
dest='list',
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'servers, take a comma delimited list of servers.'))
@ -357,7 +415,15 @@ class SaltCP(object):
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'use a grain value to identify targets, the syntax '
'for the target is the grains key followed by a pcre '
'for the target is the grain key followed by a glob'
'expression:\n"os:Arch*"'))
parser.add_option('--grain-pcre',
default=False,
dest='grain_pcre',
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'use a grain value to identify targets, the syntax '
'for the target is the grain key followed by a pcre '
'regular expression:\n"os:Arch.*"'))
parser.add_option('-N',
'--nodegroup',
@ -367,6 +433,14 @@ class SaltCP(object):
help=('Instead of using shell globs to evaluate the target '
'use one of the predefined nodegroups to identify a '
'list of targets.'))
parser.add_option('-R',
'--range',
default=False,
dest='range',
action='store_true',
help=('Instead of using shell globs to evaluate the target '
'use a range expressions to identify targets. '
'Range expressions look like %cluster'))
parser.add_option('-c',
'--config',
default='/etc/salt/master',
@ -379,16 +453,14 @@ class SaltCP(object):
opts = {}
opts['timeout'] = options.timeout
opts['pcre'] = options.pcre
opts['list'] = options.list_
opts['grain'] = options.grain
opts['nodegroup'] = options.nodegroup
opts['conf_file'] = options.conf_file
for k, v in options.__dict__.items():
if v is not None:
opts[k] = v
# salt-cp needs arguments
if len(args) <= 1:
parser.print_help()
parser.exit()
parser.exit(1)
if opts['list']:
opts['tgt'] = args[0].split(',')
@ -422,7 +494,7 @@ class SaltKey(object):
parser.add_option('-l',
'--list',
dest='list_',
dest='list',
default=False,
action='store_true',
help='List the unaccepted public keys')
@ -462,7 +534,7 @@ class SaltKey(object):
parser.add_option('-p',
'--print',
dest='print_',
dest='print',
default='',
help='Print the specified public key')
@ -479,16 +551,22 @@ class SaltKey(object):
default='',
help='Delete the named key')
parser.add_option('-D',
'--delete-all',
dest='delete_all',
default=False,
action='store_true',
help='Delete all keys')
parser.add_option('-q',
'--quiet',
dest='quiet',
default=False,
action='store_true',
help='Supress output')
parser.add_option('--logfile',
dest='logfile',
default='/var/log/salt/key.log',
parser.add_option('--key-logfile',
dest='key_logfile',
help=('Send all output to a file. '
'Default is /var/log/salt/key.log'))
@ -514,37 +592,26 @@ class SaltKey(object):
parser.add_option('-c',
'--config',
dest='config',
dest='conf_file',
default='/etc/salt/master',
help='Pass in an alternative configuration file')
options, args = parser.parse_args()
opts = {}
opts.update(salt.config.master_config(options.conf_file))
opts['quiet'] = options.quiet
opts['logfile'] = options.logfile
for k, v in options.__dict__.items():
if k == 'keysize':
if v < 2048:
opts[k] = v
else:
opts[k] = v
elif v is not None:
opts[k] = v
# I decided to always set this to info, since it really all is info or
# error.
opts['loglevel'] = 'info'
opts['list'] = options.list_
opts['list_all'] = options.list_all
opts['accept'] = options.accept
opts['accept_all'] = options.accept_all
opts['reject'] = options.reject
opts['reject_all'] = options.reject_all
opts['print'] = options.print_
opts['print_all'] = options.print_all
opts['delete'] = options.delete
opts['gen_keys'] = options.gen_keys
opts['gen_keys_dir'] = options.gen_keys_dir
if options.keysize < 2048:
opts['keysize'] = 2048
else:
opts['keysize'] = options.keysize
opts.update(salt.config.master_config(options.config))
return opts
def run(self):
@ -552,7 +619,7 @@ class SaltKey(object):
Execute saltkey
'''
import salt.log
salt.log.setup_logfile_logger(self.opts['logfile'],
salt.log.setup_logfile_logger(self.opts['key_logfile'],
self.opts['loglevel'])
key = salt.cli.key.Key(self.opts)
key.run()
@ -569,11 +636,12 @@ class SaltCall(object):
'''
Parse the command line arguments
'''
parser = optparse.OptionParser(version="%%prog %s" % VERSION)
usage = "%prog [options] <function> [arguments]"
parser = optparse.OptionParser(version='%%prog %s'.format(VERSION), usage=usage)
parser.add_option('-g',
'--grains',
dest='grains',
dest='grains_run',
default=False,
action='store_true',
help='Return the information generated by the salt grains')
@ -585,7 +653,7 @@ class SaltCall(object):
'from, multiple directories can be delimited by commas'))
parser.add_option('-c',
'--config',
dest='config',
dest='conf_file',
default='/etc/salt/minion',
help='Pass in an alternative configuration file')
parser.add_option('-d',
@ -632,27 +700,28 @@ class SaltCall(object):
options, args = parser.parse_args()
opts = {}
opts.update(salt.config.minion_config(options.conf_file))
for k, v in options.__dict__.items():
if k == 'module_dirs':
opts[k] = v.split(',')
else:
opts[k] = v
opts['grains_run'] = options.grains
opts['module_dirs'] = options.module_dirs.split(',')
opts['doc'] = options.doc
opts['raw_out'] = options.raw_out
opts['txt_out'] = options.txt_out
opts['yaml_out'] = options.yaml_out
opts['color'] = not options.no_color
opts['json_out'] = options.json_out
opts.update(salt.config.minion_config(options.config))
opts['log_level'] = options.log_level
if len(args) >= 1:
opts['fun'] = args[0]
opts['arg'] = args[1:]
elif opts['grains_run']:
pass
else:
opts['fun'] = ''
opts['arg'] = []
salt.verify_env([opts['pki_dir'],
opts['cachedir'],
os.path.dirname(opts['log_file']),
])
# salt-call should not ever be called without arguments
parser.print_help()
parser.exit(1)
verify_env([opts['pki_dir'],
opts['cachedir'],
os.path.dirname(opts['log_file']),
])
return opts
@ -684,7 +753,7 @@ class SaltRun(object):
parser.add_option('-c',
'--config',
dest='config',
dest='conf_file',
default='/etc/salt/master',
help=('Change the location of the master configuration; '
'default=/etc/salt/master'))
@ -702,10 +771,9 @@ class SaltRun(object):
options, args = parser.parse_args()
opts = {}
opts['config'] = options.config
opts.update(salt.config.master_config(options.conf_file))
opts['conf_file'] = options.conf_file
opts['doc'] = options.doc
if len(args) > 0:
opts['fun'] = args[0]
else:
@ -715,13 +783,11 @@ class SaltRun(object):
else:
opts['arg'] = []
opts.update(salt.config.master_config(options.config))
return opts
def run(self):
'''
Execute the salt call!
Execute salt-run
'''
runner = salt.runner.Runner(self.opts)
runner.run()

136
salt/cli/batch.py Normal file
View File

@ -0,0 +1,136 @@
'''
Execute batch runs
'''
# Import Python libs
import math
import time
import copy
# Import Salt libs
import salt.client
import salt.output
class Batch(object):
'''
Manage the execution of batch runs
'''
def __init__(self, opts):
self.opts = opts
self.local = salt.client.LocalClient(opts['conf_file'])
self.minions = self.__gather_minions()
def __gather_minions(self):
'''
Return a list of minions to use for the batch run
'''
args = [self.opts['tgt'],
'test.ping',
[],
1,
]
if self.opts['pcre']:
args.append('pcre')
elif self.opts['list']:
args.append('list')
elif self.opts['grain']:
args.append('grain')
elif self.opts['grain_pcre']:
args.append('grain_pcre')
elif self.opts['exsel']:
args.append('exsel')
elif self.opts['nodegroup']:
args.append('nodegroup')
elif self.opts['compound']:
args.append('compound')
else:
args.append('glob')
fret = []
for ret in self.local.cmd_iter(*args):
for minion in ret:
print '{0} Detected for this batch run'.format(minion)
fret.append(minion)
return sorted(fret)
def get_bnum(self):
'''
Return the active number of minions to maintain
'''
partition = lambda x: float(x) / 100.0 * len(self.minions)
try:
if '%' in self.opts['batch']:
res = partition(float(self.opts['batch'].strip('%')))
if res < 1:
return int(math.ceil(res))
else:
return int(res)
else:
return int(self.opts['batch'])
except ValueError:
print ('Invalid batch data sent: {0}\nData must be in the form'
'of %10, 10% or 3').format(self.opts['batch'])
def run(self):
'''
Execute the batch run
'''
args = [[],
self.opts['fun'],
self.opts['arg'],
9999999999,
'list',
]
bnum = self.get_bnum()
to_run = copy.deepcopy(self.minions)
active = []
ret = {}
iters = []
# Itterate while we still have things to execute
while len(ret) < len(self.minions):
next_ = []
if len(to_run) <= bnum and not active:
# last bit of them, add them all to next iterator
while to_run:
next_.append(to_run.pop())
else:
for ind in range(bnum - len(active)):
if to_run:
next_.append(to_run.pop())
active += next_
args[0] = next_
if next_:
print '\nExecuting run on {0}\n'.format(next_)
iters.append(
self.local.cmd_iter_no_block(*args))
else:
time.sleep(0.02)
parts = {}
for queue in iters:
try:
# Gather returns until we get to the bottom
ncnt = 0
while True:
part = queue.next()
if part is None:
time.sleep(0.01)
ncnt += 1
if ncnt > 5:
break
continue
parts.update(part)
except StopIteration:
# remove the iter, it is done
pass
for minion, data in parts.items():
active.remove(minion)
ret[minion] = data['ret']
data[minion] = data.pop('ret')
if 'out' in data:
out = data.pop('out')
else:
out = None
salt.output.display_output(
data,
out,
self.opts)
return ret

Some files were not shown because too many files have changed in this diff Show More