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

Merge pull request #10598 from cachedout/2_19_docfix

Browse Source 
2 19 docfix
This commit is contained in:
Thomas S Hatch 2014-02-19 19:11:12 -07:00
commit 553a4fe10f
23 changed files with 395 additions and 330 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -40,9 +40,11 @@ Full list of builtin execution modules
darwin_sysctl
data
ddns
deb_apache
debconfmod
debian_ip
debian_service
defaults
dig
disk
djangomod
@ -52,6 +54,7 @@ Full list of builtin execution modules
dpkg
ebuild
eix
environ
eselect
event
extfs
@ -67,16 +70,21 @@ Full list of builtin execution modules
gentoolkitmod
git
glance
glusterfs
gnomedesktop
grains
groupadd
grub_legacy
guestfs
hadoop
hg
hosts
htpasswd
img
incron
ini_manage
iptables
junos
key
keyboard
keystone
@ -145,6 +153,9 @@ Full list of builtin execution modules
rbenv
rdp
reg
rest_package
rest_sample
rest_service
ret
rh_ip
rh_service
@ -182,6 +193,7 @@ Full list of builtin execution modules
tomcat
upstart
useradd
uwsgi
virt
virtualenv_mod
win_autoruns

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -7,34 +7,38 @@ Salt execution modules are the functions called by the :command:`salt` command.
.. note::
Salt execution modules are different from state modules and cannot be
called directly within state files. You must use the `module` state module
to execute execution modules within state runs.
called directly within state files. You must use the :mod:`module <salt.states.module>`
state module to call execution modules within state runs.
.. seealso:: :ref:`Full list of builtin modules <all-salt.modules>`
Salt ships with many modules that cover a wide variety of tasks.
Salt ships with many modules that cover a wide variety of tasks.
Modules Are Easy to Write!
==========================
Salt modules are amazingly simple to write. Just write a regular Python module
or a regular `Cython`_ module and place it a directory called ``_modules/``
within the :conf_master:`file_roots` specified by the master config file, and
they will be synced to the minions when :mod:`state.highstate
<salt.modules.state.highstate>` is run, or by executing the
:mod:`saltutil.sync_modules <salt.modules.saltutil.sync_modules>` or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
Writing Salt execution modules is straightforward.
Any custom modules which have been synced to a minion, that are named the
same as one of Salt's default set of modules, will take the place of the default
module with the same name. Note that a module's default name is its filename
A Salt execution modules is a Python or `Cython`_ module
placed in a directory called ``_modules/``
within the :conf_master:`file_roots` as specified by the master config file. By
default this is `/srv/salt/_modules` on Linux systems.
Modules placed in ``_modules/`` will be synced to the minions when any of the following
Salt functions are called:
:mod:`state.highstate <salt.modules.state.highstate>`
:mod:`saltutil.sync_modules <salt.modules.saltutil.sync_modules>`
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
Note that a module's default name is its filename
(i.e. ``foo.py`` becomes module ``foo``), but that its name can be overridden
by using a :ref:`__virtual__ function <virtual-modules>`.
Since Salt modules are just Python/Cython modules, there are no restraints on
what you can put inside of a Salt module. If a Salt module has errors and
cannot be imported, the Salt minion will continue to load without issue and the
module with errors will simply be omitted.
If a Salt module has errors and cannot be imported, the Salt minion will continue
to load without issue and the module with errors will simply be omitted.
If adding a Cython module the file must be named ``<modulename>.pyx`` so that
the loader knows that the module needs to be imported as a Cython module. The
@ -43,94 +47,83 @@ starts, so only the ``*.pyx`` file is required.
.. _`Cython`: http://cython.org/
Cross Calling Modules
Cross-Calling Modules
=====================
All of the Salt modules are available to each other, and can be "cross called".
This means that, when creating a module, functions in modules that already exist
can be called.
All of the Salt execution modules are available to each other and modules can call
functions available in other execution modules.
The variable ``__salt__`` is packed into the modules after they are loaded into
the Salt minion. This variable is a :ref:`Python dictionary <python2:typesmapping>`
of all of the Salt functions, laid out in the same way that they are made available
to the Salt command.
the Salt minion.
Salt modules can be cross called by accessing the value in the ``__salt__`` dict:
The ``__salt__`` variable is a :ref:`Python dictionary <python2:typesmapping>`
containing all of the Salt functions. Dictionary keys are strings representing the
names of the modules and the values are the functions themselves.
Salt modules can be cross-called by accessing the value in the ``__salt__`` dict:
.. code-block:: python
def foo(bar):
return __salt__['cmd.run'](bar)
This code will call the Salt cmd module's ``run`` function and pass the argument
``bar``.
This code will call the `run` function in the :mod:`cmd <salt.modules.cmdmod>` and pass the argument
``bar`` to it.
Preloaded Modules Data
======================
Preloaded Execution Module Data
===============================
When interacting with execution modules often it is nice to be able to read information
dynamically about the minion or to load in configuration parameters for a module.
When interacting with modules often it is nice to be able to read information
dynamically about the minion, or load in configuration parameters for a module.
Salt allows for different types of data to be loaded into the modules by the
minion, as of this writing Salt loads information gathered from the Salt Grains
system and from the minion configuration file.
minion.
Grains Data
-----------
The Salt minion detects information about the system when started. This allows
for modules to be written dynamically with respect to the underlying hardware
and operating system. This information is referred to as Salt Grains, or
"grains of salt". The Grains system was introduced to replace Facter, since
relying on a Ruby application from a Python application was both slow and
inefficient. Grains support replaces Facter in all Salt releases after 0.8
The values detected by the Salt Grains on the minion are available in a
:ref:`dict <python2:typesmapping>` named ``__grains__`` and can be accessed
from within callable objects in the Python modules.
To see the contents of the grains dict for a given system in your deployment
To see the contents of the grains dictionary for a given system in your deployment
run the :func:`grains.items` function:
.. code-block:: bash
salt 'hostname' grains.items
salt 'hostname' grains.items --output=pprint
To use the ``__grains__`` dict simply call it as a Python dict from within your
code, an excellent example is available in the Grains module:
:mod:`salt.modules.grains`.
Any value in a grains dictionary can be accessed as any other Python dictionary. For
example, the grain representing the minion ID is stored in the ``id`` key and from
an execution module, the value would be stored in ``__grains__['id']``.
Module Configuration
--------------------
Since parameters for configuring a module may be desired, Salt allows for
configuration information stored in the main minion config file to be passed to
the modules.
configuration information from the minion configuation file to be passed to
execution modules.
Since the minion configuration file is a YAML document, arbitrary configuration
data can be passed in the minion config that is read by the modules. It is
data can be passed in the minion config that is read by the modules. It is therefore
**strongly** recommended that the values passed in the configuration file match
the module. This means that a value intended for the ``test`` module should be
named ``test.<value>``.
the module name. A value intended for the ``test`` execution module should be named
``test.<value>``.
Configuration also requires that default configuration parameters need to be
loaded as well. This can be done simply by adding the ``__opts__`` dict to the
top level of the module.
The test module contains usage of the module configuration, and the default
The test execution module contains usage of the module configuration and the default
configuration file for the minion contains the information and format used to
pass data to the modules. :mod:`salt.modules.test`, :file:`conf/minion`.
Printout Configuration
======================
Since module functions can return different data, and the way the data is
printed can greatly change the presentation, Salt has a printout
configuration.
Since execution module functions can return different data, and the way the data is
printed can greatly change the presentation, Salt has a printout configuration.
When writing a module the ``__outputter__`` dict can be declared in the module.
The ``__outputter__`` dict contains a mapping of function name to Salt
When writing a module the ``__outputter__`` dictionary can be declared in the module.
The ``__outputter__`` dictionary contains a mapping of function name to Salt
Outputter.
.. code-block:: python
@ -147,9 +140,9 @@ This will ensure that the text outputter is used.
Virtual Modules
===============
Sometimes a module should be presented in a generic way. A good example of this
Sometimes an execution module should be presented in a generic way. A good example of this
can be found in the package manager modules. The package manager changes from
one operating system to another, but the Salt module that interfaces with the
one operating system to another, but the Salt execution module that interfaces with the
package manager can be presented in a generic way.
The Salt modules for package managers all contain a ``__virtual__`` function
@ -170,30 +163,31 @@ function. Some examples:
- :blob:`yumpkg.py <salt/modules/yumpkg.py>`
- :blob:`apt.py <salt/modules/apt.py>`
.. note::
Modules which return a string from ``__virtual__`` that is already used by a module that
ships with Salt will _override_ the stock module.
Documentation
=============
Salt modules are self documenting, the :func:`sys.doc` function will return the
Salt execution modules are documented. The :func:`sys.doc` function will return the
documentation for all available modules:
.. code-block:: bash
salt '*' sys.doc
This function simply prints out the docstrings found in the modules; when
writing Salt modules, please follow the formatting conventions for docstrings as
The ``sys.doc`` function simply prints out the docstrings found in the modules; when
writing Salt execution modules, please follow the formatting conventions for docstrings as
they appear in the other modules.
Adding Documentation to Salt Modules
------------------------------------
Since life is much better with documentation, it is strongly suggested that
all Salt modules have documentation added. Any Salt modules submitted for
inclusion in the main distribution of Salt will be required to have
documentation.
It is strongly suggested that all Salt modules have documentation added.
Documenting Salt modules is easy! Just add a `Python docstring`_ to the function.
To add documenation add a `Python docstring`_ to the function.
.. code-block:: python
@ -212,11 +206,15 @@ to the calling terminal.
.. _`Python docstring`: http://docs.python.org/2/glossary.html#term-docstring
Documentation added to execution modules in docstrings will automatically be added
to the online web-based documentation.
Add Module metadata
-------------------
Add information about the module using the following field lists:
Add Execution Module Metadata
-----------------------------
When writing a Python docstring for an execution module, add information about the module
using the following field lists:
.. code-block:: text
@ -237,10 +235,10 @@ on.
The platform field is a comma-delimited list of platforms that this module is
known to run on.
How Functions are Read
======================
Private Functions
=================
In Salt, Python callable objects contained within a module are made available
In Salt, Python callable objects contained within an execution module are made available
to the Salt minion for use. The only exception to this rule is a callable
object with a name starting with an underscore ``_``.
@ -269,22 +267,24 @@ Objects NOT Loaded into the Salt Minion
.. note::
Some callable names also end with an underscore ``_``, to avoid keyword clashes
with Python keywords. When using Salt modules, or state modules, with these
with Python keywords. When using execution modules, or state modules, with these
in them the trailing underscore should be omitted.
Useful Decorators for Modules
=============================
Sometimes when writing modules for large scale deployments you run into some small
things that end up severely complicating the code. To alleviate some of this pain
Salt has some useful decorators for use within modules!
Depends Decorator
-----------------
When writing custom modules there are many times where some of the module will
work on all hosts, but some functions require (for example) a service to be installed.
Instead of trying to wrap much of the code in large try/except blocks you can use
a simple decorator to do this. If the dependencies passed to the decorator don't
exist, then the salt minion will remove those functions from the module on that host.
When writing execution modules there are many times where some of the module will
work on all hosts but some functions have an external dependency, such as a service
that needs to be installed or a binary that needs to be present on the system.
Instead of trying to wrap much of the code in large try/except blocks, a decorator can
be used.
If the dependencies passed to the decorator don't exist, then the salt minion will remove
those functions from the module on that host.
If a "fallback_function" is defined, it will replace the function instead of removing it
.. code-block:: python
@ -324,29 +324,3 @@ If a "fallback_function" is defined, it will replace the function instead of rem
return True
Examples of Salt Modules
========================
The existing Salt modules should be fairly easy to read and understand, the
goal of the main distribution's Salt modules is not only to build a set of
functions for Salt, but to stand as examples for building out more Salt
modules.
The existing modules can be found here:
:blob:`salt/modules`
The most simple module is the test module, it contains the simplest Salt
function, ``test.ping``:
.. code-block:: python
def ping():
'''
Just used to make sure the minion is up and responding
Return True
CLI Example::
salt '*' test.ping
'''
return True

100
doc/ref/renderers/index.rst
View File

@ -2,35 +2,41 @@
Renderers
=========
The Salt state system operates by gathering information from simple data
structures. The state system was designed in this way to make interacting with
it generic and simple. This also means that state files (SLS files) can be one
of many formats.
The Salt state system operates by gathering information from common data
types such as lists, dictionaries and strings that would be familiar
to any developer.
SLS files are translated from whatever data templating format they are written
in back into Python data types to be consumed by Salt.
By default SLS files are rendered as Jinja templates and then parsed as YAML
documents. But since the only thing the state system cares about is raw data,
the SLS files can be any structured format that can be dreamed up.
Currently there is support for ``Jinja + YAML``, ``Mako + YAML``,
``Wempy + YAML``, ``Jinja + json`` ``Mako + json`` and ``Wempy + json``. But
renderers can be written to support anything. This means that the Salt states
could be managed by XML files, HTML files, puppet files, or any format that
can be translated into the data structure used by the state system.
``Wempy + YAML``, ``Jinja + json`` ``Mako + json`` and ``Wempy + json``.
Renderers can be written to support any template type. This means that the
Salt states could be managed by XML files, HTML files, Puppet files, or any
format that can be translated into the Pythonic data structure used by the state
system.
Multiple Renderers
------------------
When deploying a state tree a default renderer is selected in the master
configuration file with the renderer option. But multiple renderers can be
used inside the same state tree.
A default renderer is selected in the master configuration file by providing
a value to the ``renderer`` key.
When rendering SLS files Salt checks for the presence of a Salt specific
shebang line. The shebang line syntax was chosen because it is familiar to
the target audience, the systems admin and systems engineer.
When evaluating an SLS, more than one renderer can be used.
When rendering SLS files, Salt checks for the presence of a Salt-specific
shebang line.
The shebang line directly calls the name of the renderer as it is specified
within Salt. One of the most common reasons to use multiple renderers in to
use the Python or ``py`` renderer:
within Salt. One of the most common reasons to use multiple renderers is to
use the Python or ``py`` renderer.
Below, the first line is a shebang that references the ``py`` renderer.
.. code-block:: python
@ -43,16 +49,17 @@ use the Python or ``py`` renderer:
return {'include': ['python'],
'python-mako': {'pkg': ['installed']}}
The first line is a shebang that references the ``py`` renderer.
Composing Renderers
-------------------
A renderer can be composed from other renderers by connecting them in a series
of pipes(``|``). In fact, the default ``Jinja + YAML`` renderer is implemented
by combining a YAML renderer and a Jinja renderer. Such renderer configuration
is specified as: ``jinja | yaml``.
of pipes(``|``).
Other renderer combinations are possible, here's a few examples:
In fact, the default ``Jinja + YAML`` renderer is implemented by connecting a YAML
renderer to a Jinja renderer. Such renderer configuration is specified as: ``jinja | yaml``.
Other renderer combinations are possible:
``yaml``
i.e, just YAML, no templating.
@ -65,7 +72,7 @@ Other renderer combinations are possible, here's a few examples:
This one allows you to use both jinja and mako templating syntax in the
input and then parse the final rendered output as YAML.
And here's a contrived example sls file using the ``jinja | mako | yaml`` renderer:
The following is a contrived example SLS file using the ``jinja | mako | yaml`` renderer:
.. code-block:: python
@ -81,33 +88,41 @@ And here's a contrived example sls file using the ``jinja | mako | yaml`` render
<%doc> ${...} is Mako's notation, and so is this comment. </%doc>
{# Similarly, {{...}} is Jinja's notation, and so is this comment. #}
For backward compatibility, ``jinja | yaml`` can also be written as
For backward compatibility, ``jinja | yaml`` can also be written as
``yaml_jinja``, and similarly, the ``yaml_mako``, ``yaml_wempy``,
``json_jinja``, ``json_mako``, and ``json_wempy`` renderers are all supported
as well.
``json_jinja``, ``json_mako``, and ``json_wempy`` renderers are all supported.
Keep in mind that not all renderers can be used alone or with any other renderers.
For example, the template renderers shouldn't be used alone as their outputs are
just strings, which still need to be parsed by another renderer to turn them into
highstate data structures. Also, for example, it doesn't make sense to specify
``yaml | jinja`` either, because the output of the yaml renderer is a highstate
data structure(a dict in Python), which cannot be used as the input to a template
renderer. Therefore, when combining renderers, you should know what each renderer
accepts as input and what it returns as output.
highstate data structures.
For example, it doesn't make sense to specify ``yaml | jinja`` because the
output of the YAML renderer is a highstate data structure (a dict in Python), which
cannot be used as the input to a template renderer. Therefore, when combining
renderers, you should know what each renderer accepts as input and what it returns
as output.
Writing Renderers
-----------------
Writing a renderer is easy, all that is required is that a Python module is
placed in the rendered directory and that the module implements the ``render``
function. The ``render`` function will be passed the path of the SLS file. In
the ``render`` function, parse the passed file and return the data structure
derived from the file. You can place your custom renderers in a ``_renderers``
directory within the :conf_master:`file_roots` specified by the master config
file. These custom renderers are distributed when :mod:`state.highstate
<salt.modules.state.highstate>` is run, or by executing the
:mod:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>` or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
A custom renderer must be a Python module placed in the rendered directory and the
module implement the ``render`` function.
The ``render`` function will be passed the path of the SLS file as an argument.
The purpose of of ``render`` function is to parse the passed file and to return
the Python data structure derived from the file.
Custom renderers must be placed in a ``_renderers`` directory within the
:conf_master:`file_roots` specified by the master config file.
Custom renderers are distributed when any of the following are run:
:mod:`state.highstate <salt.modules.state.highstate>`
:mod:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>`
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
Any custom renderers which have been synced to a minion, that are named the
same as one of Salt's default set of renderers, will take the place of the
@ -117,8 +132,9 @@ default renderer with the same name.
Examples
--------
The best place to find examples of renderers is in the Salt source code. The
renderers included with Salt can be found here:
The best place to find examples of renderers is in the Salt source code.
Documentation for renderers included with Salt can be found here:
:blob:`salt/renderers`

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

@ -3,24 +3,23 @@ Returners
=========
By default the return values of the commands sent to the Salt minions are
returned to the salt-master. But since the commands executed on the Salt
minions are detached from the call on the Salt master, anything at all can be
done with the results data.
returned to the Salt master, however anything at all can be done with the results
data.
This is where the returner interface comes in. Returners are modules called
in addition to returning the data to the Salt master.
By using a Salt returner, results data can be redirected to external data-stores
for analysis and archival.
The returner interface allows the return data to be sent to any system that
can receive data. This means that return data can be sent to a Redis server,
a MongoDB server, a MySQL server, or any system!
a MongoDB server, a MySQL server, or any system.
.. seealso:: :ref:`Full list of builtin returners <all-salt.returners>`
Using Returners
===============
All commands will return the command data back to the master. Adding more
returners will ensure that the data is also sent to the specified returner
All Salt commands will return the command data back to the master. Specifying
returners will ensure that the data is _also_ sent to the specified returner
interfaces.
Specifying what returners to use is done when the command is invoked:
@ -43,12 +42,13 @@ test.ping command will be sent out to the three named returners.
Writing a Returner
==================
A returner is a module which contains a returner function, the returner
function must accept a single argument. this argument is the return data from
A returner is a Python module which contains a function called ``returner``.
The ``returner`` function must accept a single argument for the return data from
the called minion function. So if the minion function ``test.ping`` is called
the value of the argument will be ``True``.
A simple returner is implemented here:
A simple returner is implemented below:
.. code-block:: python
@ -69,23 +69,28 @@ A simple returner is implemented here:
serv.sadd('jobs', ret['jid'])
serv.sadd(ret['jid'], ret['id'])
This simple example of a returner set to send the data to a redis server
serializes the data as json and sets it in redis.
The above example of a returner set to send the data to a Redis server
serializes the data as JSON and sets it in redis.
You can place your custom returners in a ``_returners`` directory within the
:conf_master:`file_roots` specified by the master config file. These custom
returners are distributed when :mod:`state.highstate
<salt.modules.state.highstate>` is run, or by executing the
:mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>` or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
Place custom returners in a ``_returners`` directory within the
:conf_master:`file_roots` specified by the master config file.
Any custom returners which have been synced to a minion, that are named the
same as one of Salt's default set of returners, will take the place of the
default returner with the same name. Note that a returner's default name is its
filename (i.e. ``foo.py`` becomes returner ``foo``), but that its name can be
overridden by using a :ref:`__virtual__ function <virtual-modules>`. A good
example of this can be found in the `redis`_ returner, which is named
``redis_return.py`` but is loaded as simply ``redis``:
Custom returners are distributed when any of the following are called:
:mod:`state.highstate <salt.modules.state.highstate>`
:mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>`
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
Any custom returners which have been synced to a minion that are named the
same as one of Salt's default set of returners will take the place of the
default returner with the same name.
Note that a returner's default name is its filename (i.e. ``foo.py`` becomes
returner ``foo``), but that its name can be overridden by using a
:ref:`__virtual__ function <virtual-modules>`. A good example of this can be
found in the `redis`_ returner, which is named ``redis_return.py`` but is
loaded as simply ``redis``:
.. code-block:: python
@ -101,9 +106,3 @@ example of this can be found in the `redis`_ returner, which is named
return 'redis'
.. _`redis`: https://github.com/saltstack/salt/blob/develop/salt/returners/redis_return.py
Examples
--------
The collection of built-in Salt returners can be found here:
:blob:`salt/returners`

25
doc/ref/runners/index.rst
View File

@ -2,27 +2,24 @@
Salt Runners
============
.. seealso:: :ref:`The full list of runners <all-salt.runners>`
Salt runners are convenience applications executed with the salt-run command.
Salt runners work similar to salt modules however they execute on the
Salt master itself instead of each individual Salt minion.
Salt runners work similarly to Salt execution modules however they execute on the
Salt master itself instead of remote Salt minions.
A Salt runner can be a simple client call, or a complex application.
A Salt runner can be a simple client call or a complex application.
The use for a Salt runner is to build a frontend hook for running sets of
commands via Salt or creating special formatted output.
.. seealso:: :ref:`The full list of runners <all-salt.runners>`
Writing Salt Runners
--------------------
A Salt runner is written very similar to a Salt module. Both are Python
modules which contain functions and each public function is a runner
which may be executed via the *salt-run* command.
A Salt runner is written in a similar manner to a Salt execution module.
Both are Python modules which contain functions and each public function
is a runner which may be executed via the *salt-run* command.
For example, if a Python module named test.py is created in the runners
directory and contains a function called ``foo``, the runner could be
For example, if a Python module named ``test.py`` is created in the runners
directory and contains a function called ``foo``, the ``test`` runner could be
invoked with the following command:
.. code-block:: bash
@ -32,12 +29,12 @@ invoked with the following command:
Examples
--------
The best examples of runners can be found in the Salt source:
Examples of runners can be found in the Salt distribution:
:blob:`salt/runners`
A simple runner that returns a well-formatted list of the minions that are
responding to Salt calls would look like this:
responding to Salt calls could look like this:
.. code-block:: python

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

@ -6,20 +6,17 @@ Salt offers an optional interface to manage the configuration or "state" of the
Salt minions. This interface is a fully capable mechanism used to enforce the
state of systems from a central manager.
The Salt state system is made to be accurate, simple, and fast. And like the
rest of the Salt system, Salt states are highly modular.
State management
================
State management, also frequently called software configuration management
State management, also frequently called Software Configuration Management
(SCM), is a program that puts and keeps a system into a predetermined state. It
installs software packages, starts or restarts services, or puts configuration
installs software packages, starts or restarts services or puts configuration
files in place and watches them for changes.
Having a state management system in place allows you to easily and reliably
configure and manage a few servers or a few thousand servers. It allows you to
keep that configuration under version control.
Having a state management system in place allows one to easily and reliably
configure and manage a few servers or a few thousand servers. It allows
configurations to be kept under version control.
Salt States is an extension of the Salt Modules that we discussed in the
previous :doc:`remote execution </topics/tutorials/modules>` tutorial. Instead
@ -36,7 +33,7 @@ an understanding of Salt states and how to write the states is needed as well.
.. note::
States are compiled and executed only on minions that have been targeted.
To execute things on masters, see `runners`_.
To execute functions directly on masters, see `runners`_.
Salt SLS System
---------------
@ -59,8 +56,9 @@ Salt SLS System
SLS File Layout
```````````````
SLS files are laid out in the Salt file server. A simple layout can look like
this:
SLS files are laid out in the Salt file server.
A simple layout can look like this:
.. code-block:: yaml
@ -69,39 +67,43 @@ this:
sshd_config
users/init.sls
users/admin.sls
salt/init.sls
salt/master.sls
web/init.sls
This example shows the core concepts of file layout. The top file is a key
component and is used with Salt matchers to match SLS states with minions.
The ``.sls`` files are states. The rest of the files are seen by the Salt
master as just files that can be downloaded.
The ``top.sls`` file is a key component. The ``top.sls`` files
is used to determine which SLS files should be applied to which minions.
The states are translated into dot notation, so the ``ssh.sls`` file is
seen as the ssh state, the ``users/admin.sls`` file is seen as the
users.admin states.
The rest of the files with the ``.sls`` extension in the above example are
state files.
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.
Files without a ``.sls`` extensions are seen by the Salt master as
files that can be downloaded to a Salt minion.
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
States are translated into dot notation. For example, the ``ssh.sls`` file is
seen as the ssh state and the ``users/admin.sls`` file is seen as the
users.admin state.
Files named ``init.sls`` are translated to be the state name of the parent
directory, so the ``web/init.sls`` file translates to the ``web`` state.
In Salt, everything is a file; there is no "magic translation" of files and file
types. This means that a state file can be distributed to minions just like a
plain text or binary file.
SLS Files
`````````
The Salt state files are simple sets of data. Since the SLS files are just data
they can be represented in a number of different ways. The default format is
yaml generated from a Jinja template. This allows for the states files to have
all the language constructs of Python and the simplicity of yaml. State files
can then be complicated Jinja templates that translate down to yaml, or just
plain and simple yaml files!
The Salt state files are simple sets of data. Since SLS files are just data
they can be represented in a number of different ways.
The State files are constructed data structures in a simple format. The format
allows for many real activates to be expressed in very little text, while
maintaining the utmost in readability and usability.
The default format is YAML generated from a Jinja template. This allows for the
states files to have all the language constructs of Python and the simplicity of YAML.
State files can then be complicated Jinja templates that translate down to YAML, or just
plain and simple YAML files.
The State files are simply common data structures such as dictionaries and lists, constructed
using a templating language such as YAML.
Here is an example of a Salt State:
@ -142,12 +144,16 @@ watched file updated.
The Top File
````````````
The top file is the mapping for the state system. The top file specifies which
minions should have which modules applied and which environments they should
draw the states from.
The top file controls the mapping between minions and the states which should be
applied to them.
The top file works by specifying the environment, containing matchers with
lists of Salt states sent to the matching minions:
The top file specifies which minions should have which SLS files applied and which
environments they should draw those SLS files from.
The top file works by specifying environments on the top-level.
Each environment contains globs to match minions. Finally, each glob contains a list of
lists of Salt states to apply to matching minions:
.. code-block:: yaml
@ -160,46 +166,28 @@ lists of Salt states sent to the matching minions:
- match: pcre
- salt.master
This simple example uses the base environment, which is built into the default
Salt setup, and then all minions will have the modules salt, users and
users.admin since '*' will match all minions. Then the regular expression
matcher will match all minions' with an id matching saltmaster.* and add the
salt.master state.
This above example uses the base environment which is built into the default
Salt setup.
Renderer System
---------------
The Renderer system is a key component to the state system. SLS files are
representations of Salt "high data" structures. All Salt cares about when
reading an SLS file is the data structure that is produced from the file.
This allows Salt states to be represented by multiple types of files. The
Renderer system can be used to allow different formats to be used for SLS
files.
The available renderers can be found in the renderers directory in the Salt
source code:
:blob:`salt/renderers`
By default SLS files are rendered using Jinja as a templating engine, and yaml
as the serialization format. Since the rendering system can be extended simply
by adding a new renderer to the renderers directory, it is possible that any
structured file could be used to represent the SLS files.
In the future XML will be added, as well as many other formats.
The base environment has two globs. First, the '*' glob contains a list of
SLS files to apply to all minions.
The second glob contains a regular expression that will match all minions with
an ID matching saltmaster.* and specifies that for those minions, the salt.master
state should be applied.
Reloading Modules
-----------------
Some salt states require specific packages to be installed in order for the
module to load, as an example the :mod:`pip <salt.states.pip_state>` state
module requires the `pip`_ package for proper name and version parsing. On
most of the common cases, salt is clever enough to transparently reload the
modules, for example, if you install a package, salt reloads modules because
Some Salt states require that specific packages be installed in order for the
module to load. As an example the :mod:`pip <salt.states.pip_state>` state
module requires the `pip`_ package for proper name and version parsing.
In most of the common cases, Salt is clever enough to transparently reload the
modules. For example, if you install a package, Salt reloads modules because
some other module or state might require just that package which was installed.
On some edge-cases salt might need to be told to reload the modules. Consider
On some edge-cases salt might need to be told to reload the modules. Consider
the following state file which we'll call ``pep8.sls``:
.. code-block:: yaml
@ -265,19 +253,22 @@ If we executed the state again the output would be:
Total: 2
Since we installed `pip`_ using :mod:`cmd <salt.states.cmd>`, salt has no way
to know that a system-wide package was installed. On the second execution,
since the required `pip`_ package was installed, the state executed perfectly.
Since we installed `pip`_ using :mod:`cmd <salt.states.cmd>`, Salt has no way
to know that a system-wide package was installed.
To those thinking, could not salt reload modules on every state step since it
already does for some cases? It could, but it should not since it would
greatly slow down state execution.
On the second execution, since the required `pip`_ package was installed, the
state executed correctly.
.. note::
Salt does not reload modules on every state run because doing so would greatly
slow down state execution.
So how do we solve this *edge-case*? ``reload_modules``!
``reload_modules`` is a boolean option recognized by salt on **all** available
states which, does exactly what it tells use, forces salt to reload it's
modules once that specific state finishes. The fixed state file would now be:
states which forces salt to reload its modules once a given state finishes.
The modified state file would now be:
.. code-block:: yaml
@ -300,7 +291,7 @@ Let's run it, once:
salt-call state.sls pep8
And it's output now is:
The output is:
.. code-block:: text

33
doc/topics/eauth/index.rst
View File

@ -4,14 +4,12 @@
External Authentication System
==============================
Salt 0.10.4 comes with a fantastic new way to open up running Salt commands
to users. This system allows for Salt itself to pass through authentication to
any authentication system (The Unix PAM system was the first) to determine
if a user has permission to execute a Salt command.
Salt's External Authentication System (eAuth) allows for Salt to pass through
command authorization to any external authentication system, such as PAM or LDAP.
The external authentication system allows for specific users to be granted
access to execute specific functions on specific minions. Access is configured
in the master configuration file, and uses the new :ref:`access control system
in the master configuration file and uses the :ref:`access control system
<acl>`:
.. code-block:: yaml
@ -25,9 +23,9 @@ in the master configuration file, and uses the new :ref:`access control system
steve:
- .*
So, the above allows the user thatch to execute functions in the test and
network modules on the minions that match the web* target. User steve is
given unrestricted access to minion commands.
The above configuration allows the user ``thatch`` to execute functions
in the test and network modules on the minions that match the web* target.
User ``steve`` is given unrestricted access to minion commands.
.. note:: The PAM module does not allow authenticating as ``root``.
@ -42,8 +40,8 @@ modules <all-salt.runners>` the following ``@`` syntax must be used:
- '@wheel'
- '@runner'
The external authentication system can then be used from the command line by
any user on the same system as the master with the `-a` option:
The external authentication system can then be used from the command-line by
any user on the same system as the master with the ``-a`` option:
.. code-block:: bash
@ -55,18 +53,21 @@ authentication system and then publish the command.
Tokens
------
With external authentication alone the authentication credentials will be
With external authentication alone, the authentication credentials will be
required with every call to Salt. This can be alleviated with Salt tokens.
The tokens are short term authorizations and can be easily created by just
Tokens are short term authorizations and can be easily created by just
adding a ``-T`` option when authenticating:
.. code-block:: bash
$ salt -T -a pam web\* test.ping
Now a token will be created that has a expiration of, by default, 12 hours.
Now a token will be created that has a expiration of 12 hours (by default).
This token is stored in a file named ``.salt_token`` in the active user's home
directory. Once the token is created, it is sent with all subsequent communications.
The user authentication does not need to be entered again until the token expires. The
token expiration time can be set in the Salt master config file.
directory.
Once the token is created, it is sent with all subsequent communications.
User authentication does not need to be entered again until the token expires.
Token expiration time can be set in the Salt master config file.

45
doc/topics/event/index.rst
View File

@ -2,13 +2,13 @@
Salt Event System
=================
Salt 0.9.10 introduced the Salt Event System. This system is used to fire
off events enabling third party applications or external processes to react
to behavior within Salt.
The Salt Event System is used to fire off events enabling third party
applications or external processes to react to behavior within Salt.
The event system is comprised of a few components, the event sockets which
publish events, and the event library which can listen to events and send
events into the salt system.
The event system is comprised of a two primary components:
* The event sockets which publishes events.
* The event library which can listen to events and send events into the salt system.
Listening for Events
====================
@ -30,11 +30,14 @@ The following code will check for a single event:
data = event.get_event()
Events will also use a "tag". A "tag" allows for events to be filtered. By
default all events will be returned, but if only authentication events are
desired, then pass the tag "auth". Also, the get_event method has a default
poll time assigned of 5 seconds, to change this time set the "wait" option.
This example will only listen for auth events and will wait for 10 seconds
Events will also use a "tag". Tags allow for events to be filtered. By
default all events will be returned. If only authentication events are
desired, then pass the tag "auth".
The ``get_event`` method has a default poll time assigned of 5 seconds. To
change this time set the "wait" option.
The following example will only listen for auth events and will wait for 10 seconds
instead of the default 5.
.. code-block:: python
@ -45,9 +48,10 @@ instead of the default 5.
data = event.get_event(wait=10, tag='auth')
Instead of looking for a single event, the iter_events method can be used to
make a generator which will continually yield salt events. The iter_events
method also accepts a tag, but not a wait time:
Instead of looking for a single event, the ``iter_events`` method can be used to
make a generator which will continually yield salt events.
The iter_events method also accepts a tag but not a wait time:
.. code-block:: python
@ -62,9 +66,10 @@ method also accepts a tag, but not a wait time:
Firing Events
=============
It is possible to fire events on either the minion's local bus, or to fire
events intended for the master. To fire a local event from the minion, on the
command line:
It is possible to fire events on either the minion's local bus or to fire
events intended for the master.
To fire a local event from the minion, on the command line:
.. code-block:: bash
@ -129,8 +134,8 @@ So long as the salt-master process is running, the master socket can be used:
sock_dir = '/var/run/salt/master'
This allows 3rd party applications to harness the power of the Salt event bus
programmatically, without having to make other calls to Salt. A 3rd party
process can listen to the event bus on the master, and another 3rd party
programmatically, without having to make other calls to Salt.
A 3rd party process can listen to the event bus on the master and another 3rd party
process can fire events to the process on the master, which Salt will happily
pass along.

15
doc/topics/git/index.rst
View File

@ -3,11 +3,12 @@ SaltStack Git Policy
====================
The SaltStack team follows a git policy to maintain stability and consistency
with the repository. The git policy has been developed to encourage
contributions and make contributing to Salt as easy as possible. Code
contributors to SaltStack projects DO NOT NEED TO READ THIS DOCUMENT, because
all contributions come into SaltStack via a single gateway to make it as
easy as possible for contributors to give us code.
with the repository.
The git policy has been developed to encourage contributions and make contributing
to Salt as easy as possible. Code contributors to SaltStack projects DO NOT NEED
TO READ THIS DOCUMENT, because all contributions come into SaltStack via a single
gateway to make it as easy as possible for contributors to give us code.
The primary rule of git management in SaltStack is to make life easy on
contributors and developers to send in code. Simplicity is always a goal!
@ -15,8 +16,8 @@ contributors and developers to send in code. Simplicity is always a goal!
New Code Entry
==============
All new SaltStack code is posted to the `develop` branch, this is the single
point of entry. The only exception here is when a bugfix to develop cannot be
All new SaltStack code is posted to the `develop` branch, which is the single
point of entry. The only exception is when a bugfix to develop cannot be
cleanly merged into a release branch and the bugfix needs to be rewritten for
the release branch.

10
doc/topics/installation/index.rst
View File

@ -3,10 +3,6 @@
============
Installation
============
The Salt system setup is amazingly simple, as this is one of the central design
goals of Salt.
.. seealso::
:doc:`Installing Salt for development </topics/hacking>` and contributing
@ -44,10 +40,10 @@ See `Salt Bootstrap`_ for more information.
.. _`Salt Bootstrap`: https://github.com/saltstack/salt-bootstrap
Platform-specific installation instructions
Platform-specific Installation Instructions
-------------------------------------------
These guides go into detail how to install salt on a given platform.
These guides go into detail how to install Salt on a given platform.
.. toctree::
:maxdepth: 1
@ -77,6 +73,8 @@ Salt should run on any Unix-like platform so long as the dependencies are met.
* `msgpack-python`_ - High-performance message interchange format
* `YAML`_ - Python YAML bindings
* `Jinja2`_ - parsing Salt States (configurable in the master settings)
* `MarkupSafe`_ - Implements a XML/HTML/XHTML Markup safe string for Python
* `apache-libcloud` - Python lib for interacting with many of the popular cloud service providers using a unified API
Optional Dependencies
---------------------

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

@ -5,13 +5,12 @@ Job Management
.. versionadded:: 0.9.7
Since Salt executes jobs running on many systems, Salt needs to be able to
manage jobs running on many systems. As of Salt 0.9.7, the capability was
added for more advanced job management.
manage jobs running on many systems.
The Minion proc System
======================
The Salt Minions now maintain a *proc* directory in the Salt cachedir, the *proc*
Salt Minions maintain a *proc* directory in the Salt ``cachedir``. The *proc*
directory maintains files named after the executed job ID. These files contain
the information about the current running jobs on the minion and allow for
jobs to be looked up. This is located in the *proc* directory under the