saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-16 09:40:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

documentation updates

Browse source
This commit is contained in:
L.C. Rees 2012-05-22 22:43:12 -06:00
parent bd0ce29c89
commit 3315dad9e7
64 changed files with 438 additions and 375 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/contents.rst
View file

@ -34,7 +34,7 @@ Full Table of Contents
ref/runners
ref/peer
ref/syndic
ref/python-api
ref/Python-api
ref/file_server/index
ref/file_server/file_roots
ref/file_server/dynamic-modules

6
doc/man/salt-key.1
View file

@ -35,7 +35,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
salt\-key [ options ]
.SH DESCRIPTION
.sp
Salt\-key executes simple management of salt server public keys used for
Salt\-key executes simple management of Salt server public keys used for
authentication.
.SH OPTIONS
.INDENT 0.0
@ -51,7 +51,7 @@ List the unaccepted minion public keys.
.INDENT 0.0
.TP
.B \-L, \-\-list\-all
List all public keys on this salt master: accepted, pending,
List all public keys on this Salt master: accepted, pending,
and rejected.
.UNINDENT
.INDENT 0.0
@ -87,7 +87,7 @@ Deleta all keys
.INDENT 0.0
.TP
.B \-c CONFIG, \-\-config=CONFIG
The master configuration file needs to be read to determine where the salt
The master configuration file needs to be read to determine where the Salt
keys are stored via the pki_dir configuration value;
default=/etc/salt/master
.UNINDENT

8
doc/man/salt-master.1
View file

@ -31,13 +31,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" Man page generated from reStructeredText.
.
.sp
The salt master daemon, used to control the salt minions
The Salt master daemon, used to control the Salt minions
.SH SYNOPSIS
.sp
salt\-master [ options ]
Salt\-master [ options ]
.SH DESCRIPTION
.sp
The master daemon controls the salt minions
The master daemon controls the Salt minions
.SH OPTIONS
.INDENT 0.0
.TP
@ -47,7 +47,7 @@ Print a usage message briefly summarizing these command\-line options.
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run the salt master as a daemon
Run the Salt master as a daemon
.UNINDENT
.INDENT 0.0
.TP

6
doc/man/salt-minion.1
View file

@ -31,13 +31,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" Man page generated from reStructeredText.
.
.sp
The salt minion daemon, receives commands from a remote salt master.
The Salt minion daemon, receives commands from a remote Salt master.
.SH SYNOPSIS
.sp
salt\-minion [ options ]
.SH DESCRIPTION
.sp
The salt minion receives commands from the central salt master and replies with
The Salt minion receives commands from the central Salt master and replies with
the results of said commands.
.SH OPTIONS
.INDENT 0.0
@ -48,7 +48,7 @@ Print a usage message briefly summarizing these command\-line options.
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run the salt minion as a daemon
Run the Salt minion as a daemon
.UNINDENT
.INDENT 0.0
.TP

2
doc/man/salt-run.1
View file

@ -53,7 +53,7 @@ Print a usage message briefly summarizing these command\-line options
.INDENT 0.0
.TP
.B \-c CONFIG, \-\-config=CONFIG
The location of the salt master configuration file, the salt master
The location of the Salt master configuration file, the Salt master
settings are required to know where the connections are;
default=/etc/salt/master
.UNINDENT

6
doc/man/salt-syndic.1
View file

@ -31,14 +31,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" Man page generated from reStructeredText.
.
.sp
The salt syndic daemon, a special minion that passes through commands from a
The Salt syndic daemon, a special minion that passes through commands from a
higher master
.SH SYNOPSIS
.sp
salt\-syndic [ options ]
.SH DESCRIPTION
.sp
The salt syndic daemon, a special minion that passes through commands from a
The Salt syndic daemon, a special minion that passes through commands from a
higher master.
.SH OPTIONS
.INDENT 0.0
@ -49,7 +49,7 @@ Print a usage message briefly summarizing these command\-line options.
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run the salt syndic as a daemon
Run the Salt syndic as a daemon
.UNINDENT
.INDENT 0.0
.TP

2
doc/ref/cli/index.rst
View file

@ -21,7 +21,7 @@ environment variables ``SALT_MASTER_CONFIG`` and ``SALT_MINION_CONFIG``.
Using the Salt Command
======================
The Salt command needs a few components to send information to the salt
The Salt command needs a few components to send information to the Salt
minions. The target minions need to be defined, the function to call and any
arguments the function requires.

12
doc/ref/cli/salt-call.rst
View file

@ -20,7 +20,7 @@ Options
.. option:: -g, --grains
Return the information generated by the salt grains
Return the information generated by the Salt grains
.. option:: -m MODULE_DIRS, --module-dirs=MODULE_DIRS
@ -29,7 +29,7 @@ Options
.. option:: -d, --doc
Return the documentation for the specified module of for all modules if
Return the documentation for the specified module or for all modules if
none are specified
.. option:: -l LOG_LEVEL, --log-level=LOG_LEVEL
@ -40,9 +40,9 @@ Options
.. option:: --raw-out
Print the output from the salt command in raw python
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.
an executing Python script with eval.
.. option:: --text-out
@ -51,11 +51,11 @@ Options
.. option:: --yaml-out
Print the output from the salt command in yaml.
Print the output from the salt command in YAML.
.. option:: --json-out
Print the output from the salt command in json.
Print the output from the salt command in JSON.
.. option:: --no-color

12
doc/ref/cli/salt-cp.rst
View file

@ -18,7 +18,7 @@ Synopsis
Description
===========
Salt copy copies a local file out to all of the salt minions matched by the
Salt copy copies a local file out to all of the Salt minions matched by the
given target.
Options
@ -32,11 +32,11 @@ Options
.. option:: -t TIMEOUT, --timeout=TIMEOUT
The timeout in seconds to wait for replies from the salt minions.
The timeout in seconds to wait for replies from the Salt minions.
.. option:: -E, --pcre
The target expression will be interpreted as a pcre regular expression
The target expression will be interpreted as a PCRE regular expression
rather than a shell glob.
.. option:: -L, --list
@ -46,13 +46,13 @@ Options
.. option:: -G, --grain
The target expression matches values returned by the salt grains system on
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 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.*'
@ -75,7 +75,7 @@ Options
.. option:: -c CONFIG, --config=CONFIG
The location of the salt master configuration file, the salt master
The location of the Salt master configuration file, the Salt master
settings are required to know where the connections are;
default=/etc/salt/master

6
doc/ref/cli/salt-key.rst
View file

@ -10,7 +10,7 @@ salt-key [ options ]
Description
===========
Salt-key executes simple management of salt server public keys used for
Salt-key executes simple management of Salt server public keys used for
authentication.
Options
@ -28,7 +28,7 @@ Options
.. option:: -L, --list-all
List all public keys on this salt master: accepted, pending,
List all public keys on this Salt master: accepted, pending,
and rejected.
.. option:: -a ACCEPT, --accept=ACCEPT
@ -57,6 +57,6 @@ Options
.. option:: -c CONFIG, --config=CONFIG
The master configuration file needs to be read to determine where the salt
The master configuration file needs to be read to determine where the Salt
keys are stored via the pki_dir configuration value;
default=/etc/salt/master

6
doc/ref/cli/salt-master.rst
View file

@ -2,7 +2,7 @@
``salt-master``
===============
The salt master daemon, used to control the salt minions
The Salt master daemon, used to control the Salt minions
Synopsis
========
@ -12,7 +12,7 @@ salt-master [ options ]
Description
===========
The master daemon controls the salt minions
The master daemon controls the Salt minions
Options
=======
@ -25,7 +25,7 @@ Options
.. option:: -d, --daemon
Run the salt master as a daemon
Run the Salt master as a daemon
.. option:: -c CONFIG, --config=CONFIG

6
doc/ref/cli/salt-minion.rst
View file

@ -2,7 +2,7 @@
``salt-minion``
===============
The salt minion daemon, receives commands from a remote salt master.
The Salt minion daemon, receives commands from a remote Salt master.
Synopsis
========
@ -12,7 +12,7 @@ salt-minion [ options ]
Description
===========
The salt minion receives commands from the central salt master and replies with
The Salt minion receives commands from the central Salt master and replies with
the results of said commands.
Options
@ -26,7 +26,7 @@ Options
.. option:: -d, --daemon
Run the salt minion as a daemon
Run the Salt minion as a daemon
.. option:: -c CONFIG, --config=CONFIG

2
doc/ref/cli/salt-run.rst
View file

@ -29,7 +29,7 @@ Options
.. option:: -c CONFIG, --config=CONFIG
The location of the salt master configuration file, the salt master
The location of the Salt master configuration file, the Salt master
settings are required to know where the connections are;
default=/etc/salt/master

6
doc/ref/cli/salt-syndic.rst
View file

@ -2,7 +2,7 @@
``salt-syndic``
===============
The salt syndic daemon, a special minion that passes through commands from a
The Salt syndic daemon, a special minion that passes through commands from a
higher master
Synopsis
@ -13,7 +13,7 @@ salt-syndic [ options ]
Description
===========
The salt syndic daemon, a special minion that passes through commands from a
The Salt syndic daemon, a special minion that passes through commands from a
higher master.
Options
@ -27,7 +27,7 @@ Options
.. option:: -d, --daemon
Run the salt syndic as a daemon
Run the Salt syndic as a daemon
.. option:: --pid-file PIDFILE

22
doc/ref/cli/salt.rst
View file

@ -33,7 +33,7 @@ Options
.. option:: -t TIMEOUT, --timeout=TIMEOUT
The timeout in seconds to wait for replies from the salt minions.
The timeout in seconds to wait for replies from the Salt minions.
.. option:: -s STATIC, --static=STATIC
@ -51,7 +51,7 @@ Options
.. option:: --version
Print the version of salt that is running.
Print the version of Salt that is running.
.. option:: -E, --pcre
@ -65,7 +65,7 @@ Options
.. option:: -G, --grain
The target expression matches values returned by the salt grains system on
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*'
@ -75,7 +75,7 @@ Options
.. option:: --grain-pcre
The target expression matches values returned by the salt grains system on
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.*'
@ -93,7 +93,7 @@ Options
.. option:: -N, --nodegroup
Use a predefined compound target defined in the salt master configuration
Use a predefined compound target defined in the Salt master configuration
file
.. option:: -R, --range
@ -114,7 +114,7 @@ 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
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
@ -122,15 +122,15 @@ Options
.. option:: -c CONFIG, --config=CONFIG
The location of the salt master configuration file, the salt master
The location of the Salt master configuration file, the Salt master
settings are required to know where the connections are;
default=/etc/salt/master
.. option:: --raw-out
Print the output from the salt command in raw python
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.
an executing Python script with eval.
.. option:: --text-out
@ -139,11 +139,11 @@ Options
.. option:: --yaml-out
Print the output from the salt command in yaml.
Print the output from the salt command in YAML.
.. option:: --json-out
Print the output from the salt command in json.
Print the output from the salt command in JSON.
.. option:: --no-color

7
doc/ref/configuration/master.rst
View file

@ -45,7 +45,7 @@ The network port to set up the publication interface
.. conf_master:: user
``user``
----------------
--------
Default: ``root``
@ -201,7 +201,7 @@ Set additional directories to search for runner modules
Default: ``False``
Set to true to enable cython modules (.pyx files) to be compiled on the fly on
the salt master
the Salt master
.. code-block:: yaml
@ -296,6 +296,7 @@ Default: ``base: [/srv/salt]``
Salt runs a lightweight file server written in zeromq to deliver files to
minions. This file server is built into the master daemon and does not
require a dedicated port.
The file server works on environments passed to the master. Each environment
can have multiple root directories. The subdirectories in the multiple file
roots cannot match, otherwise the downloaded files will not be able to be
@ -524,7 +525,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

38
doc/ref/configuration/minion.rst
View file

@ -37,7 +37,7 @@ The hostname or ipv4 of the master.
Default: ``4506``
The port of the master ret server, this needs to coincide with the ret_port
option on the salt master.
option on the Salt master.
.. code-block:: yaml
@ -46,7 +46,7 @@ option on the salt master.
.. conf_minion:: user
``user``
----------------
--------
Default: ``root``
@ -72,14 +72,14 @@ The directory used to store the minion's public and private keys.
.. conf_minion:: id
``id``
------------
------
Default: hostname (as returned by the Python call: ``socket.getfqdn()``)
Explicitly declare the id for this minion to use, if left commented the id
will be the hostname as returned by the python call: socket.getfqdn()
Since salt uses detached ids it is possible to run multiple minions on the
same machine but with different ids, this can be useful for salt compute
will be the hostname as returned by the Python call: ``socket.getfqdn()``
Since Salt uses detached ids it is possible to run multiple minions on the
same machine but with different ids, this can be useful for Salt compute
clusters.
.. code-block:: yaml
@ -186,7 +186,7 @@ If certain returners should be disabled, this is the place
Default: ``[]``
A list of extra directories to search for salt modules
A list of extra directories to search for Salt modules
.. code-block:: yaml
@ -200,7 +200,7 @@ A list of extra directories to search for salt modules
Default: ``[]``
A list of extra directories to search for salt returners
A list of extra directories to search for Salt returners
.. code-block:: yaml
@ -214,7 +214,7 @@ A list of extra directories to search for salt returners
Default: ``[]``
A list of extra directories to search for salt states
A list of extra directories to search for Salt states
.. code-block:: yaml
@ -229,7 +229,7 @@ A list of extra directories to search for salt states
Default: ``[]``
A list of extra directories to search for salt renderers
A list of extra directories to search for Salt renderers
.. code-block:: yaml
@ -243,8 +243,8 @@ A list of extra directories to search for salt renderers
Default: ``False``
Set this value to true to enable auto loading and compiling of .pyx modules,
This setting requires that gcc and cython are installed on the minion
Set this value to true to enable auto-loading and compiling of ``.pyx`` modules,
This setting requires that ``gcc`` and ``cython`` are installed on the minion
.. code-block:: yaml
@ -275,7 +275,7 @@ Default: ``False``
state_verbose allows for the data returned from the minion to be more
verbose. Normally only states that fail or states that have changes are
returned, but setting state_verbose to True will return all states that
returned, but setting state_verbose to ``True`` will return all states that
were checked
.. code-block:: yaml
@ -291,7 +291,7 @@ Default: ``True``
autoload_dynamic_modules Turns on automatic loading of modules found in the
environments on the master. This is turned on by default, to turn of
autoloading modules when states run set this value to False
autoloading modules when states run set this value to ``False``
.. code-block:: yaml
@ -304,7 +304,7 @@ Default: ``True``
clean_dynamic_modules keeps the dynamic modules on the minion in sync with
the dynamic modules on the master, this means that if a dynamic module is
not on the master it will be deleted from the minion. By default this is
enabled and can be disabled by changing this value to False
enabled and can be disabled by changing this value to ``False``
.. code-block:: yaml
@ -327,7 +327,7 @@ environments is to isolate via the top file.
environment: None
Security Settings
------------------
-----------------
.. conf_minion:: open_mode
@ -336,7 +336,7 @@ Security Settings
Default: ``False``
Open mode can be used to clean out the pki key received from the salt master,
Open mode can be used to clean out the PKI key received from the Salt master,
turn on open mode, restart the minion, then turn off open mode and restart the
minion to clean the keys.
@ -351,7 +351,7 @@ Thread Settings
Default: ``True``
Disable multiprocessing support, by default when a minion receives a
Disable multiprocessing support by default when a minion receives a
publication a new process is spawned and the command is executed therein.
.. code-block:: yaml
@ -396,7 +396,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

4
doc/ref/file_server/dynamic-modules.rst
View file

@ -4,7 +4,7 @@ Dynamic Module Distribution
.. versionadded:: 0.9.5
Salt python modules can be distributed automatically via the salt file server.
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.
@ -17,7 +17,7 @@ The directories are prepended with an underscore:
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
Python modules have been created in them. There are a number of ways to sync
the modules.
Sync Via States

4
doc/ref/file_server/file_roots.rst
View file

@ -43,7 +43,7 @@ are listed. In the case of this ``file_roots`` configuration:
- /srv/salt/base
- /srv/salt/failover
If a file's uri is ``salt://httpd/httpd.conf``, it will first search for the
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.
@ -58,7 +58,7 @@ Local File Server
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
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``

12
doc/ref/file_server/index.rst
View file

@ -3,10 +3,10 @@ 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.
Salt minions. The file server is a stateless ZeroMQ server that is built into
the Salt master.
The main intent of the Salt File server is to present files for use in the
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.
@ -35,7 +35,7 @@ the master, the syntax looks like this:
# salt '*' cp.get_file salt://vimrc /etc/vimrc
This will instruct all salt minions to download the vimrc file and copy it
This will instruct all Salt minions to download the vimrc file and copy it
to /etc/vimrc
File Server Client API
@ -61,7 +61,7 @@ built in ``__opts__`` data can be passed:
def get_file(path, dest, env='base'):
'''
Used to get a single file from the salt master
Used to get a single file from the Salt master
CLI Example:
salt '*' cp.get_file salt://vimrc /etc/vimrc
@ -81,7 +81,7 @@ data is not available, it needs to be generated:
def get_file(path, dest, env='base'):
'''
Used to get a single file from the salt master
Used to get a single file from the Salt master
'''
# Get the configuration data
opts = salt.config.minion_config('/etc/salt/minion')

24
doc/ref/index.rst
View file

@ -14,7 +14,7 @@ so much more.
Client API
----------
The primary interface used to extend salt, is to simply use it. Salt executions
The primary interface used to extend Salt, is to simply use it. Salt executions
can be called via the Salt client api, making programming master side solutions
with Salt is easy.
@ -22,7 +22,7 @@ Adding Loadable Plugins
-----------------------
Salt is comprised of a core platform that loads many types of easy to write
plugins. The idea is to enable all of the breaking points in the salt processes
plugins. The idea is to enable all of the breaking points in the Salt processes
to have a point of pluggable interaction. This means that all of the main
features of Salt can be extended, modified or used.
@ -32,14 +32,14 @@ executions to manipulating the flow of how data is handled by Salt.
Minion Execution Modules
````````````````````````
The minion execution modules or just ``modules`` are the core to what salt is
The minion execution modules or just ``modules`` are the core to what Salt is
and does. These modules are found in:
:blob:`salt/modules`
These modules are what is called by the salt command line and the salt client
api. Adding modules is done by simply adding additional python modules to the
modules directory and restarting the minion.
These modules are what is called by the Salt command line and the salt client
API. Adding modules is done by simply adding additional Python modules to the
*modules* directory and restarting the minion.
Grains
``````
@ -50,7 +50,7 @@ what package manager to default to, or where certain configuration files are
stored on the minion.
The Salt grains are the interface used for auto detection and dynamic assignment
of execution modules and types to specific salt minions.
of execution modules and types to specific Salt minions.
The code used to generate the Salt grains can be found here:
@ -82,10 +82,10 @@ The existing renderers can be found here:
Returners
`````````
The salt commands all produce a return value, that return value is sent to the
salt master by default, but it can be sent anywhere. The returner interface
The Salt commands all produce a return value, that return value is sent to the
Salt master by default, but it can be sent anywhere. The returner interface
makes it programmatically possible for the information to be sent to anything
from an SQL or NOSQL database, to a custom application made to use Salt.
from an SQL or NoSQL database, to a custom application made to use Salt.
The existing returners can be found here:
@ -95,8 +95,8 @@ Runners
```````
Sometimes a certain application can be made to execute and run from the
existing salt command line. This is where the salt runners come into play.
The Salt Runners what is called by the salt-run command and are meant to
existing Salt command line. This is where the Salt runners come into play.
The Salt Runners what is called by the Salt-run command and are meant to
act as a generic interface for encapsulating master side executions.
Existing Salt runners are located here:

69
doc/ref/modules/index.rst
View file

@ -11,30 +11,32 @@ Salt modules are the functions called by the :command:`salt` command.
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. You
Salt modules are amazingly simple to write. Just write a regular Python module
or a regular `Cython`_ module and place it in the ``salt/modules`` directory. You
can also place them in a directory called ``_modules/`` 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
cannot import the Salt minion will continue to load without issue, the module
with errors will simply be omitted.
Since Salt modules are just Python/Cython modules, there are no restraints on
what you can put inside of a Salt module. If a Salt module has errors and
cannot be imported, the Salt minion will continue to load without issue and the
module with errors will simply be omitted.
If adding a Cython module the file must be named ``<modulename>.pyx`` so that
the loader knows that the module needs to be imported as a Cython module. The
compilation of the Cython module is automatic and happens when the minion
starts, so only the ``*.pyx`` file is required.
.. _`Cython`: http://cython.org/
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 which already exist
All of the Salt modules are available to each other, and can be "cross called".
This means that, when creating a module, functions in modules that already exist
can be called.
The variable ``__salt__`` is packed into the modules after they are loaded into
the salt minion. This variable is a python dictionary of all of the salt
functions, laid out in the same way that they are made available to the salt
the Salt minion. This variable is a `Python dictionary`_ of all of the Salt
functions, laid out in the same way that they are made available to the Salt
command.
Salt modules can be cross called by accessing the value in the ``__salt__``
@ -45,9 +47,11 @@ dict:
def foo(bar):
return __salt__['cmd.run'](bar)
This code will call the Salt cmd module's run function and pass the argument
This code will call the Salt cmd module's ``run`` function and pass the argument
``bar``.
.. _`Python dictionary`: http://docs.python.org/library/stdtypes.html#typesmapping
Preloaded Modules Data
======================
@ -62,13 +66,13 @@ 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 OS. This information is referred to as Salt Grains, or "grains of salt".
The Grains system was introduced to replace Facter, since relying on a Ruby
application from a Python application was both slow and inefficient. Grains
support replaces Facter in all releases after 0.8
and operating system. This information is referred to as Salt Grains, or
"grains of salt". The Grains system was introduced to replace Facter, since
relying on a Ruby application from a Python application was both slow and
inefficient. Grains support replaces Facter in all Salt releases after 0.8
The values detected by the Salt Grains on the minion are available in a dict by
the name of ``__grains__`` and can be accessed from within callable objects in
The values detected by the Salt Grains on the minion are available in a `dict`_
named ``__grains__`` and can be accessed from within callable objects in
the Python modules.
To see the contents of the grains dict for a given system in your deployment
@ -82,6 +86,8 @@ 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`.
.. _`dict`: http://docs.python.org/library/stdtypes.html#typesmapping
Module Configuration
--------------------
@ -89,7 +95,7 @@ Since parameters for configuring a module may be desired, Salt allows for
configuration information stored in the main minion config file to be passed to
the modules.
Since the minion configuration file is a yaml document, arbitrary configuration
Since the minion configuration file is a YAML document, arbitrary configuration
data can be passed in the minion config that is read by the modules. It is
**strongly** recommended that the values passed in the configuration file match
the module. This means that a value intended for the ``test`` module should be
@ -127,17 +133,17 @@ Virtual Modules
Sometimes a module should be presented in a generic way. A good example of this
can be found in the package manager modules. The package manager changes from
one operating system to another, but the salt module that interfaces with the
one operating system to another, but the Salt module that interfaces with the
package manager can be presented in a generic way.
The salt modules for package managers all contain a ``__virtual__`` function
The Salt modules for package managers all contain a ``__virtual__`` function
which is called to define what systems the module should be loaded on.
The ``__virtual__`` function is used to return either a string or False. If
The ``__virtual__`` function is used to return either a `string`_ or `False`_. If
False is returned then the module is not loaded, if a string is returned then
the module is loaded with the name of the string.
This means that the package manager modules can be presented as the pkg module
This means that the package manager modules can be presented as the ``pkg`` module
regardless of what the actual module is named.
The package manager modules are the best example of using the ``__virtual__``
@ -146,6 +152,9 @@ function:
:blob:`salt/modules/yumpkg.py`
:blob:`salt/modules/apt.py`
.. _`string`: http://docs.python.org/library/stdtypes.html#typesseq
.. _`False`: http://docs.python.org/library/constants.html#False
Documentation
=============
@ -157,7 +166,7 @@ documentation for all available Facter modules:
salt '*' sys.doc
This function simple prints out the docstrings found in the modules, when
writing salt modules, please follow the formating conventions for docstrings as
writing Salt modules, please follow the formating conventions for docstrings as
they appear in the other modules.
Adding Documentation to Salt Modules
@ -168,7 +177,7 @@ all Salt modules have documentation added. Any Salt modules submitted for
inclusion in the main distribution of Salt will be required to have
documentation.
Documenting Salt modules is easy! Just add a python docstring to the function.
Documenting Salt modules is easy! Just add a `Python docstring`_ to the function.
.. code-block:: python
@ -185,10 +194,12 @@ Documenting Salt modules is easy! Just add a python docstring to the function.
Now when the sys.doc call is executed the docstring will be cleanly returned
to the calling terminal.
.. _`Python docstring`: #term-docstring
How Functions are Read
======================
In Salt Python callable objects contained within a module are made available to
In Salt, Python callable objects contained within a module are made available to
the Salt minion for use. The only exception to this rule is a callable object
with a name starting with an underscore ``_``.
@ -212,21 +223,21 @@ Objects NOT Loaded into the Salt Minion
def _foobar(baz): # Preceded with an _
return baz
cheese = {} # Not a callable python object
cheese = {} # Not a callable Python object
Examples of Salt Modules
========================
The existing Salt modules should be fairly easy to read and understand, the
goal of the main distribution's Salt modules is not only to build a set of
functions for salt, but to stand as examples for building out more Salt
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:
The most simple module is the test module, it contains the simplest Salt
function, ``test.ping``:
.. code-block:: python

14
doc/ref/peer.rst
View file

@ -2,23 +2,23 @@
Peer Communication
==================
Salt 0.9.0 introduced the capability for salt minions to publish commands. The
intent of this feature is not for salt minions to act as independent brokers
one with another, but to allow salt minions to pass commands to each other.
Salt 0.9.0 introduced the capability for Salt minions to publish commands. The
intent of this feature is not for Salt minions to act as independent brokers
one with another, but to allow Salt minions to pass commands to each other.
The peer interface allows a minion to call out publications on the salt master
The peer interface allows a minion to call out publications on the Salt master
and receive the return data.
Since this presents a viable security risk by allowing minions access to the
master publisher the capability is turned off by default. The minions can be
allowed access to the master publisher on a per minion basis based on regular
expressions. Minions with specific ids can be allowed access to certain salt
expressions. Minions with specific ids can be allowed access to certain Salt
modules and functions.
Configuration
=============
The configuration is done under the peer setting in the salt master
The configuration is done under the peer setting in the Salt master
configuration file, here are a number of configuration possibilities.
The simplest approach is to enable all communication for all minions, this is
@ -30,7 +30,7 @@ only recommended for very secure environments.
.*:
- .*
This configuration will allow minions with ids ending in example.com access
This configuration will allow minions with IDs ending in example.com access
to the test, ps, and pkg module functions.
.. code-block:: yaml

14
doc/ref/python-api.rst
View file

@ -16,7 +16,7 @@ Sending information through the client is simple:
.. code-block:: python
# Import the salt client library
# Import the Salt client library
import salt.client
# create a local client object
client = salt.client.LocalClient()
@ -25,7 +25,7 @@ Sending information through the client is simple:
The LocalClient object only works running as root on the salt-master, it is the
same interface used by the salt command line tool.
same interface used by the ``salt`` command line tool.
.. function:: LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form='glob', ret='')
@ -36,7 +36,7 @@ same interface used by the salt command line tool.
The tgt option is the target specification, by default a target is passed
in as a bash shell glob. The expr_form option allows the tgt to be passed
as either a pcre regular expression or as a python list.
as either a pcre regular expression or as a Python list.
.. cmdoption:: fun
@ -77,7 +77,7 @@ same interface used by the salt command line tool.
The tgt option is the target specification, by default a target is passed
in as a bash shell glob. The expr_form option allows the tgt to be passed
as either a pcre regular expression or as a python list.
as either a pcre regular expression or as a Python list.
.. cmdoption:: fun
@ -121,7 +121,7 @@ same interface used by the salt command line tool.
The tgt option is the target specification, by default a target is passed
in as a bash shell glob. The expr_form option allows the tgt to be passed
as either a pcre regular expression or as a python list.
as either a pcre regular expression or as a Python list.
.. cmdoption:: fun
@ -162,7 +162,7 @@ same interface used by the salt command line tool.
The tgt option is the target specification, by default a target is passed
in as a bash shell glob. The expr_form option allows the tgt to be passed
as either a pcre regular expression or as a python list.
as either a pcre regular expression or as a Python list.
.. cmdoption:: fun
@ -216,7 +216,7 @@ All client command methods can execute compound commands.
.. code-block:: python
# Import the salt client library
# Import the Salt client library
import salt.client
# create a local client object
client = salt.client.LocalClient()

22
doc/ref/renderers/index.rst
View file

@ -4,15 +4,15 @@ 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
it generic and simple. This also means that state files (SLS files) can be one
of many formats.
By default sls files are rendered as jinja templates and then parsed as yaml
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.
the SLS files can be any structured format that can be dreamed up.
Currently there is support for ``jinja + yaml``, ``mako + yaml``,
``jinja + json`` and ``mako + json``. But renderers can be written to support
Currently there is support for ``Jinja + YAML``, ``Mako + YAML``,
``Jinja + json`` and ``Mako + 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.
@ -24,13 +24,13 @@ When deploying a state tree a default renderer is selected in the master
configuration file with the renderer option. But multiple renderers can be
used inside the same state tree.
When rendering sls files Salt checks for the presence of a salt specific
When rendering SLS files Salt checks for the presence of a Salt specific
shebang line. The shebang line syntax was chosen because it is familiar to
the target audience, the systems admin and systems engineer.
The shebang line directly calls the name of the renderer as it is specified
within Salt. One of the most common reasons to use multiple renderers in to
use the python or ``py`` renderer:
use the Python or ``py`` renderer:
.. code-block:: python
@ -49,9 +49,9 @@ The first line is a shebang that references the ``py`` renderer.
Writing Renderers
-----------------
Writing a renderer is easy, all that is required is that a python module
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.
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.
@ -63,11 +63,11 @@ renderers included with Salt can be found here:
:blob:`salt/renderers`
Here is a simple jinja + yaml example:
Here is a simple Jinja + YAML example:
.. code-block:: python
# Import python libs
# Import Python libs
import os
# Import Third Party libs

12
doc/ref/returners/index.rst
View file

@ -2,13 +2,13 @@
Returners
=========
By default the return values of the commands sent to the salt minions are
returned to the salt-master. But since the commands executed on the salt
minions are detached from the call on the salt master, there is no need for
the minion to return the data to the salt master.
By default the return values of the commands sent to the Salt minions are
returned to the salt-master. But since the commands executed on the Salt
minions are detached from the call on the Salt master, there is no need for
the minion to return the data to the Salt master.
This is where the returner interface comes in. Returners are modules called
in place of returning the data to the salt master.
in place of returning the data to the Salt master.
The returner interface allows the return data to be sent to any system that
can receive data. This means that return data can be sent to a Redis server,
@ -75,5 +75,5 @@ serializes the data as json and sets it in redis.
Examples
--------
The collection of built-in salt returners can be found here:
The collection of built-in Salt returners can be found here:
:blob:`salt/returners`

16
doc/ref/runners.rst
View file

@ -1,13 +1,13 @@
=================
============
Salt Runners
=================
============
Salt runners are convenience applications executed with the salt-run command.
A Salt runner can be a simple client call, or a complex application.
The use for a salt running is to build a frontend hook for running sets of
commands via salt or creating special formatted output.
The use for a Salt runner is to build a frontend hook for running sets of
commands via Salt or creating special formatted output.
Writing Salt Runners
--------------------
@ -15,10 +15,10 @@ Writing Salt Runners
Salt runners can be easily written, the work in a similar way to Salt modules
except they run on the server side.
A runner is a python module that contains functions, each public function is
a runner that can be executed via the salt-run command.
A runner is a Python module that contains functions, each public function is
a runner that can be executed via the *salt-run* command.
If a python module named test.py is created in the runners directory and
If a Python module named test.py is created in the runners directory and
contains a function called ``foo`` then the function could be called with:
.. code-block:: bash
@ -33,7 +33,7 @@ The best examples of runners can be found in the Salt source:
: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 would look like this:
.. code-block:: python

8
doc/ref/states/extend.rst
View file

@ -35,7 +35,7 @@ this:
- managed
- source: salt://ssh/banner
A few critical things happened here, first off the sls files that are going to
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
@ -44,7 +44,7 @@ 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
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
@ -66,9 +66,9 @@ 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
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
declared twice in a single SLS
4. Many IDs can be extended under the extend declaration

16
doc/ref/states/highstate.rst
View file

@ -18,9 +18,9 @@ The Salt State Tree
.. glossary::
State tree
A collection of ``sls`` files that live under the directory specified
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`.
``SLS modules``.
Include declaration
-------------------
@ -29,7 +29,7 @@ Include declaration
Include declaration
Defines a list of :term:`module reference` strings to include in this
:term:`sls`.
:term:`SLS`.
Occurs only in the top level of the highstate structure.
@ -48,7 +48,7 @@ Module reference
Module reference
The name of a SLS module defined by a separate SLS file and residing on
the Salt Master. A module named ``edit.vim`` is a reference to the sls
the Salt Master. A module named ``edit.vim`` is a reference to the SLS
file ``salt://edit/vim.sls``.
ID declaration
@ -80,15 +80,15 @@ Extend declaration
.. glossary::
Extend declaration
Extends a :term:`name declaration` from an included ``sls module``. The
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``.
``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
:term:`state declaration` that is defined in another ``SLS`` file. In the
following contrived example, the shown ``mywebsite.sls`` file is ``include``
-ing and ``extend`` -ing the ``apache.sls`` module in order to add a ``watch``
declaration that will restart Apache whenever the Apache configuration file,
@ -276,7 +276,7 @@ For example, given the following state declaration:
- python-crypto
- python-yaml
Once converted into the :term:`lowstate` data structure the above state
Once converted into the lowstate data structure the above state
declaration will be expanded into the following three state declarations:
.. code-block:: yaml

30
doc/ref/states/index.rst
View file

@ -3,7 +3,7 @@ State Enforcement
=================
Salt offers an optional interface to manage the configuration or "state" of the
salt minions. This interface is a fully capable mechanism used to enforce the
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
@ -30,8 +30,8 @@ Understanding the Salt State System Components
==============================================
The Salt state system is comprised of a number of components. As a user, an
understanding of the sls and renderer systems are needed. But as a developer,
an understanding of salt states and how to write the states is needed as well.
understanding of the SLS and renderer systems are needed. But as a developer,
an understanding of Salt states and how to write the states is needed as well.
@ -40,12 +40,12 @@ Salt SLS System
.. glossary::
sls
SLS
The primary system used by the Salt state system is the SLS system. SLS
stands for **S**\ a\ **L**\ t **S**\ tate.
The Salt States are files which contain the information about how to
configure salt minions. The states are laid out in a directory tree and
configure Salt minions. The states are laid out in a directory tree and
can be written in many different formats.
The contents of the files and they way they are laid out is intended to
@ -70,8 +70,8 @@ this:
salt/master.sls
This example shows the core concepts of file layout. The top file is a key
component and is used with salt matchers to match SLS states with minions.
The ``.sls`` files are states. The rest of the files are seen by the salt
component and is used with Salt matchers to match SLS states with minions.
The ``.sls`` files are states. The rest of the files are seen by the Salt
master as just files that can be downloaded.
The states are translated into dot notation, so the ``ssh.sls`` file is
@ -79,10 +79,10 @@ seen as the ssh state, the ``users/admin.sls`` file is seen as the
users.admin states.
The init.sls files are translated to be the state name of the parent
directory, so the ``salt/init.sls`` file translates to the salt state.
directory, so the ``salt/init.sls`` file translates to the Salt state.
The plain files are visible to the minions, as well as the state files. In
salt, everything is a file; there is no "magic translation" of files and file
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.
@ -132,7 +132,7 @@ Here is an example of a Salt State:
- require:
- pkg: salt
This short stanza will ensure that vim is installed, salt is installed and up
This short stanza will ensure that vim is installed, Salt is installed and up
to date, the salt-master and salt-minion daemons are running and the Salt
minion configuration file is in place. It will also ensure everything is
deployed in the right order and that the Salt services are restarted when the
@ -160,7 +160,7 @@ lists of Salt states sent to the matching minions:
- 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
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.
@ -170,10 +170,10 @@ 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.
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
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
@ -181,9 +181,9 @@ source code:
:blob:`salt/renderers`
By default sls files are rendered using jinja as a templating engine, and yaml
By default SLS files are rendered using jinja as a templating engine, and yaml
as the serialization format. Since the rendering system can be extended simply
by adding a new renderer to the renderers directory, it is possible that any
structured file could be used to represent the SLS files.
In the future xml and raw python will be added, as well as many other formats.
In the future xml and raw Python will be added, as well as many other formats.

4
doc/ref/states/ordering.rst
View file

@ -2,7 +2,7 @@
Ordering States
===============
When creating salt sls files, it is often important to ensure that they run in
When creating Salt SLS files, it is often important to ensure that they run in
a specific order. While states will always execute in the same order, that
order is not necessarily defined the way you want it.
@ -149,7 +149,7 @@ restarted.
Watch and the Watcher Function
------------------------------
The watch requisite is based on the ``watcher`` function, state python
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.

8
doc/ref/states/providers.rst
View file

@ -1,4 +1,4 @@
===============
*===============
State Providers
===============
@ -26,7 +26,7 @@ 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
@ -41,7 +41,7 @@ module can be used to provide certain functionality.
- 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
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.

8
doc/ref/states/top.rst
View file

@ -2,7 +2,7 @@
The Top File
============
The top file is used to map what sls modules get loaded onto what minions via
The top file is used to map what SLS modules get loaded onto what minions via
the state system. The top file creates a few general abstractions. First it
maps what nodes should pull from which environments, next it defines which
matches systems should draw from.
@ -95,10 +95,10 @@ it suits your deployment:
'db*prod*':
- db
In this setup all systems will pull the global sls from the base environment,
In this setup all systems will pull the global SLS from the base environment,
as well as pull from their respective environments.
Remember, that since everything is a file in salt, the environments are
Remember, that since everything is a file in Salt, the environments are
primarily file server environments, this means that environments that have
nothing to do with states can be defined and used to distribute other files.
@ -141,7 +141,7 @@ would look something like this:
- db
Other Ways of Targeting Minions
================================
===============================
In addition to globs, minions can be specified in top files a few other
ways. Some common ones are :doc:`compound matches </topics/targeting/compound>`

4
doc/ref/states/writing.rst
View file

@ -3,10 +3,10 @@ State Modules
=============
State Modules are the components that map to actual enforcement and management
of salt states.
of Salt states.
States are - Easy to Write!
============================
===========================
State Modules should be easy to write and straightforward. The information
passed to the SLS data structures will map directly to the states modules.

2
doc/topics/configuration.rst
View file

@ -66,7 +66,7 @@ Salt manages authentication with RSA public keys. The keys are managed on the
checks into the master the master will save a copy of the minion key. Before
the master can send commands to the minion the key needs to be "accepted".
1. List the accepted and unaccepted salt keys::
1. List the accepted and unaccepted Salt keys::
salt-key -L

13
doc/topics/index.rst
View file

@ -9,10 +9,10 @@ Distributed remote execution
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.
world of remote execution together and make them better, faster, and more
malleable. Salt accomplishes this through its ability to handle large loads of
information, and not just dozens but hundreds and even thousands of individual
servers quickly through a simple and manageable interface.
Simplicity
==========
@ -21,7 +21,7 @@ Versatility between massive scale deployments and smaller systems may seem
daunting, but Salt is very simple to set up and maintain, regardless of the
size of the project. The architecture of Salt is designed to work with any
number of servers, from a handful of local network systems to international
deployments across disparate datacenters. The topology is a simple
deployments across different datacenters. The topology is a simple
server/client model with the needed functionality built into a single set of
daemons. While the default configuration will work with little to no
modification, Salt can be fine tuned to meet specific needs.
@ -42,13 +42,14 @@ 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
public keys for authentication with the master daemon, then uses faster AES
public keys for authentication with the master daemon, then uses faster `AES`_
encryption for payload communication, this means that authentication and
encryption are also built into Salt. Salt takes advantage of communication via
`msgpack`_, enabling fast and light network traffic.
.. _`ZeroMQ`: http://www.zeromq.org/
.. _`msgpack`: http://msgpack.org/
.. _`AES`: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
Python client interface
=======================

8
doc/topics/installation/arch.rst
View file

@ -113,7 +113,7 @@ configuration paths.
**Interface**
By default the Salt master listens on ports 4505 and 4506 on all interfaces
By default the Salt master listens on TCP 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:
@ -124,7 +124,7 @@ By default the Salt master listens on ports 4505 and 4506 on all interfaces
**rc.conf**
You'll need to activate the Salt Master in your rc.conf file. Using your
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
@ -197,7 +197,7 @@ 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
@ -263,7 +263,7 @@ the ``test.ping`` remote command:
{'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

12
doc/topics/installation/debian.rst
View file

@ -22,7 +22,7 @@ After installation you'll need to make a few changes to the configuration files.
Configuration
=============
To configure your salt files we must modify both master and minion
To configure your Salt files we must modify both master and minion
configuration files. We need to set where the master binds, by default salt
listens on all interfaces. If you have a need to bind to a specific local IP,
make the change as needed. To edit the master type in the following command:
@ -62,7 +62,7 @@ minion. To do so type in the following commands:
Test
====
To test salt we must first sign the key of the minion to the master. To see the
To test Salt we must first sign the key of the minion to the master. To see the
pending keys type in the following command:
.. code-block:: bash
@ -98,7 +98,7 @@ If it is working properly you should see this result:
Troubleshooting
===============
To see if the master is running properly type in the following command:
To see if the Salt master is running properly type in the following command:
.. code-block:: bash
@ -115,14 +115,14 @@ command:
ps -efH | grep sal[t]
This should return 8 salt masters and 1 salt minion if both are configured
properly. If you are still having issues with your salt configuration please
This should return 8 Salt masters and 1 Salt minion if both are configured
properly. If you are still having issues with your Salt configuration please
reference the trouble shooting page :doc:`Troubleshooting</topics/troubleshooting/index>`.
What Now?
=========
Congratulations you have just successfully setup salt on your Ubuntu machine
Congratulations you have just successfully installed Salt on your Ubuntu machine
and configured both the master and the minion. From this point you are now
able to send remote commands. Depending on the primary way you want to
manage your machines you may either want to visit the section regarding Salt

12
doc/topics/installation/fedora.rst
View file

@ -3,7 +3,7 @@ Fedora & CentOS / Enterprise Linux
==================================
Beginning with version 0.9.4, Salt has been available in the primary Fedora
repositories and EPEL. It is installable using yum. Fedora will have more
repositories and `EPEL`_. It is installable using yum. Fedora will have more
up to date versions of Salt than other members of the Red Hat family, which
makes it a great place to help improve Salt!
@ -21,6 +21,8 @@ makes it a great place to help improve Salt!
"RHEL Server Optional Channel". Verify this repository is enabled before
installing salt on RHEL6.
.. _`EPEL`: http://fedoraproject.org/wiki/EPEL
Installation
============
@ -54,7 +56,7 @@ configuration paths.
**Interface**
By default the Salt master listens on ports ``4505`` and ``4506`` on all interfaces
By default the Salt master listens on TCP 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:
@ -65,7 +67,7 @@ By default the Salt master listens on ports ``4505`` and ``4506`` on all interfa
**Enable the Master**
You'll also likely want to activate the Salt Master in systemd, configuring the
You'll also likely want to activate the Salt Master in *systemd*, configuring the
Salt Master to start automatically at boot.
.. code-block:: bash
@ -135,7 +137,7 @@ 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
@ -201,7 +203,7 @@ the ``test.ping`` remote command:
{'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

6
doc/topics/installation/freebsd.rst
View file

@ -133,7 +133,7 @@ file. Using your favorite editor open ``/etc/rc.conf`` or
+ 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
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.
@ -146,7 +146,7 @@ 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
@ -210,7 +210,7 @@ the ``test.ping`` remote command. ::
{'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

4
doc/topics/installation/windows.rst
View file

@ -18,7 +18,7 @@ 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
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.
@ -68,7 +68,7 @@ Install on Windows XP 32bit
13. Add c:\\python27\\scripts to your path
14. Close terminal window and open a new terminal window (cmd)
14. Close terminal window and open a new terminal window (*cmd*)
15. Install jinja2

12
doc/topics/jobs/index.rst
View file

@ -5,17 +5,17 @@ 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
manage jobs running on many systems. As of Salt 0.9.7, the capability was
added for more advanced job management.
The Minion proc System
======================
The Salt Minions now maintain a proc directory in the salt cachedir, the proc
directory maintains files named after the executed job id. These files contain
The Salt Minions now maintain a *proc* directory in the Salt cachedir, the *proc*
directory maintains files named after the executed job ID. These files contain
the information about the current running jobs on the minion and allow for
jobs to be looked up. This is located in the proc directory under the
cachedir, with a default configuration it is under /var/cache/salt/proc.
jobs to be looked up. This is located in the *proc* directory under the
cachedir, with a default configuration it is under */var/cache/salt/proc*.
Functions in the saltutil Module
================================
@ -25,7 +25,7 @@ Salt 0.9.7 introduced a few new functions to the
jobs. These functions are:
1. ``running``
Returns the data of all running jobs that are found in the proc directory.
Returns the data of all running jobs that are found in the *proc* directory.
2. ``find_job``
Returns specific data about a certain job based on job id.

12
doc/topics/pillar/index.rst
View file

@ -2,9 +2,9 @@
Pillar of Salt
==============
Pillar is an interface for Salt designed to offer global values to be
Pillar is an interface for Salt designed to offer global values that can be
distributed to all minions. Pillar data is managed in a similar way to
the salt state tree.
the Salt State Tree.
Pillar was added to Salt in version 0.9.8 as an experimental add on.
@ -29,7 +29,7 @@ behavior and function as the ``file_roots`` configuration:
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:
used for States, and has the same structure:
``/srv/pillar/top.sls``
@ -65,8 +65,8 @@ for one special minion.
somekey: specialvalue
Now this data can be used from within modules, renderers, state sls files and
more via the shared pillar dict:
Now this data can be used from within modules, renderers, State SLS files, and
more via the shared pillar `dict`_:
.. code-block:: yaml
@ -111,6 +111,8 @@ this:
on 'someminion':
somekey has value: {{ pillar['somekey'] }}
.. _`dict`: http://docs.python.org/library/stdtypes.html#mapping-types-dict
Footnotes
---------

2
doc/topics/releases/0.6.0.rst
View file

@ -32,7 +32,7 @@ detach the execution from the calling process on the master, it also means that
replies are cached, so that information gathered from historic commands can be
queried in the future.
Salt also allows users to make execution modules in python. Writers of these
Salt also allows users to make execution modules in Python. Writers of these
modules should also be pleased to know that they have access to the impressive
information gathered from PuppetLabs' Facter application, making Salt module
more flexible. In the future I hope to also allow Salt to group servers based

22
doc/topics/releases/0.8.0.rst
View file

@ -20,7 +20,7 @@ Dynamic returners
Faster return handling
Lowered required python version to 2.6
Lowered required Python version to 2.6
Advanced minion threading
@ -43,8 +43,8 @@ the functionality will much more closely resemble the cp command.
Cython minion modules -
========================
Cython is an amazing tool used to compile python modules down to c. This is
arguably the fastest way to run python code, and since pyzmq requires cython,
Cython is an amazing tool used to compile Python modules down to c. This is
arguably the fastest way to run Python code, and since pyzmq requires cython,
adding support to salt for cython adds no new dependencies.
Cython minion modules allow minion modules to be written in cython and
@ -71,7 +71,7 @@ There are 2 simple stock returners in the returners directory:
:blob:`salt/returners`
The documentation on writing returners will be added to the wiki shortly, and
returners can be written in pure python, or in cython.
returners can be written in pure Python, or in cython.
Configurable Minion Modules -
==============================
@ -90,22 +90,22 @@ default options:
Advanced Minion Threading:
==============================
In 0.7.0 the minion would block after receiving a command from the master, now
the minion will spawn a thread or multiprocess. By default python threads are
the minion will spawn a thread or multiprocess. By default Python threads are
used because for general use they have proved to be faster, but the minion can
now be configured to use the python multiprocessing module instead. Using
now be configured to use the Python multiprocessing module instead. Using
multiprocessing will cause executions that are cpu bound or would otherwise
exploit the negative aspects of the Python GIL to run faster and more reliably,
but simple calls will still be faster with python threading.
but simple calls will still be faster with Python threading.
The configuration option can be found in the minion configuration file:
:blob:`conf/minion`
Lowered Supported Python to 2.6 -
The requirement for python 2.7 has been removed to support python 2.6. I have
received requests to take the minimum python version back to 2.4, but
unfortunately this will not be possible, since the zeromq python bindings do
not support python 2.4.
The requirement for Python 2.7 has been removed to support Python 2.6. I have
received requests to take the minimum Python version back to 2.4, but
unfortunately this will not be possible, since the zeromq Python bindings do
not support Python 2.4.
Salt 0.8.0 is a very major update, it also changes the network protocol slightly
which makes communication with older salt daemons impossible, your master and

2
doc/topics/releases/0.9.2.rst
View file

@ -10,7 +10,7 @@ git repo is growing with example of how to use states.
This release introduces salt states for early developers and testers to start
helping us clean up the states interface and make it ready for the world!
0.9.2 also fixes a number of bugs found on python 2.6.
0.9.2 also fixes a number of bugs found on Python 2.6.
Download!
---------

6
doc/topics/releases/0.9.3.rst
View file

@ -106,7 +106,7 @@ Python State Renderer
Until now Salt States could only be declared in yaml or json using jinja or
mako. A new, very powerful, renderer has been added, making it possible to
write Salt States in pure python:
write Salt States in pure Python:
.. code-block:: python
@ -120,9 +120,9 @@ write Salt States in pure python:
'python-mako': {'pkg': ['installed']}}
This renderer is used by making a run function that returns the Highstate data
structure. Any capabilities of python can be used in pure python sls modules.
structure. Any capabilities of Python can be used in pure Python sls modules.
This example of a pure python sls module is the same as this example in yaml:
This example of a pure Python sls module is the same as this example in yaml:
.. code-block:: yaml

14
doc/topics/releases/0.9.5.rst
View file

@ -69,13 +69,13 @@ Major Features
SPEED! Pickle to msgpack
------------------------
For a few months now we have been talking about moving away from python
For a few months now we have been talking about moving away from Python
pickles for network serialization, but a preferred serialization format
had not yet been found. After an extensive performance testing period
involving everything from JSON to protocol buffers, a clear winner emerged.
Message Pack (http://msgpack.org/) proved to not only be the fastest and most
compact, but also the most "salt like". Message Pack is simple, and the code
involved is very small. The msgpack library for python has been added directly
involved is very small. The msgpack library for Python has been added directly
to Salt.
This move introduces a few changes to Salt. First off, Salt is no longer a
@ -229,7 +229,7 @@ Salt -Q is Useful Now
---------------------
In the past the salt query system, which would display the data from recent
executions would be displayed in pure python, and it was unreadable.
executions would be displayed in pure Python, and it was unreadable.
0.9.5 has added the outputter system to the ``-Q`` option, thus enabling the
salt query system to return readable output.
@ -346,7 +346,7 @@ init system are supported on systems running systemd.
:mod:`virtualenv <salt.modules.virtualenv>`
```````````````````````````````````````````
The virtualenv module has been added to allow salt to create virtual python
The virtualenv module has been added to allow salt to create virtual Python
environments.
Thanks goes to whitinge for the addition of the virtualenv module
@ -368,8 +368,8 @@ Salt can now manage local users on Microsoft Windows Systems
`````````````````````````````````````
The yumpkg module introduces in 0.9.4 uses the yum api to interact with the
yum package manager. Unfortunately, on Red Hat 5 systems salt does not have
access to the yum api because the yum api is running under python 2.4 and Salt
needs to run under python 2.6.
access to the yum api because the yum api is running under Python 2.4 and Salt
needs to run under Python 2.6.
The yumpkg5 module bypasses this issue by shelling out to yum on systems where
the yum api is not available.
@ -390,7 +390,7 @@ The mysql_user state enables mysql user management.
:mod:`virtualenv <salt.states.virtualenv>`
``````````````````````````````````````````
The virtualenv state can manage the state of python virtual environments.
The virtualenv state can manage the state of Python virtual environments.
Thanks to Whitinge for the virtualenv state
New Returners

2
doc/topics/releases/0.9.6.rst
View file

@ -42,6 +42,6 @@ returns. By default cache_jobs is set to False.
Pure Python Template Support For file.managed
---------------------------------------------
Templates in the file.managed state can now be defined in a python script.
Templates in the file.managed state can now be defined in a Python script.
This script needs to have a run function that returns the string that needs to
be in the named file.

2
doc/topics/specs/salt_auth_proto_abs.rst
View file

@ -16,7 +16,7 @@ The header is always clear, and specifies the encryption used by the load. The
load can be encrypted with the private key of the sending system, or with the
shared, rotating, AES key.
The message itself is abstracted as a python dict in this fashion:
The message itself is abstracted as a Python dict in this fashion:
.. code-block:: python

9
doc/topics/targeting/compound.rst
View file

@ -9,7 +9,7 @@ Compound matchers
boolean operators.
Compound matchers allow very granular minion targeting using any of the
previously discussed matchers. The default matcher is a glob, as usual. For
previously discussed matchers. The default matcher is a `glob`_, as usual. For
matching via anything other than glob, preface it with the letter denoting
the match type. The currently implemented "letters" are:
@ -18,7 +18,7 @@ Letter Meaning Example
====== ==================== ===============================================================
G Grains glob match ``G@os:Ubuntu``
E PCRE Minion id match ``E@web\d+\.(dev|qa|prod)\.loc``
P Grains pcre match ``P@os:(RedHat|Fedora|CentOS)``
P Grains PCRE match ``P@os:(RedHat|Fedora|CentOS)``
L List of minions ``L@minion1.example.com,minion3.domain.com and bl*.domain.com``
====== ==================== ===============================================================
@ -26,7 +26,7 @@ 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
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
@ -37,3 +37,6 @@ That same example expressed in a :term:`top file` looks like the following::
'webserv* and G@os:Debian or E@web-dc1-srv.*':
- match: compound
- webserver
.. _`glob`: http://docs.python.org/library/fnmatch.html
.. _`regular expressions`: http://docs.python.org/library/re.html#module-re

18
doc/topics/targeting/globbing.rst
View file

@ -22,7 +22,7 @@ configuration setting.
Globbing
========
The default matching that Salt utilizes is shell-style globbing around the
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::
@ -51,19 +51,21 @@ Match the ``web1`` through ``web5`` minions::
Match the ``web-x``, ``web-y``, and ``web-z`` minions::
salt 'web-[x-z]' test.ping
.. _`shell-style globbing`: http://docs.python.org/library/fnmatch.html
Regex
=====
Regular Expressions
===================
Minions can be matched using Perl-compatible regular expressions (which is
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
When using regular expressions in a State's :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
@ -72,10 +74,12 @@ the first option. The following example executes the contents of
'web1-(prod|devel)':
- match: pcre
- webserver
.. _`regular expressions`: http://docs.python.org/library/re.html#module-re
Lists
=====
At the most basic you can specify a flat list of minion ids::
At the most basic level, you can specify a flat list of minion IDs::
salt -L 'web1,web2,web3' test.ping

12
doc/topics/targeting/grains.rst
View file

@ -20,7 +20,7 @@ Match all CentOS minions::
salt -G 'os:CentOS' test.ping
Match all minions with 64 bit CPUs and return number of available cores::
Match all minions with 64-bit CPUs and return number of available cores::
salt -G 'cpuarch:x86_64' grains.item num_cpus
@ -41,7 +41,7 @@ Just add the option ``grains`` and pass options to it:
cab_u: 14-15
Then status data specific to your servers can be retrieved via Salt, or used
inside of the state system for matching. It also makes targeting, in the case
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
@ -50,18 +50,20 @@ 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
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
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.
.. _`dict`: http://docs.python.org/library/stdtypes.html#typesmapping
Examples of Grains
------------------
The core module in the grains package is where the main grains are loaded by
the salt minion and the principal example of how to write grains:
the Salt minion and provides the principal example of how to write grains:
:blob:`salt/grains/core.py`

2
doc/topics/targeting/index.rst
View file

@ -13,7 +13,7 @@ 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
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

2
doc/topics/targeting/nodegroups.rst
View file

@ -6,7 +6,7 @@ Node groups
Node group
A predefined group of minions declared in the master configuration file
:conf_master:`nodegroups` setting as a :term:`compound target`.
:conf_master:`nodegroups` setting as a compound target.
For example, in the master config file :conf_master:`nodegroups` setting::

62
doc/topics/troubleshooting/index.rst
View file

@ -2,9 +2,9 @@
Troubleshooting
===============
The intent of the troubleshooting section is to introduce solutions to a
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.
to aid in developing States and Salt code.
Running in the Foreground
=========================
@ -18,16 +18,19 @@ master in the foreground:
# salt-master -l debug
# salt-minion -l debug
Anyone wanting to run salt daemons via a process supervisor such as monit,
runit, or supervisord, should omit the ``-d`` argument to the daemons and
Anyone wanting to run Salt daemons via a process supervisor such as `monit`_,
`runit`_, or `supervisord`_, should omit the ``-d`` argument to the daemons and
run them in the foreground.
.. _`monit`: http://mmonit.com/monit/
.. _`runit`: http://smarden.org/runit/
.. _`supervisord`: http://supervisord.org/
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
No ports need to be opened up on each minion. For the master, TCP ports 4505
and 4506 need to be open. If you've put both your Salt master and minion in
debug mode and don't see an acknowledgement that your minion has connected,
it could very well be a firewall.
@ -41,23 +44,27 @@ You can check port connectivity from the minion with the nc command:
There is also a :doc:`firewall configuration</topics/tutorials/firewall>`
document that might help as well.
If you've enabled the right ports on your operating system or Linux
If you've enabled the right TCP ports on your operating system or Linux
distribution's firewall and still aren't seeing connections, check that no
additional access control such as SELinux or AppArmor are blocking salt.
additional access control system such as `SELinux`_ or `AppArmor`_ is blocking
Salt.
.. _`SELinux`: https://en.wikipedia.org/wiki/Security-Enhanced_Linux
.. _`AppArmor`: http://wiki.apparmor.net/index.php/Main_Page
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 running any
salt module locally on a minion. These range from the original intent of
salt-call, development assistance, to gathering more verbose output from calls
like :doc:`state.highstate</ref/modules/all/salt.modules.state>`.
of new Salt modules. Since then, many applications have been developed for
running any Salt module locally on a minion. These range from the original
intent of salt-call, development assistance, to gathering more verbose output
from calls like :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. For even more
When developing the State Tree it is generally recommended to invoke
state.highstate with salt-call. This displays far more information
about the highstate execution than calling it remotely. For even more
verbosity, increase the loglevel with the same argument as ``salt-minion``:
.. code-block:: sh
@ -69,7 +76,7 @@ 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
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
@ -96,10 +103,10 @@ 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
There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the
Salt master to not respond properly. If you're running a ZeroMQ version greater
than or equal to 2.1.9, you can work around the bug by setting the sysctls
``net.core.rmem_max`` and ``net.core.wmem_max`` to 16777216. Next, set the third
field in ``net.ipv4.tcp_rmem`` and ``net.ipv4.tcp_wmem`` to at least 16777216.
You can do it manually with something like:
@ -111,7 +118,7 @@ You can do it manually with something like:
# 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:
Or with the following Salt state:
.. code-block:: yaml
:linenos:
@ -139,14 +146,17 @@ Or with the following salt state:
Red Hat Enterprise Linux 5
==========================
Salt requires Python 2.6 or 2.7. RHEL 5 and variants come with python 2.4 by
default, when installing on RHEL 5 from the EPEL repository this is handled
for you. But if running Salt from git, be advised that the deps needs to be
installed from EPEL and salt needs to be run with the ``python26`` executable.
Salt requires Python 2.6 or 2.7. Red Hat Enterprise Linux 5 and its variants
come with Python 2.4 installed by default. When installing on RHEL 5 from the
`EPEL repository`_ this is handled for you. But, if you run Salt from git, be
advised that its dependencies need to be installed from EPEL and that Salt
needs to be run with the ``python26`` executable.
.. _`EPEL repository`: http://fedoraproject.org/wiki/EPEL
Common YAML Gotchas
===================
An extensive list of
:doc:`yaml idiosyncrasies</topics/troubleshooting/yaml_idiosyncrasies>`
:doc:`YAML idiosyncrasies</topics/troubleshooting/yaml_idiosyncrasies>`
has been compiled.

34
doc/topics/troubleshooting/yaml_idiosyncrasies.rst
View file

@ -3,34 +3,38 @@ 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
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.
.. _`YAML`: http://yaml.org/spec/1.1/
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
`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``.
.. _`YAML uses spaces`: http://yaml.org/spec/1.1/#id871998
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
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:
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
@ -69,10 +73,12 @@ is not desirable, then a deeply nested dict can be declared with curly braces:
custom_var: "default value",
other_var: 123 }
.. _`dicts`: http://docs.python.org/library/stdtypes.html#dict
Integers are Parsed as Integers
===============================
When passing integers into an sls file, they are passed as integers. This means
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.
@ -102,11 +108,13 @@ preceded by a 0 then it needs to be passed as a string:
- user: root
- group: root
- mode: '0644'
.. _`integers`: http://docs.python.org/library/functions.html#int
Yaml does not like "Double Short Decs"
YAML does not like "Double Short Decs"
======================================
If I can find a way to make yaml accept "Double Short Decs" then I will, since
If I can find a way to make YAML accept "Double Short Decs" then I will, since
I think that double short decs would be awesome. So what is a "Double Short
Dec"? It is when you declare a multiple short decs in one ID. Here is a
standard short dec, it works great:
@ -119,7 +127,7 @@ standard short dec, it works great:
The short dec means that there are no arguments to pass, so it is not required
to add any arguments, and it can save space.
Yaml though, gets upset when declaring multiple short decs, for the record...
YAML though, gets upset when declaring multiple short decs, for the record...
THIS DOES NOT WORK:

16
doc/topics/tutorials/bootstrap_ec2.rst
View file

@ -5,11 +5,11 @@ 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.
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``
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:
@ -34,7 +34,10 @@ Here is a sample script::
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.
that resolves to your Salt master.
.. _ `AMI`: https://en.wikipedia.org/wiki/Amazon_Machine_Image
.. _ `EC2 Instance`: http://aws.amazon.com/ec2/instance-types/
Used With Boto
--------------
@ -55,10 +58,11 @@ a file, you can read it into a string::
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>`_.
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
would be saving the node's role to a file and then using a custom Grain
to select it.

17
doc/topics/tutorials/firewall.rst
View file

@ -15,7 +15,7 @@ rules for allowing these incoming connections to the master.
iptables
========
Different Linux distributions store their iptables rules in different places,
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.
@ -43,15 +43,17 @@ to allow traffic on ``tcp/4505`` and ``tcp/4506``:
Create a file named ``/etc/ufw/applications.d/salt-master`` ::
[Salt Master]
title=Salt master
description=Salt is a remote execution and configuration management tool.
ports=4505,4506/tcp
[Salt Master]
title=Salt master
description=Salt is a remote execution and configuration management tool.
ports=4505,4506/tcp
.. _`iptables`: http://www.netfilter.org/
pf.conf
=======
The BSD-family of operating systems uses packet filter (pf). The following
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.
@ -66,3 +68,6 @@ new rules with the new additions. This can be done using the ``pfctl`` command.
.. code-block:: bash
pfctl -vf /etc/pf.conf
.. _ `packet filter (pf)`: http://openbsd.org/faq/pf/

4
doc/topics/tutorials/modules.rst
View file

@ -19,12 +19,12 @@ target
------
The target component allows you to filter which minions should run the
following function. The default filter is a glob on the minion id. E.g.::
following function. The default filter is a glob on the minion id. For example::
salt '*' test.ping
salt '*.example.org' test.ping
Targets can be based on minion system information using the grains system::
Targets can be based on minion system information using the Grains system::
salt -G 'os:Ubuntu' test.ping

18
doc/topics/tutorials/standalone_minion.rst
View file

@ -6,7 +6,7 @@ Since the Salt minion contains such extensive functionality it can be useful
to run it standalone. A standalone minion can be used to do a number of
things:
- Stand up a master server via states (Salting a Salt Master)
- Stand up a master server via States (Salting a Salt Master)
- Use salt-call commands on a system without connectivity to a master
- Masterless States, run states entirely from files local to the minion
@ -34,9 +34,9 @@ local system has all of the file ad pillar resources.
Running States Masterless
=========================
The state system can be easily run without a salt master, with all needed files
local to the minion. to do this the minion config file needs to be set up to
know how to return file_roots information like the master. The file_roots
The state system can be easily run without a Salt master, with all needed files
local to the minion. To do this the minion configuration file needs to be set
up to know how to return file_roots information like the master. The file_roots
setting defaults to /srv/salt for the base environment just like on the master:
.. code-block:: yaml
@ -45,16 +45,16 @@ setting defaults to /srv/salt for the base environment just like on the master:
base:
- /srv/salt
Now set up the salt state tree, top file and sls modules in the same way that
Now set up the Salt State Tree, top file, and SLS modules in the same way that
they would be set up on a master. Now, with the ``file_client`` option set to
``local`` and an available state tree then calls to functions in the state
module will use the information in the file_roots on the minion instead of
checking in with the master.
Remember that when creating a state tree on a minion there are no syntax or
path changes needed, sls modules written to be used from a master do not need
path changes needed, SLS modules written to be used from a master do not need
to be modified in any way to work with a minion.
This makes it easy to "script" deployments with salt states without having to
set up a master, and allows for these sls modules to be easily moved into a
salt master as the deployment grows.
This makes it easy to "script" deployments with Salt states without having to
set up a master, and allows for these SLS modules to be easily moved into a
Salt master as the deployment grows.

66
doc/topics/tutorials/starting_states.rst
View file

@ -19,20 +19,25 @@ is just a data structure under the hood. While understanding that the SLS is
just a data structure is not at all critical to understand to make use Salt
States, it should help bolster the understanding of where the real power is.
SLS files are therefore, in reality, just dictionaries, lists, strings and
numbers. By using this approach Salt can be much more flexible. As someone
writes more state files, it becomes clear exactly what is being written. The
result is a system that is easy to understand, yet grows with the needs of
the admin or developer.
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.
.. _`dictionaries`: http://docs.python.org/glossary.html#term-dictionary
.. _`lists`: http://docs.python.org/glossary.html#term-list
.. _`strings`: http://docs.python.org/library/stdtypes.html#typesseq
.. _`numbers: http://docs.python.org/library/stdtypes.html#numeric-types-int-float-long-complex
Default Data - YAML
===================
By default Salt represents the SLS data in what is one of the simplest
serialization formats available - YAML.
serialization formats available - `YAML`_.
A typical SLS file will often look like this in YAML:
@ -66,11 +71,13 @@ 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.
.. _`YAML`: http://yaml.org/spec/1.1/
Adding Configs and Users
========================
When setting up a service like an apache web server, many more components may
need to be added. The apache configuration file will most likely be managed,
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
@ -111,9 +118,9 @@ This SLS data greatly extends the first example, and includes a config file,
a user, a group and new requisite statement: ``watch``.
Adding more states is easy, since the new user and group states are under
the apache ID, the user and group will be the apache user and group. The
the Apache ID, the user and group will be the Apache user and group. The
``require`` statements will make sure that the user will only be made after
the group, and that the group will be made only after the apache package is
the group, and that the group will be made only after the Apache package is
installed.
Next,the ``require`` statement under service was changed to watch, and is
@ -135,10 +142,10 @@ combined to build out a State Tree. The above example also references a file
with a strange source - ``salt://apache/httpd.conf``. That file will need to
be available as well.
The SLS files are laid out in a directory on the salt master. Files are laid
out as just files. A sls is just a file and files to download are just files.
The SLS files are laid out in a directory on the Salt master. Files are laid
out as just files. A SLS is just a file and files to download are just files.
The apache example would be laid out in the root of the salt file server like
The Apache example would be laid out in the root of the Salt file server like
this: ::
/apache/init.sls
@ -148,7 +155,7 @@ So the httpd.conf is just a file in the apache directory, and is referenced
directly.
But with more than a single SLS file, more components can be added to the
toolkit, consider this ssh example:
toolkit, consider this SSH example:
``/ssh/init.sls:``
@ -287,28 +294,31 @@ to learn and use. But the SLS files can be rendered from almost any imaginable
medium, so long as a renderer module is provided.
The default rendering system is the ``yaml_jinja`` renderer. The
``yaml_jinja`` renderer will first pass the template through the jinja
``yaml_jinja`` renderer will first pass the template through the `Jinja2`_
templating system, and then through the YAML parser. The benefit here is that
full programming constructs are available when creating SLS files.
Other renderers available are ``yaml_mako`` which uses the mako templating
Other renderers available are ``yaml_mako`` which uses the `Mako`_ templating
system rather than the jinja templating system, and more notably, the pure
python or ``py`` renderer. The ``py`` renderer allows for SLS files to be
written in pure python, allowing for the utmost level of flexibility and
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.
.. _`Jinja2`: http://jinja.pocoo.org/
.. _`Mako`: http://www.makotemplates.org/
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:
templating system. A guide to the Jinja templating system can be found here:
http://jinja.pocoo.org/docs
When working with renderers a few very useful bits of data are passed in. In
the case of templating engine based renderers two critical components are
available, ``salt``, ``grains``, and ``pillar``. The salt object allows for
any salt function to be called from within the template, and grains allows for
the grains to be accessed from within the template. A few examples:
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:``
@ -353,7 +363,7 @@ the grains to be accessed from within the template. A few examples:
- mode: 644
This example is simple. If the ``os`` grain states that the operating system is
Red Hat, then the name of the apache package and service needs to be httpd.
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:
@ -428,11 +438,11 @@ Introducing the Python Renderer
-------------------------------
Sometimes the chosen default renderer might not have enough logical power to
accomplish the needed task. When this happens, the python renderer can be
used. Normally a yaml renderer should be used for the majority of SLS files,
accomplish the needed task. When this happens, the Python renderer can be
used. Normally a YAML renderer should be used for the majority of SLS files,
but a SLS file set to use another renderer can be easily added to the tree.
This example shows a very basic python SLS file:
This example shows a very basic Python SLS file:
``/python/django.sls:``
@ -454,7 +464,7 @@ 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
:doc:`HighState data structure</ref/states/highstate>`.
This python example would look like this if it were written in YAML:
This Python example would look like this if it were written in YAML:
.. code-block:: yaml
:linenos:
@ -468,6 +478,6 @@ This python example would look like this if it were written in YAML:
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.
needed by using a pure Python SLS.
Now onto the :doc:`States tutorial, part 1</topics/tutorials/states_pt1>`.

2
doc/topics/tutorials/states_pt1.rst
View file

@ -71,7 +71,7 @@ Create an ``sls`` module
========================
In the same directory as your :term:`top file`, create an empty file, called an
:term:`sls module`, named ``webserver.sls``. Type the following and save the
:term:`SLS module`, named ``webserver.sls``. Type the following and save the
file:
.. code-block:: yaml

2
doc/topics/tutorials/states_pt2.rst
View file

@ -32,7 +32,7 @@ the output.
Expand the SLS module
=====================
As you have seen, sls modules are appended with the file extension ``.sls`` and
As you have seen, SLS modules are appended with the file extension ``.sls`` and
are referenced by name starting at the root of the state tree. An SLS module
can be also defined as a directory. Demonstrate that now by creating a
directory named ``webserver`` and moving and renaming ``webserver.sls`` to