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

Merge remote-tracking branch 'upstream/2015.8' into 2015.8

Browse source
This commit is contained in:
Rafael Uzarowski 2015-09-23 21:56:43 +02:00
commit 5d292a221e
581 changed files with 81964 additions and 32635 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
conf/cloud
View file

@ -28,6 +28,9 @@
# The level of messages to send to the console.
# One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
#
# The following log levels are considered INSECURE and may log sensitive data:
# ['garbage', 'trace', 'debug']
#
# Default: 'info'
#
#log_level: info
@ -65,7 +68,9 @@
# the coloring of the messages, these color formatters also include padding as
# well. Color LogRecord attributes are only available for console logging.
#
#log_fmt_console: '%(colorlevel)s %(colormsg)s'
#log_fmt_console: '[%(levelname)-8s] %(message)s'
#
#log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'

24
conf/cloud.providers
View file

@ -3,13 +3,13 @@
# directory is identical.
#my-digitalocean-config:
# provider: digital_ocean
# driver: digital_ocean
# client_key: wFGEwgregeqw3435gDger
# api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
# location: New York 1
#my-aws-quick-start:
# provider: ec2
# driver: ec2
# id: HJGRYCILJLKJYG
# key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
# keyname: test
@ -17,7 +17,7 @@
# private_key: /root/test.pem
#my-aws-default:
# provider: ec2
# driver: ec2
# id: HJGRYCILJLKJYG
# key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
# keyname: test
@ -25,12 +25,12 @@
# private_key: /root/test.pem
#my-gogrid-config:
# provider: gogrid
# driver: gogrid
# apikey: asdff7896asdh789
# sharedsecret: saltybacon
#my-openstack-hp-config:
# provider: openstack
# driver: openstack
# identity_url: 'https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/'
# compute_name: Compute
# compute_region: 'az-1.region-a.geo-1'
@ -41,7 +41,7 @@
# password: mypass
#my-ibmsce-config:
# provider: ibmsce
# driver: ibmsce
# user: myuser@mycorp.com
# password: mypass
# ssh_key_name: mykey
@ -49,30 +49,30 @@
# location: Raleigh
#my-joyent-config:
# provider: joyent
# driver: joyent
# user: fred
# password: saltybacon
# private_key: /root/joyent.pem
#my-linode-config:
# provider: linode
# driver: linode
# apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf
# password: F00barbaz
#my-parallels-config:
# provider: parallels
# driver: parallels
# user: myuser
# password: xyzzy
# url: https://api.cloud.xmission.com:4465/paci/v1.0/
#my-proxmox-config:
# provider: proxmox
# driver: proxmox
# user: saltcloud@pve
# password: xyzzy
# url: your.proxmox.host
#my-openstack-rackspace-config:
# provider: openstack
# driver: openstack
# identity_url: 'https://identity.api.rackspacecloud.com/v2.0/tokens'
# compute_name: cloudServersOpenStack
# protocol: ipv4
@ -83,4 +83,4 @@
# apikey: 901d3f579h23c8v73q9
#my-saltify-config:
# provider: saltify
# driver: saltify

2
conf/cloud.providers.d/digitalocean.conf
View file

@ -1,5 +1,5 @@
#my-digitalocean-config:
# provider: digital_ocean
# driver: digital_ocean
# client_key: wFGEwgregeqw3435gDger
# api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
# location: New York 1

4
conf/cloud.providers.d/ec2.conf
View file

@ -1,5 +1,5 @@
#my-aws-quick-start:
# provider: ec2
# driver: ec2
# id: HJGRYCILJLKJYG
# key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
# keyname: test
@ -7,7 +7,7 @@
# private_key: /root/test.pem
#my-aws-default:
# provider: ec2
# driver: ec2
# id: HJGRYCILJLKJYG
# key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
# keyname: test

2
conf/cloud.providers.d/gogrid.conf
View file

@ -1,4 +1,4 @@
#my-gogrid-config:
# provider: gogrid
# driver: gogrid
# apikey: asdff7896asdh789
# sharedsecret: saltybacon

2
conf/cloud.providers.d/hpcloud-openstack.conf
View file

@ -1,5 +1,5 @@
#my-openstack-hp-config:
# provider: openstack
# driver: openstack
# identity_url: 'https://region-a.geo-1.identity.hpcloudsvc.com:35357/v2.0/'
# compute_name: Compute
# compute_region: 'az-1.region-a.geo-1'

2
conf/cloud.providers.d/ibmsce.conf
View file

@ -1,5 +1,5 @@
#my-ibmsce-config:
# provider: ibmsce
# driver: ibmsce
# user: myuser@mycorp.com
# password: mypass
# ssh_key_name: mykey

2
conf/cloud.providers.d/joyent.conf
View file

@ -1,5 +1,5 @@
#my-joyent-config:
# provider: joyent
# driver: joyent
# user: fred
# password: saltybacon
# private_key: /root/joyent.pem

2
conf/cloud.providers.d/linode.conf
View file

@ -1,4 +1,4 @@
#my-linode-config:
# provider: linode
# driver: linode
# apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf
# password: F00barbaz

2
conf/cloud.providers.d/parallels.conf
View file

@ -1,5 +1,5 @@
#my-parallels-config:
# provider: parallels
# driver: parallels
# user: myuser
# password: xyzzy
# url: https://api.cloud.xmission.com:4465/paci/v1.0/

3
conf/cloud.providers.d/proxmox.conf
View file

@ -1,6 +1,5 @@
#my-proxmox-config:
# provider: proxmox
# driver: proxmox
# user: saltcloud@pve
# password: xyzzy
# url: your.proxmox.host

2
conf/cloud.providers.d/rackspace-openstack.conf
View file

@ -1,5 +1,5 @@
#my-openstack-rackspace-config:
# provider: openstack
# driver: openstack
# identity_url: 'https://identity.api.rackspacecloud.com/v2.0/tokens'
# compute_name: cloudServersOpenStack
# protocol: ipv4

2
conf/cloud.providers.d/saltify.conf
View file

@ -1,2 +1,2 @@
#my-saltify-config:
# provider: saltify
# driver: saltify

2
conf/cloud.providers.d/vsphere.conf
View file

@ -1,5 +1,5 @@
#my-vsphere-config:
# provider: vsphere
# driver: vsphere
# user: myuser
# password: verybadpass
# url: 'https://10.1.1.1:443'

36
conf/master
View file

@ -356,12 +356,12 @@
# If this is set to True the first newline after a Jinja block is removed
# (block, not variable tag!). Defaults to False, corresponds to the Jinja
# environment init variable "trim_blocks".
# jinja_trim_blocks: False
#jinja_trim_blocks: False
#
# If this is set to True leading spaces and tabs are stripped from the start
# of a line to a block. Defaults to False, corresponds to the Jinja
# environment init variable "lstrip_blocks".
# jinja_lstrip_blocks: False
#jinja_lstrip_blocks: False
# The failhard option tells the minions to stop immediately after the first
# failure detected in the state execution, defaults to False
@ -381,7 +381,7 @@
#state_output: full
# Automatically aggregate all states that have support for mod_aggregate by
# setting to True. Or pass a list of state module names to automatically
# setting to 'True'. Or pass a list of state module names to automatically
# aggregate just those types.
#
# state_aggregate:
@ -389,6 +389,11 @@
#
#state_aggregate: False
# Send progress events as each function in a state run completes execution
# by setting to 'True'. Progress events are in the format
# 'salt/job/<JID>/prog/<MID>/<RUN NUM>'.
#state_events: False
##### File Server settings #####
##########################################
# Salt runs a lightweight file server written in zeromq to deliver files to
@ -413,6 +418,23 @@
#file_roots:
# base:
# - /srv/salt
#
# When using multiple environments, each with their own top file, the
# default behaviour is an unordered merge. To prevent top files from
# being merged together and instead to only use the top file from the
# requested environment, set this value to 'same'.
#top_file_merging_strategy: merge
# To specify the order in which environments are merged, set the ordering
# in the env_order option. Given a conflict, the last matching value will
# win.
#env_order: ['base', 'dev', 'prod']
# If top_file_merging_strategy is set to 'same' and an environment does not
# contain a top file, the top file in the environment specified by default_top
# will be used instead.
#default_top: base
# The hash_type is the hash to use when discovering the hash of a file on
# the master server. The default is md5, but sha1, sha224, sha256, sha384
@ -548,7 +570,7 @@
# master config file that can then be used on minions.
#pillar_opts: False
# The pillar_safe_render_error option prevents the master from passing piller
# The pillar_safe_render_error option prevents the master from passing pillar
# render errors to the minion. This is set on by default because the error could
# contain templating data which would give that minion information it shouldn't
# have, like a password! When set true the error message will only show:
@ -670,6 +692,10 @@
# The level of messages to send to the console.
# One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
#
# The following log levels are considered INSECURE and may log sensitive data:
# ['garbage', 'trace', 'debug']
#
#log_level: warning
# The level of messages to send to the log file.
@ -696,7 +722,9 @@
# the coloring of the messages, these color formatters also include padding as
# well. Color LogRecord attributes are only available for console logging.
#
#log_fmt_console: '%(colorlevel)s %(colormsg)s'
#log_fmt_console: '[%(levelname)-8s] %(message)s'
#
#log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'
# This can be used to control logging levels more specificically. This

16
conf/minion
View file

@ -1,5 +1,5 @@
##### Primary configuration settings #####
##########################################
##########################################
# This configuration file is used to manage the behavior of the Salt Minion.
# With the exception of the location of the Salt Master Server, values that are
# commented out but have an empty line after the comment are defaults that need
@ -25,7 +25,7 @@
# Minions can connect to multiple masters simultaneously (all masters
# are "hot"), or can be configured to failover if a master becomes
# unavailable. Multiple hot masters are configured by setting this
# value to "standard". Failover masters can be requested by setting
# value to "str". Failover masters can be requested by setting
# to "failover". MAKE SURE TO SET master_alive_interval if you are
# using failover.
# master_type: str
@ -482,9 +482,9 @@
# will be shown for each state run.
#state_output_profile: True
# Fingerprint of the master public key to double verify the master is valid,
# the master fingerprint can be found by running "salt-key -f master.pub" on the
# salt master.
# Fingerprint of the master public key to validate the identity of your Salt master
# before the initial key exchange. The master fingerprint can be found by running
# "salt-key -F master" on the Salt master.
#master_finger: ''
@ -511,6 +511,10 @@
# The level of messages to send to the console.
# One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'.
#
# The following log levels are considered INSECURE and may log sensitive data:
# ['garbage', 'trace', 'debug']
#
# Default: 'warning'
#log_level: warning
@ -539,7 +543,9 @@
# the coloring of the messages, these color formatters also include padding as
# well. Color LogRecord attributes are only available for console logging.
#
#log_fmt_console: '%(colorlevel)s %(colormsg)s'
#log_fmt_console: '[%(levelname)-8s] %(message)s'
#
#log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'
# This can be used to control logging levels more specificically. This

7
doc/_incl/_incl/sls_filename_cant_contain_period.rst
View file

@ -1,4 +1,4 @@
.. admonition:: Do not use dots in SLS file names
.. admonition:: Do not use dots in SLS file names or their directories
The initial implementation of :conf_master:`top.sls <state_top>` and
:ref:`include-declaration` followed the python import model where a slash
@ -6,4 +6,7 @@
the name ( besides the suffix period) can not be referenced. For example,
webserver_1.0.sls is not referenceable because webserver_1.0 would refer
to the directory/file webserver_1/0.sls
The same applies for any subdirecortories, this is especially 'tricky' when
git repos are created. Another command that typically can't render it's
output is ```state.show_sls``` of a file in a path that contains a dot.

3
doc/_static/proxy_minions.drawio.xml vendored
View file

File diff suppressed because one or more lines are too long

BIN
doc/_static/proxy_minions.png vendored
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 106 KiB

After

Width:  |  Height:  |  Size: 113 KiB

4
doc/_static/proxy_minions.svg vendored
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 109 KiB

BIN
doc/_static/rest_status_screen.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

26
doc/_themes/saltstack2/layout.html vendored
View file

@ -21,12 +21,12 @@
{% set script_files = [
'_static/js/core.min.js',
'_static/js/webhelp.min_v1.4.1.js',
'_static/js/webhelp.min_v1.4.2.js',
] %}
{% set css_files = [
'_static/css/core.min.css',
'_static/css/webhelp.min_v1.4.1.css',
'_static/css/webhelp.min_v1.4.2.css',
] %}
{%- macro relbar() %}
@ -160,6 +160,12 @@
</div>
{% endif %}
{% if build_type == "inactive" and on_saltstack %}
<div id="dev-notification">
<div class="alert alert-warning dev-notification-text releaselinks" role="alert"><i class="glyphicon glyphicon-cog"></i> You are viewing docs from a branch that is no longer active. You might want to view docs for the <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Docs for the latest stable release" href="/en/latest/">{{ latest_release }}</a> release instead.</div>
</div>
{% endif %}
{%- block document %}
<div class="body-content">
{% block body %} {% endblock %}
@ -192,8 +198,11 @@
{% elif build_type == "previous" %}
<p>You are viewing docs for the previous stable release, {{ previous_release }}. Switch to docs for the latest stable release, <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Docs for the latest stable release" href="/en/latest/">{{ latest_release }}</a>, or to a recent doc build from the <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Latest docs from the develop branch" href="/en/develop/">develop</a> branch.</p>
{% elif build_type == "inactive" %}
<p>You are viewing docs for an inactive release, {{ previous_release }}. Switch to docs for the latest stable release, <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Docs for the latest stable release" href="/en/latest/">{{ latest_release }}</a>, or to a recent doc build from the <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Latest docs from the develop branch" href="/en/develop/">develop</a> branch.</p>
{% elif build_type == "develop" %}
<p>You are viewing docs built from a recent snapshot of the develop branch. Switch to docs for the latest stable release, <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Docs for the latest stable release" href="/en/latest/">{{ latest_release }}</a>, or to docs for the previous stable release, <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Docs for the previous stable release" href="/en/{{ previous_release_dir }}/">{{ previous_release }}</a>.</p>
<p>You are viewing docs built from a recent snapshot of the develop branch. Switch to docs for the latest stable release, <a data-container="body" data-toggle="tooltip" data-placement="bottom" title="Docs for the latest stable release" href="/en/latest/">{{ latest_release }}</a>.</p>
{% endif %}
<br>
@ -203,12 +212,9 @@
<div class="col-sm-6">
<a href="http://saltstack.com/saltstack-enterprise-4-0-now-with-gui/" target="_blank"><img class="nolightbox nav-banner" src="{{ pathto('_static/images/saltStack_enterprise_350x125.jpg', 1) }}"/></a>
<a href="http://saltstack.com/events/" target="_blank"><img class="nolightbox nav-banner center" src="{{ pathto('_static/images/saltStack_events_300x300.jpg', 1) }}"/></a>
<br/><br/>
<p><b>SaltStack Training</b></p>
<p><a href="http://www.saltstack.com/training/">Now offering remote attendee training!</a></p>
</div>
</div>
{% endif %}
@ -224,9 +230,9 @@
<a class="ss-logo" href="http://saltstack.com"><img width="250" height="63" class="nolightbox center" src="{{ pathto('_static/images/saltstack_logo.svg', 1) }}"></a>
{% if on_saltstack %}
<div class="versions {{ build_type }}">
<div class="releaselinks versions {{ build_type }}">
<a class="btn btn-secondary{% if build_type == "previous" %} active{% endif %}" id="previous"{% if build_type == "previous" %} title="View release notes"{% else %} title="Switch to docs for the previous stable release"{% endif %} data-container="body" data-toggle="tooltip" data-placement="bottom" href="/en/{{ previous_release_dir }}/">{{ previous_release }}{% if build_type == "previous" %} <i class="glyphicon glyphicon-ok"></i>{%- endif %}</a>
<a class="btn btn-secondary{% if build_type == "previous" or build_type == "inactive" %} active{% endif %}" id="previous"{% if build_type == "previous" or build_type == "inactive" %} title="View release notes"{% else %} title="Switch to docs for the previous stable release"{% endif %} data-container="body" data-toggle="tooltip" data-placement="bottom" href="/en/{{ previous_release_dir }}/">{{ previous_release }}{% if build_type == "previous" or build_type == "inactive" %} <i class="glyphicon glyphicon-ok"></i>{%- endif %}</a>
<a class="btn btn-secondary{% if build_type == "latest" %} active{% endif %}" id="latest"{% if build_type == "latest" %} title="View release notes"{% else %} title="Switch to docs for the latest stable release"{% endif %} data-container="body" data-toggle="tooltip" data-placement="bottom" href="/en/latest/">{{ latest_release }}{% if build_type == "latest" %} <i class="glyphicon glyphicon-ok"></i>{% endif %}</a>
@ -295,7 +301,7 @@
<!--analytics-->
<script type="text/javascript" language="javascript">llactid=23943</script>
<script type="text/javascript" language="javascript" src="http://t6.trackalyzer.com/trackalyze.js"></script>
<script type="text/javascript" language="javascript" src="https://trackalyzer.com/trackalyze_secure.js"></script>
<script>
var _gaq = _gaq || [];

13
doc/_themes/saltstack2/static/css/webhelp.min_v1.4.1.css → doc/_themes/saltstack2/static/css/webhelp.min_v1.4.2.css vendored
View file

@ -21,11 +21,11 @@ img.center{display:block;margin:auto}
.list-group-item{border:none;padding-left:25px}
.list-group-item a{color:#333;display:list-item}
h1,h2,h3,h4,h5,h6,.h1,.h2,.h3,.h4,.h5,.h6{text-transform:uppercase}
h1,.h1,h1 > code.docutils.literal{color:#48b4fb;font-size:40px;margin-top:10px;margin-bottom:30px}
h2,.h2,h2 > code.docutils.literal{color:#48b4fb;font-size:23px}
h3,.h3,h3 > code.docutils.literal{font-size:18px}
h4,.h4,h4 > code.docutils.literal{font-size:16px}
h5,.h5,h5 > code.docutils.literal{font-size:16px;font-style:italic}
h1,.h1{color:#48b4fb;font-size:40px;margin-top:10px;margin-bottom:30px}
h2,.h2{color:#48b4fb;font-size:23px}
h3,.h3{font-size:18px}
h4,.h4{font-size:16px}
h5,.h5{font-size:16px;font-style:italic}
.subhead{color:#C0392B;font-size:16px;text-transform:uppercase}
.reference h3{font-size:16pt;line-height:1.9;color:#D75400;font-weight:300}
.head3 h2{font-size:21px;color:#C0392B}
@ -144,7 +144,8 @@ ul.nav.collapsed li{padding:0 0 15px 10px;margin:0}
.open>.dropdown-menu{width:100%}
#lnav-title{font-weight:300;font-size:16pt;text-align:center}
pre{border-top-width:4px;padding-top:18px}
code{font-family:Monaco,Menlo,Consolas,"Courier New",monospace;font-size:12px;color:#333;-webkit-border-radius:3px;-moz-border-radius:3px;border-radius:3px;white-space:nowrap;background-color:rgba(0,0,0,.1)}
code{font-family:Monaco,Menlo,Consolas,"Courier New",monospace;color:#333;-webkit-border-radius:3px;-moz-border-radius:3px;border-radius:3px;white-space:nowrap;background-color:rgba(0,0,0,.1)}
p code{font-size:12px}
code.xref{color:#4070a0}
code.descclassname{background-color:transparent;border:none}
code.descname{background-color:transparent;font-weight:700;font-size:1.5em}

BIN
doc/_themes/saltstack2/static/images/saltStack_enterprise_350x125.jpg vendored
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 22 KiB

BIN
doc/_themes/saltstack2/static/images/saltStack_events_300x300.jpg vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 20 KiB

4
doc/_themes/saltstack2/static/js/webhelp.min_v1.4.1.js → doc/_themes/saltstack2/static/js/webhelp.min_v1.4.2.js vendored
View file

@ -115,7 +115,7 @@ $( document ).ready(function() {
});
/*version page selector*/
$( 'div.versions' ).on('click', 'a', function (e) {
$( 'div.releaselinks' ).on('click', 'a', function (e) {
e.preventDefault();
var clickedVer = $(this).attr("href");
var $currentVer = $( 'div.versions' ).find( 'a.active' ).first();
@ -188,4 +188,4 @@ function resizeend() {
function last(list) {
return list[list.length - 1];
}
}

28
doc/conf.py
View file

@ -50,6 +50,7 @@ MOCK_MODULES = [
'Crypto.PublicKey',
'Crypto.Random',
'Crypto.Signature',
'Crypto.Signature.PKCS1_v1_5',
'M2Crypto',
'msgpack',
'yaml',
@ -87,6 +88,7 @@ MOCK_MODULES = [
'tornado.httpserver',
'tornado.httputil',
'tornado.ioloop',
'tornado.simple_httpclient',
'tornado.web',
'tornado.websocket',
@ -104,7 +106,6 @@ MOCK_MODULES = [
'MySQLdb.cursors',
'nagios_json',
'psutil',
'psutil.version_info',
'pycassa',
'pymongo',
'rabbitmq_server',
@ -162,23 +163,25 @@ project = 'Salt'
copyright = '2015 SaltStack, Inc.'
version = salt.version.__version__
latest_release = '2015.5.3' # latest release
previous_release = '2014.7.6' # latest release from previous branch
previous_release_dir = '2014.7' # path on web server for previous branch
build_type = 'develop' # latest, previous, develop
latest_release = '2015.8.0' # latest release
previous_release = '2015.5.5' # latest release from previous branch
previous_release_dir = '2015.5' # path on web server for previous branch
build_type = 'latest' # latest, previous, develop, inactive
# set release to 'version' for develop so sha is used
# - otherwise -
# set release to 'latest_release' or 'previous_release'
release = version # version, latest_release, previous_release
release = latest_release # version, latest_release, previous_release
# Set google custom search engine
if release == latest_release:
search_cx = '004624818632696854117:yfmprrbw3pk'
search_cx = '004624818632696854117:yfmprrbw3pk' # latest
elif release.startswith('2014.7'):
search_cx = '004624818632696854117:thhslradbru'
search_cx = '004624818632696854117:thhslradbru' # 2014.7
elif release.startswith('2015.5'):
search_cx = '004624818632696854117:ovogwef29do' # 2015.5
else:
search_cx = '004624818632696854117:haj7bjntf4s' # develop
@ -224,6 +227,14 @@ rst_prolog = """\
.. _`salt-users`: https://groups.google.com/forum/#!forum/salt-users
.. _`salt-announce`: https://groups.google.com/forum/#!forum/salt-announce
.. _`salt-packagers`: https://groups.google.com/forum/#!forum/salt-packagers
.. |windownload| raw:: html
<p>x86: <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-3-x86-Setup.exe"><strong>Salt-Minion-{release}-3-x86-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-3-x86-Setup.exe.md5"><strong>md5</strong></a></p>
<p>AMD64: <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-3-AMD64-Setup.exe"><strong>Salt-Minion-{release}-3-AMD64-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-3-AMD64-Setup.exe.md5"><strong>md5</strong></a></p>
""".format(release=release)
# A shortcut for linking to tickets on the GitHub issue tracker
@ -376,6 +387,7 @@ man_pages = [
('ref/cli/salt-key', 'salt-key', 'salt-key Documentation', authors, 1),
('ref/cli/salt-cp', 'salt-cp', 'salt-cp Documentation', authors, 1),
('ref/cli/salt-call', 'salt-call', 'salt-call Documentation', authors, 1),
('ref/cli/salt-proxy', 'salt-proxy', 'salt-proxy Documentation', authors, 1),
('ref/cli/salt-syndic', 'salt-syndic', 'salt-syndic Documentation', authors, 1),
('ref/cli/salt-run', 'salt-run', 'salt-run Documentation', authors, 1),
('ref/cli/salt-ssh', 'salt-ssh', 'salt-ssh Documentation', authors, 1),

1
doc/contents-2.rst
View file

@ -8,6 +8,7 @@ Salt Table of Contents
topics/jobs/index
topics/event/index
topics/proxyminion/index
topics/topology/index
topics/highavailability/index
topics/windows/index

4
doc/contents.rst
View file

@ -24,7 +24,9 @@ Salt Table of Contents
topics/ext_processes/index
topics/highavailability/index
topics/topology/index
topics/transports/raet/index
topics/proxyminion/index
topics/spm/index
topics/transports/index
topics/windows/index
topics/cloud/index
topics/netapi/index

17
doc/faq.rst
View file

@ -1,3 +1,5 @@
.. _faq:
Frequently Asked Questions
==========================
@ -301,3 +303,18 @@ More information about salting the Salt master can be found in the salt-formula
for salt itself:
https://github.com/saltstack-formulas/salt-formula
.. _faq-grain-security:
Is Targeting using Grain Data Secure?
=====================================
Because grains can be set by users that have access to the minion configuration
files on the local system, grains are considered less secure than other
identifiers in Salt. Use caution when targeting sensitive operations or setting
pillar values based on grain data.
When possible, you should target sensitive operations and data using the Minion
ID. If the Minion ID of a system changes, the Salt Minion's public key must be
re-accepted by an administrator on the Salt Master, making it less vulnerable
to impersonation attacks.

1
doc/glossary.rst
View file

@ -247,6 +247,7 @@ Glossary
whether or not the module should be available to a minion. This
function commonly contains logic to determine if all requirements
for a module are available, such as external libraries.
Worker
A master process which can send notices and receive replies from
minions. *See also*:

2
doc/index.rst
View file

@ -223,7 +223,7 @@ The following links explore various Salt topics in depth.
:doc:`Testing Salt <topics/development/tests/index>`
This is a tutorial for writing unit tests and integration tests.
:doc:`Salt Proxy Minions <topics/topology/proxyminion/index>`
:doc:`Salt Proxy Minions <topics/proxyminion/index>`
Proxy minions allow for the control of devices and machines which are
unable to run a salt-minion.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-API" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-API" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-api \- salt-api Command
.

5
doc/man/salt-call.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-CALL" "1" "June 26, 2015" "2015.5.0-1639-g9f8cef2" "Salt"
.TH "SALT-CALL" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-call \- salt-call Documentation
.
@ -206,7 +206,8 @@ using the Python \fBpprint\fP standard library module.
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT

5
doc/man/salt-cloud.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-CLOUD" "1" "June 26, 2015" "2015.5.0-1639-g9f8cef2" "Salt"
.TH "SALT-CLOUD" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-cloud \- Salt Cloud Command
.
@ -255,7 +255,8 @@ using the Python \fBpprint\fP standard library module.
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-CP" "1" "June 26, 2015" "2015.5.0-1639-g9f8cef2" "Salt"
.TH "SALT-CP" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-cp \- salt-cp Documentation
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-KEY" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-KEY" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-key \- salt-key Documentation
.
@ -135,7 +135,8 @@ using the Python \fBpprint\fP standard library module.
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-MASTER" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-MASTER" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-master \- salt-master Documentation
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-MINION" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-MINION" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-minion \- salt-minion Documentation
.

128
doc/man/salt-proxy.1 Normal file
View file

@ -0,0 +1,128 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-PROXY" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-proxy \- salt-proxy Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Receives commands from a Salt master and proxies these commands to
devices that are unable to run a full minion.
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
salt\-proxy [ options ]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The Salt proxy minion receives commands from a Salt master, transmits
appropriate commands to devices that are unable to run a minion, and replies
with the results of said commands.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-\-proxyid
The minion id that this proxy will assume. This is required.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Print the version of Salt that is running.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-versions\-report
Show program\(aqs dependencies and version number, and then exit
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Show the help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir
The location of the Salt configuration directory. This directory
contains the configuration files for Salt master and minions.
The default location on most systems is \fB/etc/salt\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-u USER, \-\-user=USER
Specify user to run salt\-proxy
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-daemon
Run salt\-proxy as a daemon
.UNINDENT
.INDENT 0.0
.TP
.B \-\-pid\-file PIDFILE
Specify the location of the pidfile. Default: \fB/var/run/salt\-proxy\-<id>.pid\fP
.UNINDENT
.SS Logging Options
.sp
Logging options which override any settings defined on the configuration files.
.INDENT 0.0
.TP
.B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL
Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file=LOG_FILE
Log file path. Default: /var/log/salt/minion\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file\-level=LOG_LEVEL_LOGFILE
Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
\fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default:
\fBwarning\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fIsalt(1)\fP
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch <thatch45@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2015 SaltStack, Inc.
.\" Generated by docutils manpage writer.
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-RUN" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-RUN" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-run \- salt-run Documentation
.

5
doc/man/salt-ssh.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-SSH" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-SSH" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-ssh \- salt-ssh Documentation
.
@ -221,7 +221,8 @@ using the Python \fBpprint\fP standard library module.
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-SYNDIC" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-SYNDIC" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-syndic \- salt-syndic Documentation
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT-UNITY" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT-UNITY" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt-unity \- salt-unity Command
.

11
doc/man/salt.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SALT" "1" "May 06, 2015" "2015.5.0" "Salt"
.TH "SALT" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
salt \- salt
.
@ -82,8 +82,10 @@ query the minions and check on running jobs. Default: 5
.B \-s, \-\-static
By default as of version 0.9.8 the salt command returns data to the
console as it is received from minions, but previous releases would return
data only after all data was received. To only return the data with a hard
timeout and after all minions have returned then use the static option.
data only after all data was received. Use the static option to only return
the data with a hard timeout and after all minions have returned.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
.UNINDENT
.INDENT 0.0
.TP
@ -280,7 +282,8 @@ using the Python \fBpprint\fP standard library module.
.INDENT 7.0
.INDENT 3.5
If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well.
Without the static option, you will get a JSON string for each minion.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use \fB\-\-static\fP as well.
.UNINDENT

63720
doc/man/salt.7
View file

File diff suppressed because it is too large Load diff

2
doc/man/spm.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "SPM" "1" "July 07, 2015" "2015.5.0-1703-gf8dc4fc" "Salt"
.TH "SPM" "1" "September 01, 2015" "2015.8.0" "Salt"
.SH NAME
spm \- Salt Package Manager Command
.

1
doc/ref/auth/all/index.rst
View file

@ -17,5 +17,6 @@ Full list of builtin auth modules
mysql
pam
pki
rest
stormpath
yubico

6
doc/ref/auth/all/salt.auth.rest.rst Normal file
View file

@ -0,0 +1,6 @@
salt.auth.rest module
=====================
.. automodule:: salt.auth.rest
:members:
:undoc-members:

1
doc/ref/beacons/all/index.rst
View file

@ -16,6 +16,7 @@ Full list of builtin beacon modules
journald
load
network_info
ps
service
sh
twilio_txt_msg

6
doc/ref/beacons/all/salt.beacons.ps.rst Normal file
View file

@ -0,0 +1,6 @@
salt.beacons.ps module
======================
.. automodule:: salt.beacons.ps
:members:
:undoc-members:

3
doc/ref/cli/_includes/output-options.rst
View file

@ -18,7 +18,8 @@ Output Options
.. note::
If using ``--out=json``, you will probably want ``--static`` as well.
Without the static option, you will get a JSON string for each minion.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
This is due to using an iterative outputter. So if you want to feed it
to a JSON parser, use ``--static`` as well.

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

@ -273,6 +273,12 @@ salt-minion
salt-minion
salt-proxy
==========
.. toctree::
salt-proxy
salt-run
========
.. toctree::

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

@ -15,6 +15,27 @@ Description
Salt-key executes simple management of Salt server public keys used for
authentication.
On initial connection, a Salt minion sends its public key to the Salt
master. This key must be accepted using the ``salt-key`` command on the
Salt master.
Salt minion keys can be in one of the following states:
- **unaccepted**: key is waiting to be accepted.
- **accepted**: key was accepted and the minion can communicate with the Salt
master.
- **rejected**: key was rejected using the ``salt-key`` command. In
this state the minion does not receive any communication from the Salt
master.
- **denied**: key was rejected automatically by the Salt master.
This occurs when a minion has a duplicate ID, or when a minion was rebuilt or
had new keys generated and the previous key was not deleted from the Salt
master. In this state the minion does not receive any communication from the
Salt master.
To change the state of a minion key, use ``-d`` to delete the key and then
accept or reject the key.
Options
=======
@ -163,4 +184,4 @@ See also
:manpage:`salt(7)`
:manpage:`salt-master(1)`
:manpage:`salt-minion(1)`
:manpage:`salt-minion(1)`

73
doc/ref/cli/salt-proxy.rst Normal file
View file

@ -0,0 +1,73 @@
.. _salt-proxy-cli:
==============
``salt-proxy``
==============
Receives commands from a Salt master and proxies these commands to
devices that are unable to run a full minion.
Synopsis
========
.. code-block:: bash
salt-proxy [ options ]
Description
===========
The Salt proxy minion receives commands from a Salt master, transmits
appropriate commands to devices that are unable to run a minion, and replies
with the results of said commands.
Options
=======
.. program:: salt-proxy
.. option:: --proxyid
The minion id that this proxy will assume. This is required.
.. option:: --version
Print the version of Salt that is running.
.. option:: --versions-report
Show program's dependencies and version number, and then exit
.. option:: -h, --help
Show the help message and exit
.. option:: -c CONFIG_DIR, --config-dir=CONFIG_dir
The location of the Salt configuration directory. This directory
contains the configuration files for Salt master and minions.
The default location on most systems is ``/etc/salt``.
.. option:: -u USER, --user=USER
Specify user to run salt-proxy
.. option:: -d, --daemon
Run salt-proxy as a daemon
.. option:: --pid-file PIDFILE
Specify the location of the pidfile. Default: ``/var/run/salt-proxy-<id>.pid``
.. include:: _includes/logging-options.rst
.. |logfile| replace:: /var/log/salt/minion
.. |loglevel| replace:: ``warning``
See also
========
:manpage:`salt(1)`
:manpage:`salt(7)`
:manpage:`salt-master(1)`
:manpage:`salt-minion(1)`

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

@ -34,8 +34,10 @@ Options
By default as of version 0.9.8 the salt command returns data to the
console as it is received from minions, but previous releases would return
data only after all data was received. To only return the data with a hard
timeout and after all minions have returned then use the static option.
data only after all data was received. Use the static option to only return
the data with a hard timeout and after all minions have returned.
Without the static option, you will get a separate JSON string per minion
which makes JSON output invalid as a whole.
.. option:: --async

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

@ -1,3 +1,5 @@
.. _spm-cli:
=======
``spm``
=======

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

@ -46,7 +46,7 @@ Salt's Loader Interface
Modules in the Salt ecosystem are loaded into memory using a custom loader
system. This allows modules to have conditional requirements (OS, OS version,
installed libraries, etc) and allows Salt to inject special variables
(``__salt__``, ``__opts``, etc).
(``__salt__``, ``__opts__``, etc).
Most modules can be manually loaded. This is often useful in third-party Python
apps or when writing tests. However some modules require and expect a full,

1
doc/ref/clouds/all/index.rst
View file

@ -14,7 +14,6 @@ Full list of Salt Cloud modules
botocore_aws
cloudstack
digital_ocean
digital_ocean_v2
ec2
gce
gogrid

6
doc/ref/clouds/all/salt.cloud.clouds.digital_ocean_v2.rst
View file

@ -1,6 +0,0 @@
==================================
salt.cloud.clouds.digital_ocean_v2
==================================
.. automodule:: salt.cloud.clouds.digital_ocean_v2
:members:

35
doc/ref/configuration/index.rst
View file

@ -101,6 +101,41 @@ Running Salt
There is also a full :doc:`troubleshooting guide</topics/troubleshooting/index>`
available.
.. _key-identity:
Key Identity
============
Salt provides commands to validate the identity of your Salt master
and Salt minions before the initial key exchange. Validating key identity helps
avoid inadvertently connecting to the wrong Salt master, and helps prevent
a potential MiTM attack when establishing the initial connection.
Master Key Fingerprint
----------------------
Print the master key fingerprint by running the following command on the Salt master:
.. code-block:: bash
salt-key -F master
Copy the ``master.pub`` fingerprint from the *Local Keys* section, and then set this value
as the :conf_minion:`master_finger` in the minion configuration file. Save the configuration
file and then restart the Salt minion.
Minion Key Fingerprint
----------------------
Run the following command on each Salt minion to view the minion key fingerprint:
.. code-block:: bash
salt-call --local key.finger
Compare this value to the value that is displayed when you run the
``salt-key --finger <MINION_ID>`` command on the Salt master.
Key Management
==============

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

@ -403,9 +403,9 @@ Default: ``''``
Specify the returner to use to log events. A returner may have installation and
configuration requirements. Read the returner's documentation.
.. note::
.. note::
Not all returners support event returns. Verify that a returner has an
Not all returners support event returns. Verify that a returner has an
``event_return()`` function before configuring this option with a returner.
.. code-block:: yaml
@ -417,7 +417,7 @@ configuration requirements. Read the returner's documentation.
``master_job_cache``
--------------------
.. versionadded:: 2014.7
.. versionadded:: 2014.7.0
Default: 'local_cache'
@ -908,6 +908,41 @@ If set to 'changes', the output will be full unless the state didn't change.
state_output: full
.. conf_master:: state_aggregate
``state_aggregate``
-------------------
Default: ``False``
Automatically aggregate all states that have support for mod_aggregate by
setting to ``True``. Or pass a list of state module names to automatically
aggregate just those types.
.. code-block:: yaml
state_aggregate:
- pkg
.. code-block:: yaml
state_aggregate: True
.. conf_master:: state_events
``state_events``
----------------
Default: ``False``
Send progress events as each function in a state run completes execution
by setting to ``True``. Progress events are in the format
``salt/job/<JID>/prog/<MID>/<RUN NUM>``.
.. code-block:: yaml
state_events: True
.. conf_master:: yaml_utf8
``yaml_utf8``
@ -1027,6 +1062,14 @@ nothing is ignored.
- '\*/somefolder/\*.bak'
- '\*.swp'
.. note::
Vim's .swp files are a common cause of Unicode errors in
:py:func:`file.recurse <salt.states.file.recurse>` states which use
templating. Unless there is a good reason to distribute them via the
fileserver, it is good practice to include ``'\*.swp'`` in the
:conf_master:`file_ignore_glob`.
roots: Master's Local File Server
---------------------------------
@ -1105,14 +1148,12 @@ Walkthrough <gitfs-per-remote-config>`.
.. versionadded:: 2014.7.0
Specify the provider to be used for gitfs. More information can be found in the
:ref:`GitFS Walkthrough <gitfs-dependencies>`.
Optional parameter used to specify the provider to be used for gitfs. More
information can be found in the :ref:`GitFS Walkthrough <gitfs-dependencies>`.
Specify one value among valid values: ``gitpython``, ``pygit2``, ``dulwich``
.. _pygit2: https://github.com/libgit2/pygit2
.. _GitPython: https://github.com/gitpython-developers/GitPython
.. _dulwich: https://www.samba.org/~jelmer/dulwich/
Must be one of the following: ``pygit2``, ``gitpython``, or ``dulwich``. If
unset, then each will be tried in that same order, and the first one with a
compatible version installed will be the provider that is used.
.. code-block:: yaml
@ -1125,11 +1166,11 @@ Specify one value among valid values: ``gitpython``, ``pygit2``, ``dulwich``
Default: ``True``
The ``gitfs_ssl_verify`` option specifies whether to ignore SSL certificate
errors when contacting the gitfs backend. You might want to set this to false
if you're using a git backend that uses a self-signed certificate but keep in
mind that setting this flag to anything other than the default of ``True`` is a
security concern, you may want to try using the ssh transport.
Specifies whether or not to ignore SSL certificate errors when contacting the
remote repository. You might want to set this to ``False`` if you're using a
git repo that uses a self-signed certificate. However, keep in mind that
setting this to anything other ``True`` is a considered insecure, and using an
SSH-based transport (if available) may be a better option.
.. code-block:: yaml
@ -1897,16 +1938,282 @@ There are additional details at :ref:`salt-pillars`
.. versionadded:: 2015.5.0
The ext_pillar_first option allows for external pillar sources to populate
before file system pillar. This allows for targeting file system pillar from
ext_pillar.
Default: ``False``
This option allows for external pillar sources to be evaluated before
:conf_master:`pillar_roots`. This allows for targeting file system pillar from
ext_pillar.
.. code-block:: yaml
ext_pillar_first: False
.. _git_pillar-config-opts:
Git External Pillar (git_pillar) Configuration Options
------------------------------------------------------
.. conf_master:: git_pillar_provider
``git_pillar_provider``
***********************
.. versionadded:: 2015.8.0
Specify the provider to be used for git_pillar. Must be either ``pygit2`` or
``gitpython``. If unset, then both will be tried in that same order, and the
first one with a compatible version installed will be the provider that is
used.
.. code-block:: yaml
git_pillar_provider: gitpython
.. conf_master:: git_pillar_base
``git_pillar_base``
*******************
.. versionadded:: 2015.8.0
Default: ``master``
If the desired branch matches this value, and the environment is omitted from
the git_pillar configuration, then the environment for that git_pillar remote
will be ``base``. For example, in the configuration below, the ``foo``
branch/tag would be assigned to the ``base`` environment, while ``bar`` would
be mapped to the ``bar`` environment.
.. code-block:: yaml
git_pillar_base: foo
ext_pillar:
- git:
- foo https://mygitserver/git-pillar.git
- bar https://mygitserver/git-pillar.git
.. conf_master:: git_pillar_branch
``git_pillar_branch``
*********************
.. versionadded:: 2015.8.0
Default: ``master``
If the branch is omitted from a git_pillar remote, then this branch will be
used instead. For example, in the configuration below, the first two remotes
would use the ``pillardata`` branch/tag, while the third would use the ``foo``
branch/tag.
.. code-block:: yaml
git_pillar_branch: pillardata
ext_pillar:
- git:
- https://mygitserver/pillar1.git
- https://mygitserver/pillar2.git:
- root: pillar
- foo https://mygitserver/pillar3.git
.. conf_master:: git_pillar_env
``git_pillar_env``
******************
.. versionadded:: 2015.8.0
Default: ``''`` (unset)
Environment to use for git_pillar remotes. This is normally derived from the
branch/tag (or from a per-remote ``env`` parameter), but if set this will
override the process of deriving the env from the branch/tag name. For example,
in the configuration below the ``foo`` branch would be assigned to the ``base``
environment, while the ``bar`` branch would need to explicitly have ``bar``
configured as it's environment to keep it from also being mapped to the
``base`` environment.
.. code-block:: yaml
git_pillar_env: base
ext_pillar:
- git:
- foo https://mygitserver/git-pillar.git
- bar https://mygitserver/git-pillar.git:
- env: bar
For this reason, this option is recommended to be left unset, unless the use
case calls for all (or almost all) of the git_pillar remotes to use the same
environment irrespective of the branch/tag being used.
.. conf_master:: git_pillar_root
``git_pillar_root``
*******************
.. versionadded:: 2015.8.0
Default: ``''``
Path relative to the root of the repository where the git_pillar top file and
SLS files are located. In the below configuration, the pillar top file and SLS
files would be looked for in a subdirectory called ``pillar``.
.. code-block:: yaml
git_pillar_root: pillar
ext_pillar:
- git:
- master https://mygitserver/pillar1.git
- master https://mygitserver/pillar2.git
.. note::
This is a global option. If only one or two repos need to have their files
sourced from a subdirectory, then :conf_master:`git_pillar_root` can be
omitted and the root can be specified on a per-remote basis, like so:
.. code-block:: yaml
ext_pillar:
- git:
- master https://mygitserver/pillar1.git
- master https://mygitserver/pillar2.git:
- root: pillar
In this example, for the first remote the top file and SLS files would be
looked for in the root of the repository, while in the second remote the
pillar data would be retrieved from the ``pillar`` subdirectory.
.. conf_master:: git_pillar_ssl_verify
``git_pillar_ssl_verify``
*************************
.. versionadded:: 2015.8.0
Default: ``True``
Specifies whether or not to ignore SSL certificate errors when contacting the
remote repository. You might want to set this to ``False`` if you're using a
git repo that uses a self-signed certificate. However, keep in mind that
setting this to anything other ``True`` is a considered insecure, and using an
SSH-based transport (if available) may be a better option.
.. code-block:: yaml
git_pillar_ssl_verify: True
Git External Pillar Authentication Options
******************************************
These parameters only currently apply to the ``pygit2``
:conf_master:`git_pillar_provider`. Authentication works the same as it does
in gitfs, as outlined in the :ref:`GitFS Walkthrough <gitfs-authentication>`,
though the global configuration options are named differently to reflect that
they are for git_pillar instead of gitfs.
.. conf_master:: git_pillar_user
``git_pillar_user``
~~~~~~~~~~~~~~~~~~~
.. versionadded:: 2015.8.0
Default: ``''``
Along with :conf_master:`git_pillar_password`, is used to authenticate to HTTPS
remotes.
.. code-block:: yaml
git_pillar_user: git
.. conf_master:: git_pillar_password
``git_pillar_password``
~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 2015.8.0
Default: ``''``
Along with :conf_master:`git_pillar_user`, is used to authenticate to HTTPS
remotes. This parameter is not required if the repository does not use
authentication.
.. code-block:: yaml
git_pillar_password: mypassword
.. conf_master:: git_pillar_insecure_auth
``git_pillar_insecure_auth``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 2015.8.0
Default: ``False``
By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This
parameter enables authentication over HTTP. **Enable this at your own risk.**
.. code-block:: yaml
git_pillar_insecure_auth: True
.. conf_master:: git_pillar_pubkey
``git_pillar_pubkey``
~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 2015.8.0
Default: ``''``
Along with :conf_master:`git_pillar_privkey` (and optionally
:conf_master:`git_pillar_passphrase`), is used to authenticate to SSH remotes.
.. code-block:: yaml
git_pillar_pubkey: /path/to/key.pub
.. conf_master:: git_pillar_privkey
``git_pillar_privkey``
~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 2015.8.0
Default: ``''``
Along with :conf_master:`git_pillar_pubkey` (and optionally
:conf_master:`git_pillar_passphrase`), is used to authenticate to SSH remotes.
.. code-block:: yaml
git_pillar_privkey: /path/to/key
.. conf_master:: git_pillar_passphrase
``git_pillar_passphrase``
~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 2015.8.0
Default: ``''``
This parameter is optional, required only when the SSH key being used to
authenticate is protected by a passphrase.
.. code-block:: yaml
git_pillar_passphrase: mypassphrase
.. conf_master:: pillar_source_merging_strategy
``pillar_source_merging_strategy``
@ -2058,10 +2365,21 @@ master, specify the higher level master with this configuration value.
syndic_master: masterofmasters
You can optionally connect a syndic to multiple higher level masters by
setting the 'syndic_master' value to a list:
.. code-block:: yaml
syndic_master:
- masterofmasters1
- masterofmasters2
Each higher level master must be set up in a multimaster configuration.
.. conf_master:: syndic_master_port
``syndic_master_port``
-----------------------
----------------------
Default: ``4506``
@ -2202,7 +2520,6 @@ Examples:
log_file: udp://loghost:10514
.. conf_master:: log_level
``log_level``
@ -2217,8 +2534,6 @@ The level of messages to send to the console. See also :conf_log:`log_level`.
log_level: warning
.. conf_master:: log_level_logfile
``log_level_logfile``
@ -2227,7 +2542,7 @@ The level of messages to send to the console. See also :conf_log:`log_level`.
Default: ``warning``
The level of messages to send to the log file. See also
:conf_log:`log_level_logfile`. When it is not set explicitly
:conf_log:`log_level_logfile`. When it is not set explicitly
it will inherit the level set by :conf_log:`log_level` option.
.. code-block:: yaml
@ -2235,7 +2550,6 @@ it will inherit the level set by :conf_log:`log_level` option.
log_level_logfile: warning
.. conf_master:: log_datefmt
``log_datefmt``
@ -2251,8 +2565,6 @@ The date and time format used in console log messages. See also
log_datefmt: '%H:%M:%S'
.. conf_master:: log_datefmt_logfile
``log_datefmt_logfile``
@ -2268,7 +2580,6 @@ The date and time format used in log file messages. See also
log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'
.. conf_master:: log_fmt_console
``log_fmt_console``
@ -2279,12 +2590,29 @@ Default: ``[%(levelname)-8s] %(message)s``
The format of the console logging messages. See also
:conf_log:`log_fmt_console`.
.. note::
Log colors are enabled in ``log_fmt_console`` rather than the
:conf_master:`color` config since the logging system is loaded before the
master config.
Console log colors are specified by these additional formatters:
%(colorlevel)s
%(colorname)s
%(colorprocess)s
%(colormsg)s
Since it is desirable to include the surrounding brackets, '[' and ']', in
the coloring of the messages, these color formatters also include padding
as well. Color LogRecord attributes are only available for console
logging.
.. code-block:: yaml
log_fmt_console: '%(colorlevel)s %(colormsg)s'
log_fmt_console: '[%(levelname)-8s] %(message)s'
.. conf_master:: log_fmt_logfile
``log_fmt_logfile``
@ -2300,7 +2628,6 @@ The format of the log file logging messages. See also
log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'
.. conf_master:: log_granular_levels
``log_granular_levels``
@ -2395,57 +2722,238 @@ option then the master will log a warning message.
- master.d/*
- /etc/roles/webserver
.. _winrepo-master-config-opts:
Windows Software Repo Settings
==============================
.. conf_master:: winrepo_provider
``winrepo_provider``
--------------------
.. versionadded:: 2015.8.0
Specify the provider to be used for winrepo. Must be either ``pygit2`` or
``gitpython``. If unset, then both will be tried in that same order, and the
first one with a compatible version installed will be the provider that is
used.
.. code-block:: yaml
winrepo_provider: gitpython
.. conf_master:: winrepo_dir
.. conf_master:: win_repo
``win_repo``
------------
``winrepo_dir``
---------------
.. versionchanged:: 2015.8.0
Renamed from ``win_repo`` to ``winrepo_dir``
Default: ``/srv/salt/win/repo``
Location of the repo on the master
Location on the master where the :conf_master:`winrepo_remotes` are checked
out.
.. code-block:: yaml
win_repo: '/srv/salt/win/repo'
winrepo_dir: /srv/salt/win/repo
.. conf_master:: winrepo_cachefile
.. conf_master:: win_repo_mastercachefile
``win_repo_mastercachefile``
----------------------------
``winrepo_cachefile``
---------------------
Default: ``/srv/salt/win/repo/winrepo.p``
.. versionchanged:: 2015.8.0
Renamed from ``win_repo_mastercachefile`` to ``winrepo_cachefile``
Default: ``winrepo.p``
Path relative to :conf_master:`winrepo_dir` where the winrepo cache should be
created.
.. code-block:: yaml
win_repo_mastercachefile: '/srv/salt/win/repo/winrepo.p'
winrepo_cachefile: winrepo.p
.. conf_master:: winrepo_remotes
.. conf_master:: win_gitrepos
``win_gitrepos``
----------------
``winrepo_remotes``
-------------------
.. versionchanged:: 2015.8.0
Renamed from ``win_gitrepos`` to ``winrepo_remotes``
Default: ``['https://github.com/saltstack/salt-winrepo.git']``
List of git repositories to checkout and include in the winrepo
.. code-block:: yaml
winrepo_remotes:
- https://github.com/saltstack/salt-winrepo.git
To specify a specific revision of the repository, prepend a commit ID to the
URL of the the repository:
.. code-block:: yaml
winrepo_remotes:
- '<commit_id> https://github.com/saltstack/salt-winrepo.git'
Replace ``<commit_id>`` with the SHA1 hash of a commit ID. Specifying a commit
ID is useful in that it allows one to revert back to a previous version in the
event that an error is introduced in the latest revision of the repo.
.. conf_master:: winrepo_branch
``winrepo_branch``
------------------
.. versionadded:: 2015.8.0
Default: ``master``
If the branch is omitted from a winrepo remote, then this branch will be
used instead. For example, in the configuration below, the first two remotes
would use the ``winrepo`` branch/tag, while the third would use the ``foo``
branch/tag.
.. code-block:: yaml
winrepo_branch: winrepo
ext_pillar:
- git:
- https://mygitserver/winrepo1.git
- https://mygitserver/winrepo2.git:
- foo https://mygitserver/winrepo3.git
.. conf_master:: winrepo_ssl_verify
``winrepo_ssl_verify``
----------------------
.. versionadded:: 2015.8.0
Default: ``True``
Specifies whether or not to ignore SSL certificate errors when contacting the
remote repository. You might want to set this to ``False`` if you're using a
git repo that uses a self-signed certificate. However, keep in mind that
setting this to anything other ``True`` is a considered insecure, and using an
SSH-based transport (if available) may be a better option.
.. code-block:: yaml
winrepo_ssl_verify: True
Winrepo Authentication Options
------------------------------
These parameters only currently apply to the ``pygit2``
:conf_master:`winrepo_provider`. Authentication works the same as it does in
gitfs, as outlined in the :ref:`GitFS Walkthrough <gitfs-authentication>`,
though the global configuration options are named differently to reflect that
they are for winrepo instead of gitfs.
.. conf_master:: winrepo_user
``winrepo_user``
****************
.. versionadded:: 2015.8.0
Default: ``''``
List of git repositories to include with the local repo.
Along with :conf_master:`winrepo_password`, is used to authenticate to HTTPS
remotes.
.. code-block:: yaml
win_gitrepos:
- 'https://github.com/saltstack/salt-winrepo.git'
winrepo_user: git
To specify a specific revision of the repository, preface the
repository location with a commit ID:
.. conf_master:: winrepo_password
``winrepo_password``
********************
.. versionadded:: 2015.8.0
Default: ``''``
Along with :conf_master:`winrepo_user`, is used to authenticate to HTTPS
remotes. This parameter is not required if the repository does not use
authentication.
.. code-block:: yaml
win_gitrepos:
- '<commit_id> https://github.com/saltstack/salt-winrepo.git'
winrepo_password: mypassword
Replacing ``<commit_id>`` with the ID from GitHub. Specifying a commit
ID is useful if you need to revert to a previous version if an error
is introduced in the latest version.
.. conf_master:: winrepo_insecure_auth
``winrepo_insecure_auth``
*************************
.. versionadded:: 2015.8.0
Default: ``False``
By default, Salt will not authenticate to an HTTP (non-HTTPS) remote. This
parameter enables authentication over HTTP. **Enable this at your own risk.**
.. code-block:: yaml
winrepo_insecure_auth: True
.. conf_master:: winrepo_pubkey
``winrepo_pubkey``
******************
.. versionadded:: 2015.8.0
Default: ``''``
Along with :conf_master:`winrepo_privkey` (and optionally
:conf_master:`winrepo_passphrase`), is used to authenticate to SSH remotes.
.. code-block:: yaml
winrepo_pubkey: /path/to/key.pub
.. conf_master:: winrepo_privkey
``winrepo_privkey``
*******************
.. versionadded:: 2015.8.0
Default: ``''``
Along with :conf_master:`winrepo_pubkey` (and optionally
:conf_master:`winrepo_passphrase`), is used to authenticate to SSH remotes.
.. code-block:: yaml
winrepo_privkey: /path/to/key
.. conf_master:: winrepo_passphrase
``winrepo_passphrase``
**********************
.. versionadded:: 2015.8.0
Default: ``''``
This parameter is optional, required only when the SSH key being used to
authenticate is protected by a passphrase.
.. code-block:: yaml
winrepo_passphrase: mypassphrase

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

@ -82,9 +82,9 @@ The option can can also be set to a list of masters, enabling
.. versionadded:: 2014.7.0
Default: ``standard``
Default: ``str``
The type of the :conf_minion:`master` variable. Can be ``standard``, ``failover`` or
The type of the :conf_minion:`master` variable. Can be ``str``, ``failover`` or
``func``.
.. code-block:: yaml
@ -145,7 +145,7 @@ the master hostname if name resolution fails. Defaults to 30 seconds.
Set to zero if the minion should shutdown and not retry.
.. code-block:: yaml
retry_dns: 30
.. conf_minion:: master_port
@ -198,7 +198,7 @@ need to be changed to the ownership of the new user.
.. conf_minion:: sudo_user
``sudo_user``
--------
-------------
Default: ``''``
@ -352,7 +352,7 @@ to enable set grains_cache to ``True``.
.. code-block:: yaml
cache_jobs: False
grains_cache: False
.. conf_minion:: sock_dir
@ -553,7 +553,7 @@ be able to execute a certain module. The sys module is built into the minion
and cannot be disabled.
This setting can also tune the minion, as all modules are loaded into ram
disabling modules will lover the minion's ram footprint.
disabling modules will lower the minion's ram footprint.
.. code-block:: yaml
@ -661,6 +661,23 @@ This setting requires that ``gcc`` and ``cython`` are installed on the minion
cython_enable: False
.. conf_minion:: enable_zip_modules
``enable_zip_modules``
----------------------
.. versionadded:: 2015.8.0
Default: ``False``
Set this value to true to enable loading of zip archives as extension modules.
This allows for packing module code with specific dependencies to avoid conflicts
and/or having to install specific modules' dependencies in system libraries.
.. code-block:: yaml
enable_zip_modules: False
.. conf_minion:: providers
``providers``
@ -891,6 +908,21 @@ minion to clean the keys.
open_mode: False
.. conf_minion:: master_finger
``master_finger``
-----------------
Default: ``''``
Fingerprint of the master public key to validate the identity of your Salt master
before the initial key exchange. The master fingerprint can be found by running
"salt-key -F master" on the Salt master.
.. code-block:: yaml
master_finger: 'ba:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:11:13'
.. conf_minion:: verify_master_pubkey_sign
@ -994,7 +1026,6 @@ Examples:
log_file: udp://loghost:10514
.. conf_minion:: log_level
``log_level``
@ -1009,8 +1040,6 @@ The level of messages to send to the console. See also :conf_log:`log_level`.
log_level: warning
.. conf_minion:: log_level_logfile
``log_level_logfile``
@ -1027,7 +1056,6 @@ it will inherit the level set by :conf_log:`log_level` option.
log_level_logfile: warning
.. conf_minion:: log_datefmt
``log_datefmt``
@ -1043,8 +1071,6 @@ The date and time format used in console log messages. See also
log_datefmt: '%H:%M:%S'
.. conf_minion:: log_datefmt_logfile
``log_datefmt_logfile``
@ -1060,7 +1086,6 @@ The date and time format used in log file messages. See also
log_datefmt_logfile: '%Y-%m-%d %H:%M:%S'
.. conf_minion:: log_fmt_console
``log_fmt_console``
@ -1071,12 +1096,29 @@ Default: ``[%(levelname)-8s] %(message)s``
The format of the console logging messages. See also
:conf_log:`log_fmt_console`.
.. note::
Log colors are enabled in ``log_fmt_console`` rather than the
:conf_minion:`color` config since the logging system is loaded before the
minion config.
Console log colors are specified by these additional formatters:
%(colorlevel)s
%(colorname)s
%(colorprocess)s
%(colormsg)s
Since it is desirable to include the surrounding brackets, '[' and ']', in
the coloring of the messages, these color formatters also include padding
as well. Color LogRecord attributes are only available for console
logging.
.. code-block:: yaml
log_fmt_console: '%(colorlevel)s %(colormsg)s'
log_fmt_console: '[%(levelname)-8s] %(message)s'
.. conf_minion:: log_fmt_logfile
``log_fmt_logfile``
@ -1092,7 +1134,6 @@ The format of the log file logging messages. See also
log_fmt_logfile: '%(asctime)s,%(msecs)03.0f [%(name)-17s][%(levelname)-8s] %(message)s'
.. conf_minion:: log_granular_levels
``log_granular_levels``
@ -1104,7 +1145,6 @@ This can be used to control logging levels more specifically. See also
:conf_log:`log_granular_levels`.
.. conf_minion:: failhard
``failhard``
@ -1116,7 +1156,6 @@ Set the global failhard flag, this informs all states to stop running states
at the moment a single state fails
.. code-block:: yaml
failhard: False
@ -1200,3 +1239,85 @@ have other services that need to go with it.
.. code-block:: yaml
update_restart_services: ['salt-minion']
.. _winrepo-minion-config-opts:
Standalone Minion Windows Software Repo Settings
================================================
.. important::
To use these config options, the minion must be running in masterless mode
(set :conf_minion:`file_client` to ``local``).
.. conf_minion:: winrepo_dir
.. conf_minion:: win_repo
``winrepo_dir``
---------------
.. versionchanged:: 2015.8.0
Renamed from ``win_repo`` to ``winrepo_dir``. Also, this option did not
have a default value until this version.
Default: ``C:\salt\srv\salt\win\repo``
Location on the minion where the :conf_minion:`winrepo_remotes` are checked
out.
.. code-block:: yaml
winrepo_dir: 'D:\winrepo'
.. conf_minion:: winrepo_cachefile
.. conf_minion:: win_repo_cachefile
``winrepo_cachefile``
---------------------
.. versionchanged:: 2015.8.0
Renamed from ``win_repo_cachefile`` to ``winrepo_cachefile``. Also,
this option did not have a default value until this version.
Default: ``winrepo.p``
Path relative to :conf_minion:`winrepo_dir` where the winrepo cache should be
created.
.. code-block:: yaml
winrepo_cachefile: winrepo.p
.. conf_minion:: winrepo_remotes
.. conf_minion:: win_gitrepos
``winrepo_remotes``
-------------------
.. versionchanged:: 2015.8.0
Renamed from ``win_gitrepos`` to ``winrepo_remotes``. Also, this option did
not have a default value until this version.
.. versionadded:: 2015.8.0
Default: ``['https://github.com/saltstack/salt-winrepo.git']``
List of git repositories to checkout and include in the winrepo
.. code-block:: yaml
winrepo_remotes:
- https://github.com/saltstack/salt-winrepo.git
To specify a specific revision of the repository, prepend a commit ID to the
URL of the the repository:
.. code-block:: yaml
winrepo_remotes:
- '<commit_id> https://github.com/saltstack/salt-winrepo.git'
Replace ``<commit_id>`` with the SHA1 hash of a commit ID. Specifying a commit
ID is useful in that it allows one to revert back to a previous version in the
event that an error is introduced in the latest revision of the repo.

2
doc/ref/index.rst
View file

@ -20,6 +20,7 @@ Reference
peer
pillar/index
pillar/all/index
proxy/all/index
renderers/index
returners/index
roster/all/index
@ -33,3 +34,4 @@ Reference
beacons/all/index
engines/all/index
sdb/all/index
serializers/all/index

21
doc/ref/modules/all/index.rst
View file

@ -25,6 +25,9 @@ Full list of builtin execution modules
at
augeas_cfg
aws_sqs
bamboohr
beacons
bigip
blockdev
bluez
boto_asg
@ -56,6 +59,7 @@ Full list of builtin execution modules
cmdmod
composer
config
consul
container_resource
cp
cpan
@ -69,6 +73,7 @@ Full list of builtin execution modules
ddns
deb_apache
deb_postgres
debbuild
debconfmod
debian_ip
debian_service
@ -121,11 +126,13 @@ Full list of builtin execution modules
hosts
htpasswd
http
ifttt
ilo
img
incron
influx
ini_manage
inspectlib
introspect
ipmi
ipset
@ -178,6 +185,7 @@ Full list of builtin execution modules
nfs3
nftables
nginx
node
nova
npm
nspawn
@ -192,6 +200,7 @@ Full list of builtin execution modules
osxdesktop
pacman
pagerduty
pagerduty_util
pam
parted
pecl
@ -218,6 +227,7 @@ Full list of builtin execution modules
quota
rabbitmq
raet_publish
rallydev
random_org
rbenv
rdp
@ -231,6 +241,7 @@ Full list of builtin execution modules
rh_service
riak
rpm
rpmbuild
rsync
runit
rvm
@ -248,6 +259,7 @@ Full list of builtin execution modules
shadow
slack_notify
smartos_imgadm
smartos_virt
smartos_vmadm
smbios
smf
@ -259,11 +271,13 @@ Full list of builtin execution modules
solarisips
solarispkg
solr
splay
splunk_search
sqlite3
ssh
state
status
stormpath
sudo
supervisord
svn
@ -274,20 +288,25 @@ Full list of builtin execution modules
sysrc
system
system_profiler
system_rest_sample
systemd
temp
test
test_virtual
timezone
tls
tomcat
trafficserver
tuned
twilio_notify
udev
upstart
uptime
useradd
uwsgi
varnish
vbox_guest
victorops
virt
virtualenv_mod
win_autoruns
@ -302,6 +321,7 @@ Full list of builtin execution modules
win_ntp
win_path
win_pkg
win_powercfg
win_repo
win_servermanager
win_service
@ -311,6 +331,7 @@ Full list of builtin execution modules
win_timezone
win_update
win_useradd
win_wua
x509
xapi
xfs

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

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

3
doc/ref/modules/all/salt.modules.git.rst
View file

@ -3,4 +3,5 @@ salt.modules.git
================
.. automodule:: salt.modules.git
:members:
:members:
:exclude-members: config_get_regex

6
doc/ref/modules/all/salt.modules.inspectlib.collector.rst Normal file
View file

@ -0,0 +1,6 @@
salt.modules.inspectlib.collector module
========================================
.. automodule:: salt.modules.inspectlib.collector
:members:
:undoc-members:

6
doc/ref/modules/all/salt.modules.inspectlib.dbhandle.rst Normal file
View file

@ -0,0 +1,6 @@
salt.modules.inspectlib.dbhandle module
=======================================
.. automodule:: salt.modules.inspectlib.dbhandle
:members:
:undoc-members:

6
doc/ref/modules/all/salt.modules.inspectlib.exceptions.rst Normal file
View file

@ -0,0 +1,6 @@
salt.modules.inspectlib.exceptions module
=========================================
.. automodule:: salt.modules.inspectlib.exceptions
:members:
:undoc-members:

6
doc/ref/modules/all/salt.modules.inspectlib.query.rst Normal file
View file

@ -0,0 +1,6 @@
salt.modules.inspectlib.query module
====================================
.. automodule:: salt.modules.inspectlib.query
:members:
:undoc-members:

19
doc/ref/modules/all/salt.modules.inspectlib.rst Normal file
View file

@ -0,0 +1,19 @@
salt.modules.inspectlib package
===============================
Submodules
----------
.. toctree::
salt.modules.inspectlib.collector
salt.modules.inspectlib.dbhandle
salt.modules.inspectlib.exceptions
salt.modules.inspectlib.query
Module contents
---------------
.. automodule:: salt.modules.inspectlib
:members:
:undoc-members:

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

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

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

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

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

@ -1,3 +1,5 @@
.. _execution-modules:
=================
Execution Modules
=================
@ -48,8 +50,90 @@ starts, so only the ``*.pyx`` file is required.
.. _`Cython`: http://cython.org/
Cross-Calling Modules
=====================
Zip Archives as Modules
=======================
Python 2.3 and higher allows developers to directly import zip archives containing Python code.
By setting :conf_minion:`enable_zip_modules` to ``True`` in the minion config, the Salt loader
will be able to import ``.zip`` files in this fashion. This allows Salt module developers to
package dependencies with their modules for ease of deployment, isolation, etc.
For a user, Zip Archive modules behave just like other modules. When executing a function from a
module provided as the file ``my_module.zip``, a user would call a function within that module
as ``my_module.<function>``.
Creating a Zip Archive Module
-----------------------------
A Zip Archive module is structured similarly to a simple `Python package`_. The ``.zip`` file contains
a single directory with the same name as the module. The module code traditionally in ``<module_name>.py``
goes in ``<module_name>/__init__.py``. The dependency packages are subdirectories of ``<module_name>/``.
Here is an example directory structure for the ``lumberjack`` module, which has two library dependencies
(``sleep`` and ``work``) to be included.
.. code-block:: bash
modules $ ls -R lumberjack
__init__.py sleep work
lumberjack/sleep:
__init__.py
lumberjack/work:
__init__.py
The contents of ``lumberjack/__init__.py`` show how to import and use these included libraries.
.. code-block:: python
# Libraries included in lumberjack.zip
from lumberjack import sleep, work
def is_ok(person):
''' Checks whether a person is really a lumberjack '''
return sleep.all_night(person) and work.all_day(person)
Then, create the zip:
.. code-block:: bash
modules $ zip -r lumberjack lumberjack
adding: lumberjack/ (stored 0%)
adding: lumberjack/__init__.py (deflated 39%)
adding: lumberjack/sleep/ (stored 0%)
adding: lumberjack/sleep/__init__.py (deflated 7%)
adding: lumberjack/work/ (stored 0%)
adding: lumberjack/work/__init__.py (deflated 7%)
modules $ unzip -l lumberjack.zip
Archive: lumberjack.zip
Length Date Time Name
-------- ---- ---- ----
0 08-21-15 20:08 lumberjack/
348 08-21-15 20:08 lumberjack/__init__.py
0 08-21-15 19:53 lumberjack/sleep/
83 08-21-15 19:53 lumberjack/sleep/__init__.py
0 08-21-15 19:53 lumberjack/work/
81 08-21-15 19:21 lumberjack/work/__init__.py
-------- -------
512 6 files
Once placed in :conf_master:`file_roots`, Salt users can distribute and use ``lumberjack.zip`` like any other module.
.. code-block:: bash
$ sudo salt minion1 saltutil.sync_modules
minion1:
- modules.lumberjack
$ sudo salt minion1 lumberjack.is_ok 'Michael Palin'
minion1:
True
.. _`Python package`: https://docs.python.org/2/tutorial/modules.html#packages
.. _cross-calling-execution-modules:
Cross Calling Execution Modules
===============================
All of the Salt execution modules are available to each other and modules can call
functions available in other execution modules.
@ -68,8 +152,8 @@ Salt modules can be cross-called by accessing the value in the ``__salt__`` dict
def foo(bar):
return __salt__['cmd.run'](bar)
This code will call the `run` function in the :mod:`cmd <salt.modules.cmdmod>` and pass the argument
``bar`` to it.
This code will call the `run` function in the :mod:`cmd <salt.modules.cmdmod>`
module and pass the argument ``bar`` to it.
Preloaded Execution Module Data
@ -154,15 +238,6 @@ The ``__virtual__`` function is used to return either a
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.
.. note::
Optionally, modules may additionally return a list of reasons that a module could
not be loaded. For example, if a dependency for 'my_mod' was not met, a
__virtual__ function could do as follows:
return False, ['My Module must be installed before this module can be
used.']
This means that the package manager modules can be presented as the ``pkg`` module
regardless of what the actual module is named.
@ -181,6 +256,16 @@ function. Some examples:
Modules which return a string from ``__virtual__`` that is already used by a module that
ships with Salt will _override_ the stock module.
Returning Error Information from ``__virtual__``
------------------------------------------------
Optionally, modules may additionally return a list of reasons that a module could
not be loaded. For example, if a dependency for 'my_mod' was not met, a
__virtual__ function could do as follows:
return False, ['My Module must be installed before this module can be
used.']
Documentation
=============
@ -249,6 +334,22 @@ on.
The platform field is a comma-delimited list of platforms that this module is
known to run on.
Log Output
==========
You can call the logger from custom modules to write messages to the minion
logs. The following code snippet demonstrates writing log messages:
.. code-block:: python
import logging
log = logging.getLogger(__name__)
log.info('Here is Some Information')
log.warning('You Should Not Do That')
log.error('It Is Busted')
Private Functions
=================

6
doc/ref/netapi/all/salt.netapi.rest_cherrypy.app.rst Normal file
View file

@ -0,0 +1,6 @@
salt.netapi.rest_cherrypy.app module
====================================
.. automodule:: salt.netapi.rest_cherrypy.app
:members:
:undoc-members:

6
doc/ref/netapi/all/salt.netapi.rest_cherrypy.wsgi.rst Normal file
View file

@ -0,0 +1,6 @@
salt.netapi.rest_cherrypy.wsgi module
=====================================
.. automodule:: salt.netapi.rest_cherrypy.wsgi
:members:
:undoc-members:

6
doc/ref/netapi/all/salt.netapi.rest_tornado.saltnado.rst Normal file
View file

@ -0,0 +1,6 @@
salt.netapi.rest_tornado.saltnado module
========================================
.. automodule:: salt.netapi.rest_tornado.saltnado
:members:
:undoc-members:

6
doc/ref/netapi/all/salt.netapi.rest_tornado.saltnado_websockets.rst Normal file
View file

@ -0,0 +1,6 @@
salt.netapi.rest_tornado.saltnado_websockets module
===================================================
.. automodule:: salt.netapi.rest_tornado.saltnado_websockets
:members:
:undoc-members:

4
doc/ref/pillar/all/index.rst
View file

@ -14,6 +14,7 @@ Full list of builtin pillar modules
cmd_yaml
cmd_yamlex
cobbler
consul_pillar
django_orm
ec2_pillar
etcd_pillar
@ -25,12 +26,15 @@ Full list of builtin pillar modules
libvirt
mongo
mysql
neutron
pepa
pillar_ldap
puppet
reclass_adapter
redismod
s3
sql_base
sqlite3
svn_pillar
varstack_pillar
virtkey

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

@ -0,0 +1,6 @@
salt.pillar.consul_pillar module
================================
.. automodule:: salt.pillar.consul_pillar
:members:
:undoc-members:

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

@ -0,0 +1,6 @@
salt.pillar.neutron module
==========================
.. automodule:: salt.pillar.neutron
:members:
:undoc-members:

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

@ -0,0 +1,6 @@
salt.pillar.sql_base module
===========================
.. automodule:: salt.pillar.sql_base
:members:
:undoc-members:

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

@ -0,0 +1,6 @@
salt.pillar.sqlite3 module
==========================
.. automodule:: salt.pillar.sqlite3
:members:
:undoc-members:

14
doc/ref/proxy/all/index.rst Normal file
View file

@ -0,0 +1,14 @@
.. _all-salt.proxy:
==================================
Full list of builtin proxy modules
==================================
.. currentmodule:: salt.proxy
.. autosummary::
:toctree:
:template: autosummary.rst.tmpl
junos
rest_sample

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

@ -0,0 +1,6 @@
salt.proxy.junos module
=======================
.. automodule:: salt.proxy.junos
:members:
:undoc-members:

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

@ -0,0 +1,6 @@
salt.proxy.rest_sample module
=============================
.. automodule:: salt.proxy.rest_sample
:members:
:undoc-members:

6
doc/ref/queues/all/salt.queues.sqlite_queue.rst Normal file
View file

@ -0,0 +1,6 @@
salt.queues.sqlite_queue module
===============================
.. automodule:: salt.queues.sqlite_queue
:members:
:undoc-members:

8
doc/ref/renderers/all/salt.renderers.stateconf.rst
View file

@ -172,20 +172,22 @@ Here's a list of features enabled by this renderer.
include:
- .apache
- .db.mysql
- ..app.django
exclude:
- sls: .users
If the above is written in a salt file at `salt://some/where.sls` then
it will include `salt://some/apache.sls` and `salt://some/db/mysql.sls`,
and exclude `salt://some/users.ssl`. Actually, it does that by rewriting
the above ``include`` and ``exclude`` into:
it will include `salt://some/apache.sls`, `salt://some/db/mysql.sls` and
`salt://app/django.sls`, and exclude `salt://some/users.ssl`. Actually,
it does that by rewriting the above ``include`` and ``exclude`` into:
.. code-block:: yaml
include:
- some.apache
- some.db.mysql
- app.django
exclude:
- sls: some.users

2
doc/ref/returners/all/index.rst
View file

@ -19,6 +19,7 @@ Full list of builtin returner modules
elasticsearch_return
etcd_return
hipchat_return
influxdb_return
kafka_return
local
local_cache
@ -29,6 +30,7 @@ Full list of builtin returner modules
mysql
nagios_return
odbc
pgjsonb
postgres
postgres_local_cache
pushover_returner

1
doc/ref/runners/all/index.rst
View file

@ -31,6 +31,7 @@ Full list of runner modules
pkg
queue
sdb
ssh
search
state
survey

6
doc/ref/sdb/all/salt.sdb.rest.rst Normal file
View file

@ -0,0 +1,6 @@
salt.sdb.rest module
====================
.. automodule:: salt.sdb.rest
:members:
:undoc-members:

15
doc/ref/states/all/index.rst
View file

@ -14,12 +14,14 @@ Full list of builtin state modules
alternatives
apache
apache_module
apt
aptpkg
archive
artifactory
at
augeas
aws_sqs
beacon
bigip
blockdev
boto_asg
boto_cfn
@ -52,10 +54,14 @@ Full list of builtin state modules
dockerio
dockerng
drac
elasticsearch_index
elasticsearch_index_template
environ
eselect
etcd_mod
event
file
firewalld
gem
git
glusterfs
@ -68,6 +74,7 @@ Full list of builtin state modules
host
htpasswd
http
ifttt
incron
influxdb_database
influxdb_user
@ -114,6 +121,7 @@ Full list of builtin state modules
pecl
pip_state
pkg
pkgbuild
pkgng
pkgrepo
portage_config
@ -122,6 +130,7 @@ Full list of builtin state modules
postgres_extension
postgres_group
postgres_schema
postgres_tablespace
postgres_user
powerpath
process
@ -151,6 +160,7 @@ Full list of builtin state modules
ssh_known_hosts
stateconf
status
stormpath_account
supervisord
svn
sysctl
@ -160,16 +170,19 @@ Full list of builtin state modules
timezone
tls
tomcat
trafficserver
tuned
uptime
user
vbox_guest
victorops
virtualenv_mod
win_dacl
win_dns_client
win_firewall
win_network
win_path
win_powercfg
win_servermanager
win_system
win_update

6
doc/ref/states/all/salt.states.apt.rst
View file

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

3
doc/ref/states/all/salt.states.git.rst
View file

@ -3,4 +3,5 @@ salt.states.git
===============
.. automodule:: salt.states.git
:members:
:members:
:exclude-members: config

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

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

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

@ -7,9 +7,13 @@ Highstate data structure definitions
The Salt State Tree
===================
A state tree is a collection of ``SLS`` files that live under the directory
specified in :conf_master:`file_roots`. A state tree can be organized into
``SLS modules``.
A state tree is a collection of ``SLS`` files and directories that live under the directory
specified in :conf_master:`file_roots`.
.. note::
Directory names or filenames in the state tree cannot contain a period, with the
exception of the period in the .sls file suffix.
.. _states-highstate-top-file:
@ -76,9 +80,8 @@ Extend declaration
------------------
Extends a :ref:`name-declaration` from an included ``SLS module``. The
keys of the extend declaration always define existing :ref`ID declaration`
which have been defined in included
``SLS modules``.
keys of the extend declaration always refer to an existing
:ref:`id-declaration` which have been defined in included ``SLS modules``.
Occurs only in the top level and defines a dictionary.
@ -398,4 +401,4 @@ components.
- <name>
- <name>
- <Requisite Declaration>:
- <Requisite Reference>
- <Requisite Reference>

55
doc/ref/states/include.rst
View file

@ -2,15 +2,15 @@
Include and Exclude
===================
Salt sls files can include other sls files and exclude sls files that have been
otherwise included. This allows for an sls file to easily extend or manipulate
other sls files.
Salt SLS files can include other SLS files and exclude SLS files that have been
otherwise included. This allows for an SLS file to easily extend or manipulate
other SLS files.
Include
=======
When other sls files are included, everything defined in the included sls file
will be added to the state run. When including define a list of sls formulas
When other SLS files are included, everything defined in the included SLS file
will be added to the state run. When including define a list of SLS formulas
to include:
.. code-block:: yaml
@ -19,10 +19,10 @@ to include:
- http
- libvirt
The include statement will include sls formulas from the same environment
that the including sls formula is in. But the environment can be explicitly
The include statement will include SLS formulas from the same environment
that the including SLS formula is in. But the environment can be explicitly
defined in the configuration to override the running environment, therefore
if an sls formula needs to be included from an external environment named "dev"
if an SLS formula needs to be included from an external environment named "dev"
the following syntax is used:
.. code-block:: yaml
@ -30,8 +30,8 @@ the following syntax is used:
include:
- dev: http
**NOTE**: `include` does not simply inject the states where you place it
in the sls file. If you need to guarantee order of execution, consider using
**NOTE**: ``include`` does not simply inject the states where you place it
in the SLS file. If you need to guarantee order of execution, consider using
requisites.
.. include:: ../../_incl/_incl/sls_filename_cant_contain_period.rst
@ -39,9 +39,9 @@ requisites.
Relative Include
================
In Salt 0.16.0 the capability to include sls formulas which are relative to
the running sls formula was added, simply precede the formula name with a
`.`:
In Salt 0.16.0, the capability to include SLS formulas which are relative to
the running SLS formula was added. Simply precede the formula name with a
``.``:
.. code-block:: yaml
@ -49,18 +49,35 @@ the running sls formula was added, simply precede the formula name with a
- .virt
- .virt.hyper
In Salt 2015.8, the ability to include SLS formulas which are relative to the
parents of the running SLS formula was added. In order to achieve this,
precede the formula name with more than one ``.`` (dot). Much like Python's
relative import abilities, two or more leading dots represent a relative
include of the parent or parents of the current package, with each ``.``
representing one level after the first.
The following SLS configuration, if placed within ``example.dev.virtual``,
would result in ``example.http`` and ``base`` being included respectively:
.. code-block:: yaml
include:
- ..http
- ...base
Exclude
=======
The exclude statement, added in Salt 0.10.3 allows an sls to hard exclude
another sls file or a specific id. The component is excluded after the
The exclude statement, added in Salt 0.10.3, allows an SLS to hard exclude
another SLS file or a specific id. The component is excluded after the
high data has been compiled, so nothing should be able to override an
exclude.
Since the exclude can remove an id or an sls the type of component to
exclude needs to be defined. an exclude statement that verifies that the
running highstate does not contain the `http` sls and the `/etc/vimrc` id
would look like this:
Since the exclude can remove an id or an SLS the type of component to exclude
needs to be defined. An exclude statement that verifies that the running
highstate does not contain the ``http`` SLS and the ``/etc/vimrc`` id would
look like this:
.. code-block:: yaml

2
doc/ref/states/requisites.rst
View file

@ -4,6 +4,8 @@
Requisites and Other Global State Arguments
===========================================
.. _requisites-fire-event:
Fire Event Notifications
========================

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

@ -4,33 +4,87 @@
The Top File
============
The top file (top.sls) 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.
Introduction
============
Most infrastructures are made up of groups of machines, each machine in the
group performing a role similar to others. Those groups of machines work
in concert with each other to create an application stack.
To effectively manage those groups of machines, an administrator needs to
be able to create roles for those groups. For example, a group of machines
that serve front-end web traffic might have roles which indicate that
those machines should all have the Apache webserver package installed and
that the Apache service should always be running.
In Salt, the file which contains a mapping between groups of machines on a
network and the configuration roles that should be applied to them is
called a ``top file``.
Top files are named ``top.sls`` by default and they are so-named because they
always exist in the "top" of a directory hierarchy that contains state files.
That directory hierarchy is called a ``state tree``.
A Basic Example
===============
Top files have three components:
- Environment: A state tree directory containing a set of state files to
configure systems.
- Target: A grouping of machines which will have a set of states applied
to them.
- State files: A list of state files to apply to a target. Each state
file describes one or more states to be configured and enforced
on the targeted machines.
The relationship between these three components is nested as follows:
- Environments contain targets
- Targets contain states
Putting these concepts together, we can describe a scenario in which all
minions with an ID that begins with ``web`` have an ``apache`` state applied
to them:
.. code-block:: yaml
base: # Apply SLS files from the directory root for the 'base' environment
'web*': # All minions with a minion_id that begins with 'web'
- apache # Apply the state file named 'apache.sls'
.. _states-top-environments:
Environments
============
Environments allow conceptually organizing state tree directories. Environments
can be made to be self-contained or state trees can be made to bleed through
environments.
Environments are directory hierarchies which contain a top files and a set
of state files.
.. note::
Environments can be used in many ways, however there is no requirement that
they be used at all. In fact, the most common way to deploy Salt is with
a single environment, called ``base``. It is recommended that users only
create multiple environments if they have a use case which specifically
calls for multiple versions of state trees.
Environments in Salt are very flexible. This section defines how the top
file can be used to define what states from what environments are to be
used for specific minions.
If the intent is to bind minions to specific environments, then the
`environment` option can be set in the minion configuration file.
Getting Started with Top Files
==============================
Each environment is defined inside a salt master configuration variable
called, :conf_master:`file_roots` .
In the most common single-environment setup, only the ``base`` environment is
defined in :conf_master:`file_roots` along with only one directory path for
the state tree.
The environments in the top file corresponds with the environments defined in
the :conf_master:`file_roots` variable. In a simple, single environment setup
you only have the ``base`` environment, and therefore only one state tree. Here
is a simple example of :conf_master:`file_roots` in the master configuration:
.. code-block:: yaml
@ -38,8 +92,13 @@ is a simple example of :conf_master:`file_roots` in the master configuration:
base:
- /srv/salt
This means that the top file will only have one environment to pull from,
here is a simple, single environment top file:
In the above example, the top file will only have a single environment to pull
from.
Next is a simple single-environment top file placed in ``/srv/salt/top.sls``,
illustrating that for the environment called ``base``, all minions will have the
state files named ``core.sls`` and ``edit.sls`` applied to them.
.. code-block:: yaml
@ -48,15 +107,26 @@ here is a simple, single environment top file:
- core
- edit
This also means that :file:`/srv/salt` has a state tree. But if you want to use
multiple environments, or partition the file server to serve more than
just the state tree, then the :conf_master:`file_roots` option can be expanded:
Assuming the ``file_roots`` configuration from above, Salt will look in the
``/srv/salt`` directory for ``core.sls`` and ``edit.sls``.
Multiple Environments
=====================
In some cases, teams may wish to create versioned state trees which can be
used to test Salt configurations in isolated sets of systems such as a staging
environment before deploying states into production.
For this case, multiple environments can be used to accomplish this task.
To create multiple environments, the :conf_master:`file_roots` option can be
expanded:
.. code-block:: yaml
file_roots:
base:
- /srv/salt/base
dev:
- /srv/salt/dev
qa:
@ -64,304 +134,235 @@ just the state tree, then the :conf_master:`file_roots` option can be expanded:
prod:
- /srv/salt/prod
Then our top file could reference the environments:
In the above, we declare three environments: ``dev``, ``qa`` and ``prod``.
Each environment has a single directory assigned to it.
Our top file references the environments:
.. code-block:: yaml
dev:
'webserver*dev*':
'webserver*':
- webserver
'db*dev*':
'db*':
- db
qa:
'webserver*qa*':
'webserver*':
- webserver
'db*qa*':
'db*':
- db
prod:
'webserver*prod*':
'webserver*':
- webserver
'db*prod*':
'db*':
- db
In this setup we have state trees in three of the four environments, and no
state tree in the ``base`` environment. Notice that the targets for the minions
specify environment data. In Salt the master determines who is in what
environment, and many environments can be crossed together. For instance, a
separate global state tree could be added to the ``base`` environment if it
suits your deployment:
As seen above, the top file now declares the three environments and for each,
targets are defined to map globs of minion IDs to state files. For example,
all minions which have an ID beginning with the string ``webserver`` will have the
webserver state from the requested environment assigned to it.
.. code-block:: yaml
In this manner, a proposed change to a state could first be made in a state
file in ``/srv/salt/dev`` and the applied to development webservers before moving
the state into QA by copying the state file into ``/srv/salt/qa``.
base:
'*':
- global
dev:
'webserver*dev*':
- webserver
'db*dev*':
- db
qa:
'webserver*qa*':
- webserver
'db*qa*':
- db
prod:
'webserver*prod*':
- webserver
'db*prod*':
- db
In this setup all systems will pull the global SLS from the base environment,
as well as pull from their respective environments. If you assign only one SLS
to a system, as in this example, a shorthand is also available:
Choosing an Environment to Target
=================================
The top file is used to assign a minion to an environment unless overridden
using the methods described below. The environment in the top file must match
an environment in :conf_master:`file_roots` in order for any states to be
applied to that minion. The states that will be applied to a minion in a given
environment can be viewed using the :py:func:`state.show_top
<salt.modules.state.show_top>` execution function.
Minions may be pinned to a particular environment by setting the ``environment``
value in the minion configuration file. In doing so, a minion will only
request files from the environment to which it is assigned.
The environment to use may also be dynamically selected at the time that
a ``salt``, ``salt-call`` or ``salt-ssh`` by passing passing a flag to the
execution module being called. This is most commonly done with
functions in the ``state`` module by using the ``saltenv=`` argument. For
example, to run a ``highstate`` on all minions, using the state files in
the ``prod`` state tree, run: ``salt '*' state.highstate saltenv=prod``.
.. note::
Not all functions accept ``saltenv`` as an argument See individual
function documentation to verify.
Shorthand
=========
If you assign only one SLS to a system, as in this example, a shorthand is
also available:
.. code-block:: yaml
base:
'*': global
dev:
'webserver*dev*': webserver
'db*dev*': db
'webserver*': webserver
'db*': db
qa:
'webserver*qa*': webserver
'db*qa*': db
'webserver*': webserver
'db*': db
prod:
'webserver*prod*': webserver
'db*prod*': db
'webserver*': webserver
'db*': db
.. note::
The top files from all defined environments will be compiled into a single
top file for all states. Top files are environment agnostic.
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.
.. _states-top-file_roots:
A clean and recommended setup for multiple environments would look like this:
.. code-block:: yaml
# Master file_roots configuration:
file_roots:
base:
- /srv/salt/base
dev:
- /srv/salt/dev
qa:
- /srv/salt/qa
prod:
- /srv/salt/prod
Then only place state trees in the dev, qa, and prod environments, leaving
the base environment open for generic file transfers. Then the top.sls file
would look something like this:
.. code-block:: yaml
dev:
'webserver*dev*':
- webserver
'db*dev*':
- db
qa:
'webserver*qa*':
- webserver
'db*qa*':
- db
prod:
'webserver*prod*':
- webserver
'db*prod*':
- db
Other Ways of Targeting Minions
===============================
Advanced Minion Targeting
=========================
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>`
and :doc:`node groups </topics/targeting/nodegroups>`.
Here is a slightly more complex top file example, showing the different types
Below is a slightly more complex top file example, showing the different types
of matches you can perform:
.. code-block:: yaml
# All files will be taken from the file path specified in the base
# environment in the ``file_roots`` configuration value.
base:
# All minions get the following three state files applied
'*':
- ldap-client
- networking
- salt.minion
# All minions which have an ID that begins with the phrase
# 'salt-master' will have an SLS file applied that is named
# 'master.sls' and is in the 'salt' directory, underneath
# the root specified in the ``base`` environment in the
# configuration value for ``file_roots``.
'salt-master*':
- salt.master
# Minions that have an ID matching the following regular
# expression will have the state file called 'web.sls' in the
# nagios/mon directory applied. Additionally, minions matching
# the regular expression will also have the 'server.sls' file
# in the apache/ directory applied.
# NOTE!
#
# Take note of the 'match' directive here, which tells Salt
# to treat the target string as a regex to be matched!
'^(memcache|web).(qa|prod).loc$':
- match: pcre
- nagios.mon.web
- apache.server
# Minions that have a grain set indicating that they are running
# the Ubuntu operating system will have the state file called
# 'ubuntu.sls' in the 'repos' directory applied.
#
# Again take note of the 'match' directive here which tells
# Salt to match against a grain instead of a minion ID.
'os:Ubuntu':
- match: grain
- repos.ubuntu
# Minions that are either RedHat or CentOS should have the 'epel.sls'
# state applied, from the 'repos/' directory.
'os:(RedHat|CentOS)':
- match: grain_pcre
- repos.epel
# The three minions with the IDs of 'foo', 'bar' and 'baz' should
# have 'database.sls' applied.
'foo,bar,baz':
- match: list
- database
# Any minion for which the pillar key 'somekey' is set and has a value
# of that key matching 'abc' will have the 'xyz.sls' state applied.
'somekey:abc':
- match: pillar
- xyz
# All minions which begin with the strings 'nag1' or any minion with
# a grain set called 'role' with the value of 'monitoring' will have
# the 'server.sls' state file applied from the 'nagios/' directory.
'nag1* or G@role:monitoring':
- match: compound
- nagios.server
In this example ``top.sls``, all minions get the ldap-client, networking, and
salt.minion states. Any minion with an id matching the ``salt-master*`` glob
will get the salt.master state. Any minion with ids matching the regular
expression ``^(memcache|web).(qa|prod).loc$`` will get the nagios.mon.web and
apache.server states. All Ubuntu minions will receive the repos.ubuntu state,
while all RHEL and CentOS minions will receive the repos.epel state. The
minions ``foo``, ``bar``, and ``baz`` will receive the database state. Any
minion with a pillar named ``somekey``, having a value of ``abc`` will receive
the xyz state. Finally, minions with ids matching the nag1* glob or with a
grain named ``role`` equal to ``monitoring`` will receive the nagios.server
state.
How Top Files Are Compiled
==========================
.. warning::
When using multiple environments, it is not necessary to create a top file for
each environment. The most common approach, and the easiest to maintain, is
to use a single top file placed in only one environment.
There is currently a known issue with the topfile compilation. The below
may not be completely valid until
https://github.com/saltstack/salt/issues/12483#issuecomment-64181598
is closed.
However, some workflows do call for multiple top files. In this case, top
files may be merged together to create ``high data`` for the state compiler
to use as a source to compile states on a minion.
As mentioned earlier, the top files in the different environments are compiled
into a single set of data. The way in which this is done follows a few rules,
which are important to understand when arranging top files in different
environments. The examples below all assume that the :conf_master:`file_roots`
are set as in the :ref:`above multi-environment example
<states-top-file_roots>`.
For the following discussion of top file compilation, assume the following
configuration:
1. The ``base`` environment's top file is processed first. Any environment which
is defined in the ``base`` top.sls as well as another environment's top file,
will use the instance of the environment configured in ``base`` and ignore
all other instances. In other words, the ``base`` top file is
authoritative when defining environments. Therefore, in the example below,
the ``dev`` section in ``/srv/salt/dev/top.sls`` would be completely
ignored.
``/srv/salt/base/top.sls:``
``/etc/salt/master``
.. code-block:: yaml
<snip>
file_roots:
first_env:
- /srv/salt/first
second_env:
- /srv/salt/second
base:
``/srv/salt/first/top.sls:``
.. code-block:: yaml
first_env:
'*':
- common
dev:
'webserver*dev*':
- webserver
'db*dev*':
- db
- first
second_env:
'*':
- second
``/srv/salt/dev/top.sls:``
The astute reader will ask how the state compiler resolves which should be
an obvious conflict if a minion is not pinned to a particular environment
and if no environment argument is passed into a state function.
.. code-block:: yaml
Given the above, it is initially unclear whether ``first.sls`` will be applied
or whether ``second.sls`` will be applied in a ``salt '*' state.highstate`` command.
dev:
'10.10.100.0/24':
- match: ipcidr
- deployments.dev.site1
'10.10.101.0/24':
- match: ipcidr
- deployments.dev.site2
When conflicting keys arise, there are several configuration options which
control the behaviour of salt:
.. note::
The rules below assume that the environments being discussed were not
defined in the ``base`` top file.
- ``env_order``
Setting ``env_order`` will set the order in which environments are processed
by the state compiler.
2. If, for some reason, the ``base`` environment is not configured in the
``base`` environment's top file, then the other environments will be checked
in alphabetical order. The first top file found to contain a section for the
``base`` environment wins, and the other top files' ``base`` sections are
ignored. So, provided there is no ``base`` section in the ``base`` top file,
with the below two top files the ``dev`` environment would win out, and the
``common.centos`` SLS would not be applied to CentOS hosts.
- ``top_file_merging_strategy``
Can be set to ``same``, which will process only the top file from the environment
that the minion belongs to via the ``environment`` configuration setting or
the environment that is requested via the ``saltenv`` argument supported
by some functions in the ``state`` module.
``/srv/salt/dev/top.sls:``
Can also be set to ``merge``. This is the default. When set to ``merge``,
top files will be merged together. The order in which top files are
merged together can be controlled with ``env_order``.
.. code-block:: yaml
base:
'os:Ubuntu':
- common.ubuntu
dev:
'webserver*dev*':
- webserver
'db*dev*':
- db
``/srv/salt/qa/top.sls:``
.. code-block:: yaml
base:
'os:Ubuntu':
- common.ubuntu
'os:CentOS':
- common.centos
qa:
'webserver*qa*':
- webserver
'db*qa*':
- db
3. For environments other than ``base``, the top file in a given environment
will be checked for a section matching the environment's name. If one is
found, then it is used. Otherwise, the remaining (non-``base``) environments
will be checked in alphabetical order. In the below example, the ``qa``
section in ``/srv/salt/dev/top.sls`` will be ignored, but if
``/srv/salt/qa/top.sls`` were cleared or removed, then the states configured
for the ``qa`` environment in ``/srv/salt/dev/top.sls`` will be applied.
``/srv/salt/dev/top.sls:``
.. code-block:: yaml
dev:
'webserver*dev*':
- webserver
'db*dev*':
- db
qa:
'10.10.200.0/24':
- match: ipcidr
- deployments.qa.site1
'10.10.201.0/24':
- match: ipcidr
- deployments.qa.site2
``/srv/salt/qa/top.sls:``
.. code-block:: yaml
qa:
'webserver*qa*':
- webserver
'db*qa*':
- db
.. note::
When in doubt, the simplest way to configure your states is with a single
top.sls in the ``base`` environment.
- ``default_top``
If ``top_file_merging_strategy`` is set to ``same`` and an environment does
not contain a top file, the top file in the environment specified by
``default_top`` will be used instead.

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