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

Merge branch 'develop' into infra5292_fluent

Browse source
This commit is contained in:
Mike Place 2017-09-22 11:37:31 -06:00 • committed by GitHub
commit 522399b5c0
1523 changed files with 64005 additions and 25983 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
.github/CODEOWNERS vendored Normal file
View file

@ -0,0 +1,60 @@
# SALTSTACK CODE OWNERS
# See https://help.github.com/articles/about-codeowners/
# for more info about CODEOWNERS file
# Lines starting with '#' are comments.
# Each line is a file pattern followed by one or more owners.
# See https://help.github.com/articles/about-codeowners/
# for more info about the CODEOWNERS file
# Team Boto
salt/**/*boto* @saltstack/team-boto
# Team Core
salt/auth/ @saltstack/team-core
salt/cache/ @saltstack/team-core
salt/cli/ @saltstack/team-core
salt/client/* @saltstack/team-core
salt/config/* @saltstack/team-core
salt/daemons/ @saltstack/team-core
salt/pillar/ @saltstack/team-core
salt/loader.py @saltstack/team-core
salt/payload.py @saltstack/team-core
salt/**/master* @saltstack/team-core
salt/**/minion* @saltstack/team-core
# Team Cloud
salt/cloud/ @saltstack/team-cloud
salt/utils/openstack/ @saltstack/team-cloud
salt/utils/aws.py @saltstack/team-cloud
salt/**/*cloud* @saltstack/team-cloud
# Team NetAPI
salt/cli/api.py @saltstack/team-netapi
salt/client/netapi.py @saltstack/team-netapi
salt/netapi/ @saltstack/team-netapi
# Team Network
salt/proxy/ @saltstack/team-proxy
# Team SPM
salt/cli/spm.py @saltstack/team-spm
salt/spm/ @saltstack/team-spm
# Team SSH
salt/cli/ssh.py @saltstack/team-ssh
salt/client/ssh/ @saltstack/team-ssh
salt/runners/ssh.py @saltstack/team-ssh
salt/**/thin.py @saltstack/team-ssh
# Team State
salt/state.py @saltstack/team-state
# Team Transport
salt/transport/ @saltstack/team-transport
salt/utils/zeromq.py @saltstack/team-transport
# Team Windows
salt/**/*win* @saltstack/team-windows

4
.github/stale.yml vendored
View file

@ -1,8 +1,8 @@
# Probot Stale configuration file
# Number of days of inactivity before an issue becomes stale
# 1200 is approximately 3 years and 3 months
daysUntilStale: 1200
# 1000 is approximately 2 years and 9 months
daysUntilStale: 1000
# Number of days of inactivity before a stale issue is closed
daysUntilClose: 7

14
.mention-bot
View file

@ -1,5 +1,17 @@
{
"alwaysNotifyForPaths": [
{
"name": "ryan-lane",
"files": ["salt/**/*boto*.py"],
"skipTeamPrs": false
},
{
"name": "tkwilliams",
"files": ["salt/**/*boto*.py"],
"skipTeamPrs": false
}
],
"skipTitle": "Merge forward",
"userBlacklist": ["cvrebert", "markusgattol", "olliewalsh"]
"userBlacklist": ["cvrebert", "markusgattol", "olliewalsh", "basepi"]
}

12
README.rst
View file

@ -67,10 +67,11 @@ Engage SaltStack
`SaltConf`_, **User Groups and Meetups** - SaltStack has a vibrant and `global
community`_ of customers, users, developers and enthusiasts. Connect with other
Salted folks in your area of the world, or join `SaltConf16`_, the SaltStack
annual user conference, April 19-21 in Salt Lake City. Please let us know if
you would like to start a user group or if we should add your existing
SaltStack user group to this list by emailing: info@saltstack.com
Salted folks in your area of the world, or join `SaltConf`_, the SaltStack
annual user conference held in Salt Lake City. Please visit the `SaltConf`_ site
for details of our next conference. Also, please let us know if you would like
to start a user group or if we should add your existing SaltStack user group to
this list by emailing: info@saltstack.com
**SaltStack Training** - Get access to proprietary `SaltStack education
offerings`_ through instructor-led training offered on-site, virtually or at
@ -89,9 +90,8 @@ services`_ offerings.
* LinkedIn Group - `<https://www.linkedin.com/groups/4877160>`_
* Google+ - `<https://plus.google.com/b/112856352920437801867/+SaltStackInc/posts>`_
.. _SaltConf: http://www.youtube.com/user/saltstack
.. _global community: http://www.meetup.com/pro/saltstack/
.. _SaltConf16: http://saltconf.com/
.. _SaltConf: http://saltconf.com/
.. _SaltStack education offerings: http://saltstack.com/training/
.. _SaltStack Certified Engineer (SSCE): http://saltstack.com/certification/
.. _SaltStack professional services: http://saltstack.com/services/

11
conf/cloud
View file

@ -97,3 +97,14 @@
#
#delete_sshkeys: False
# Whether or not to include grains information in the /etc/salt/minion file
# which is generated when the minion is provisioned. For example...
# grains:
# salt-cloud:
# driver: ec2
# provider: my_ec2:ec2
# profile: micro_ec2
#
# Default: 'True'
#
#enable_cloud_grains: 'True'

2
conf/cloud.providers
View file

@ -3,7 +3,7 @@
# directory is identical.
#my-digitalocean-config:
# driver: digital_ocean
# driver: digitalocean
# client_key: wFGEwgregeqw3435gDger
# api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
# location: New York 1

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

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

95
conf/master
View file

@ -59,15 +59,14 @@
# Directory for custom modules. This directory can contain subdirectories for
# each of Salt's module types such as "runners", "output", "wheel", "modules",
# "states", "returners", etc.
#extension_modules: <no default>
# "states", "returners", "engines", "utils", etc.
#extension_modules: /var/cache/salt/master/extmods
# Directory for custom modules. This directory can contain subdirectories for
# each of Salt's module types such as "runners", "output", "wheel", "modules",
# "states", "returners", "engines", etc.
# "states", "returners", "engines", "utils", etc.
# Like 'extension_modules' but can take an array of paths
#module_dirs: <no default>
# - /var/cache/salt/minion/extmods
#module_dirs: []
# Verify and set permissions on configuration directories at startup:
#verify_env: True
@ -91,6 +90,10 @@
# Set the default outputter used by the salt command. The default is "nested".
#output: nested
# To set a list of additional directories to search for salt outputters, set the
# outputter_dirs option.
#outputter_dirs: []
# Set the default output file used by the salt command. Default is to output
# to the CLI and not to a file. Functions the same way as the "--out-file"
# CLI option, only sets this to a single file for all salt commands.
@ -99,6 +102,9 @@
# Return minions that timeout when running commands like test.ping
#show_timeout: True
# Tell the client to display the jid when a job is published.
#show_jid: False
# By default, output is colored. To disable colored output, set the color value
# to False.
#color: True
@ -294,6 +300,22 @@
##### Security settings #####
##########################################
# Enable passphrase protection of Master private key. Although a string value
# is acceptable; passwords should be stored in an external vaulting mechanism
# and retrieved via sdb. See https://docs.saltstack.com/en/latest/topics/sdb/.
# Passphrase protection is off by default but an example of an sdb profile and
# query is as follows.
# masterkeyring:
# driver: keyring
# service: system
#
# key_pass: sdb://masterkeyring/key_pass
# Enable passphrase protection of the Master signing_key. This only applies if
# master_sign_pubkey is set to True. This is disabled by default.
# master_sign_pubkey: True
# signing_key_pass: sdb://masterkeyring/signing_pass
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
@ -304,6 +326,9 @@
# public keys from the minions. Note that this is insecure.
#auto_accept: False
# The size of key that should be generated when creating new keys.
#keysize: 2048
# Time in minutes that an incoming public key with a matching name found in
# pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys
# are removed when the master checks the minion_autosign directory.
@ -454,6 +479,27 @@
# - /etc/salt/roster.d
# - /opt/salt/some/more/rosters
# The ssh password to log in with.
#ssh_passwd: ''
#The target system's ssh port number.
#ssh_port: 22
# Comma-separated list of ports to scan.
#ssh_scan_ports: 22
# Scanning socket timeout for salt-ssh.
#ssh_scan_timeout: 0.01
# Boolean to run command via sudo.
#ssh_sudo: False
# Number of seconds to wait for a response when establishing an SSH connection.
#ssh_timeout: 60
# The user to log in as.
#ssh_user: root
# The log file of the salt-ssh command:
#ssh_log_file: /var/log/salt/ssh
@ -467,6 +513,18 @@
# authentication with minions
#ssh_use_home_key: False
# Set this to True to default salt-ssh to run with ``-o IdentitiesOnly=yes``.
# This option is intended for situations where the ssh-agent offers many
# different identities and allows ssh to ignore those identities and use the
# only one specified in options.
#ssh_identities_only: False
# List-only nodegroups for salt-ssh. Each group must be formed as either a
# comma-separated list, or a YAML list. This option is useful to group minions
# into easy-to-target groups when using salt-ssh. These groups can then be
# targeted with the normal -N argument to salt-ssh.
#ssh_list_nodegroups: {}
##### Master Module Management #####
##########################################
# Manage how master side modules are loaded.
@ -474,6 +532,9 @@
# Add any additional locations to look for master runners:
#runner_dirs: []
# Add any additional locations to look for master utils:
#utils_dirs: []
# Enable Cython for master side modules:
#cython_enable: False
@ -535,6 +596,11 @@
# If set to 'changes', the output will be full unless the state didn't change.
#state_output: full
# The state_output_diff setting changes whether or not the output from
# successful states is returned. Useful when even the terse output of these
# states is cluttering the logs. Set it to True to ignore them.
#state_output_diff: False
# 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.
@ -575,6 +641,10 @@
# - /srv/salt
#
# The master_roots setting configures a master-only copy of the file_roots dictionary,
# used by the state compiler.
#master_roots: /srv/salt-master
# 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
@ -919,6 +989,21 @@
#pillar_cache_backend: disk
###### Reactor Settings #####
###########################################
# Define a salt reactor. See https://docs.saltstack.com/en/latest/topics/reactor/
#reactor: []
#Set the TTL for the cache of the reactor configuration.
#reactor_refresh_interval: 60
#Configure the number of workers for the runner/wheel in the reactor.
#reactor_worker_threads: 10
#Define the queue size for workers in the reactor.
#reactor_worker_hwm: 10000
##### Syndic settings #####
##########################################
# The Salt syndic is used to pass commands through a master from a higher

29
conf/minion
View file

@ -151,7 +151,11 @@
# Set the default outputter used by the salt-call command. The default is
# "nested".
#output: nested
#
# To set a list of additional directories to search for salt outputters, set the
# outputter_dirs option.
#outputter_dirs: []
# By default output is colored. To disable colored output, set the color value
# to False.
#color: True
@ -231,7 +235,7 @@
# cause sub minion process to restart.
#auth_safemode: False
# Ping Master to ensure connection is alive (minutes).
# Ping Master to ensure connection is alive (seconds).
#ping_interval: 0
# To auto recover minions if master changes IP address (DDNS)
@ -369,6 +373,9 @@
# interface: eth0
# cidr: '10.0.0.0/8'
# The number of minutes between mine updates.
#mine_interval: 60
# Windows platforms lack posix IPC and must rely on slower TCP based inter-
# process communications. Set ipc_mode to 'tcp' on such systems
#ipc_mode: ipc
@ -613,6 +620,9 @@
# you do so at your own risk!
#open_mode: False
# The size of key that should be generated when creating new keys.
#keysize: 2048
# Enable permissive access to the salt keys. This allows you to run the
# master or minion as root, but have a non-root group be given access to
# your pki_dir. To make the access explicit, root must belong to the group
@ -654,6 +664,21 @@
# ssl_version: PROTOCOL_TLSv1_2
###### Reactor Settings #####
###########################################
# Define a salt reactor. See https://docs.saltstack.com/en/latest/topics/reactor/
#reactor: []
#Set the TTL for the cache of the reactor configuration.
#reactor_refresh_interval: 60
#Configure the number of workers for the runner/wheel in the reactor.
#reactor_worker_threads: 10
#Define the queue size for workers in the reactor.
#reactor_worker_hwm: 10000
###### Thread settings #####
###########################################
# Disable multiprocessing support, by default when a minion receives a

1230
conf/suse/master Normal file
View file

File diff suppressed because it is too large Load diff

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

@ -255,8 +255,8 @@
<div class="col-sm-6">
<a href="https://saltstack.com/support" target="_blank"><img class="nolightbox footer-banner center" src="{{ pathto('_static/images/footer-support.png', 1) }}"/></a>
<a href="https://saltstack.com/saltstack-enterprise/" target="_blank"><img class="nolightbox footer-banner center" src="{{ pathto('_static/images/enterprise_ad.jpg', 1) }}"/></a>
<a href="http://saltconf.com" target="_blank"><img class="nolightbox footer-banner center" src="{{ pathto('_static/images/DOCBANNER.jpg', 1) }}"/></a>
</div>

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

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 790 KiB

25
doc/conf.py
View file

@ -72,6 +72,7 @@ MOCK_MODULES = [
'Crypto.Signature',
'Crypto.Signature.PKCS1_v1_5',
'M2Crypto',
'msgpack',
'yaml',
'yaml.constructor',
'yaml.nodes',
@ -244,9 +245,9 @@ on_saltstack = 'SALT_ON_SALTSTACK' in os.environ
project = 'Salt'
version = salt.version.__version__
latest_release = '2016.11.5' # latest release
previous_release = '2016.3.6' # latest release from previous branch
previous_release_dir = '2016.3' # path on web server for previous branch
latest_release = '2017.7.1' # latest release
previous_release = '2016.11.7' # latest release from previous branch
previous_release_dir = '2016.11' # path on web server for previous branch
next_release = '' # next release
next_release_dir = '' # path on web server for next release branch
@ -319,11 +320,21 @@ rst_prolog = """\
.. _`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}-x86-Setup.exe"><strong>Salt-Minion-{release}-x86-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-x86-Setup.exe.md5"><strong>md5</strong></a></p>
<p>Python2 x86: <a
href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py2-x86-Setup.exe"><strong>Salt-Minion-{release}-x86-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py2-x86-Setup.exe.md5"><strong>md5</strong></a></p>
<p>Python2 AMD64: <a
href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py2-AMD64-Setup.exe"><strong>Salt-Minion-{release}-AMD64-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py2-AMD64-Setup.exe.md5"><strong>md5</strong></a></p>
<p>Python3 x86: <a
href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py3-x86-Setup.exe"><strong>Salt-Minion-{release}-x86-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py3-x86-Setup.exe.md5"><strong>md5</strong></a></p>
<p>Python3 AMD64: <a
href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py3-AMD64-Setup.exe"><strong>Salt-Minion-{release}-AMD64-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-Py3-AMD64-Setup.exe.md5"><strong>md5</strong></a></p>
<p>AMD64: <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-AMD64-Setup.exe"><strong>Salt-Minion-{release}-AMD64-Setup.exe</strong></a>
| <a href="https://repo.saltstack.com/windows/Salt-Minion-{release}-AMD64-Setup.exe.md5"><strong>md5</strong></a></p>
.. |osxdownload| raw:: html

28
doc/faq.rst
View file

@ -190,6 +190,8 @@ PATH using a :mod:`file.symlink <salt.states.file.symlink>` state.
file.symlink:
- target: /usr/local/bin/foo
.. _which-version:
Can I run different versions of Salt on my Master and Minion?
-------------------------------------------------------------
@ -319,7 +321,27 @@ Restart using states
********************
Now we can apply the workaround to restart the Minion in reliable way.
The following example works on both UNIX-like and Windows operating systems:
The following example works on UNIX-like operating systems:
.. code-block:: jinja
{%- if grains['os'] != 'Windows' %
Restart Salt Minion:
cmd.run:
- name: 'salt-call --local service.restart salt-minion'
- bg: True
- onchanges:
- pkg: Upgrade Salt Minion
{%- endif %}
Note that restarting the ``salt-minion`` service on Windows operating systems is
not always necessary when performing an upgrade. The installer stops the
``salt-minion`` service, removes it, deletes the contents of the ``\salt\bin``
directory, installs the new code, re-creates the ``salt-minion`` service, and
starts it (by default). The restart step **would** be necessary during the
upgrade process, however, if the minion config was edited after the upgrade or
installation. If a minion restart is necessary, the state above can be edited
as follows:
.. code-block:: jinja
@ -335,8 +357,8 @@ The following example works on both UNIX-like and Windows operating systems:
- pkg: Upgrade Salt Minion
However, it requires more advanced tricks to upgrade from legacy version of
Salt (before ``2016.3.0``), where executing commands in the background is not
supported:
Salt (before ``2016.3.0``) on UNIX-like operating systems, where executing
commands in the background is not supported:
.. code-block:: jinja

1
doc/man/salt.7
View file

@ -10795,6 +10795,7 @@ cmd_whitelist_glob:
.UNINDENT
.UNINDENT
.SS Thread Settings
.SS \fBmultiprocessing\fP
.sp
Default: \fBTrue\fP
.sp

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

@ -19,5 +19,4 @@ auth modules
pki
rest
sharedsecret
stormpath
yubico

6
doc/ref/auth/all/salt.auth.stormpath.rst
View file

@ -1,6 +0,0 @@
===================
salt.auth.stormpath
===================
.. automodule:: salt.auth.stormpath
:members:

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

@ -22,6 +22,7 @@ beacon modules
load
log
memusage
napalm_beacon
network_info
network_settings
pkg

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

@ -0,0 +1,6 @@
==========================
salt.beacons.napalm_beacon
==========================
.. automodule:: salt.beacons.napalm_beacon
:members:

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

@ -33,6 +33,10 @@ Output Options
Write the output to the specified file.
.. option:: --out-file-append, --output-file-append
Append the output to the specified file.
.. option:: --no-color
Disable all colored output
@ -46,3 +50,14 @@ Output Options
``green`` denotes success, ``red`` denotes failure, ``blue`` denotes
changes and success and ``yellow`` denotes a expected future change in configuration.
.. option:: --state-output=STATE_OUTPUT, --state_output=STATE_OUTPUT
Override the configured state_output value for minion
output. One of 'full', 'terse', 'mixed', 'changes' or
'filter'. Default: 'none'.
.. option:: --state-verbose=STATE_VERBOSE, --state_verbose=STATE_VERBOSE
Override the configured state_verbose value for minion
output. Set to True or False. Default: none.

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

@ -136,7 +136,7 @@ Query Options
.. versionadded:: 2014.7.0
Display a list of configured profiles. Pass in a cloud provider to view
the provider's associated profiles, such as ``digital_ocean``, or pass in
the provider's associated profiles, such as ``digitalocean``, or pass in
``all`` to list all the configured profiles.

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

@ -39,6 +39,13 @@ specified target expression.
desitination will be assumed to be a directory. Finally, recursion is now
supported, allowing for entire directories to be copied.
.. versionchanged:: 2016.11.7,2017.7.2
Reverted back to the old copy mode to preserve backward compatibility. The
new functionality added in 2016.6.6 and 2017.7.0 is now available using the
``-C`` or ``--chunked`` CLI arguments. Note that compression, recursive
copying, and support for copying large files is only available in chunked
mode.
Options
=======
@ -56,9 +63,16 @@ Options
.. include:: _includes/target-selection.rst
.. option:: -C, --chunked
Use new chunked mode to copy files. This mode supports large files, recursive
directories copying and compression.
.. versionadded:: 2016.11.7,2017.7.2
.. option:: -n, --no-compression
Disable gzip compression.
Disable gzip compression in chunked mode.
.. versionadded:: 2016.3.7,2016.11.6,2017.7.0

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

@ -81,7 +81,7 @@ Options
Pass in an external authentication medium to validate against. The
credentials will be prompted for. The options are `auto`,
`keystone`, `ldap`, `pam`, and `stormpath`. Can be used with the -T
`keystone`, `ldap`, and `pam`. Can be used with the -T
option.
.. option:: -T, --make-token

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

@ -13,7 +13,7 @@ Full list of Salt Cloud modules
aliyun
azurearm
cloudstack
digital_ocean
digitalocean
dimensiondata
ec2
gce

4
doc/ref/clouds/all/salt.cloud.clouds.digital_ocean.rst
View file

@ -1,6 +1,6 @@
===============================
salt.cloud.clouds.digital_ocean
salt.cloud.clouds.digitalocean
===============================
.. automodule:: salt.cloud.clouds.digital_ocean
.. automodule:: salt.cloud.clouds.digitalocean
:members:

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

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

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

@ -94,64 +94,6 @@ The user to run the Salt processes
user: root
.. conf_master:: max_open_files
``max_open_files``
------------------
Default: ``100000``
Each minion connecting to the master uses AT LEAST one file descriptor, the
master subscription connection. If enough minions connect you might start
seeing on the console(and then salt-master crashes):
.. code-block:: bash
Too many open files (tcp_listener.cpp:335)
Aborted (core dumped)
.. code-block:: yaml
max_open_files: 100000
By default this value will be the one of `ulimit -Hn`, i.e., the hard limit for
max open files.
To set a different value than the default one, uncomment, and configure this
setting. Remember that this value CANNOT be higher than the hard limit. Raising
the hard limit depends on the OS and/or distribution, a good way to find the
limit is to search the internet for something like this:
.. code-block:: text
raise max open files hard limit debian
.. conf_master:: worker_threads
``worker_threads``
------------------
Default: ``5``
The number of threads to start for receiving commands and replies from minions.
If minions are stalling on replies because you have many minions, raise the
worker_threads value.
Worker threads should not be put below 3 when using the peer system, but can
drop down to 1 worker otherwise.
.. note::
When the master daemon starts, it is expected behaviour to see
multiple salt-master processes, even if 'worker_threads' is set to '1'. At
a minimum, a controlling process will start along with a Publisher, an
EventPublisher, and a number of MWorker processes will be started. The
number of MWorker processes is tuneable by the 'worker_threads'
configuration value while the others are not.
.. code-block:: yaml
worker_threads: 5
.. conf_master:: ret_port
``ret_port``
@ -241,13 +183,16 @@ The directory to store the pki authentication keys.
Directory for custom modules. This directory can contain subdirectories for
each of Salt's module types such as ``runners``, ``output``, ``wheel``,
``modules``, ``states``, ``returners``, ``engines``, etc. This path is appended to
:conf_master:`root_dir`.
``modules``, ``states``, ``returners``, ``engines``, ``utils``, etc.
This path is appended to :conf_master:`root_dir`.
.. code-block:: yaml
extension_modules: /root/salt_extmods
.. conf_master:: extmod_whitelist
.. conf_master:: extmod_blacklist
``extmod_whitelist/extmod_blacklist``
-------------------------------------
@ -289,6 +234,7 @@ Valid options:
- clouds
- tops
- roster
- tokens
.. conf_master:: module_dirs
@ -393,6 +339,19 @@ Default: ``nested``
Set the default outputter used by the salt command.
.. conf_master:: outputter_dirs
``outputter_dirs``
------------------
Default: ``[]``
A list of additional directories to search for salt outputters in.
.. code-block:: yaml
outputter_dirs: []
.. conf_master:: output_file
``output_file``
@ -408,6 +367,32 @@ CLI option, only sets this to a single file for all salt commands.
output_file: /path/output/file
.. conf_master:: show_timeout
``show_timeout``
----------------
Default: ``True``
Tell the client to show minions that have timed out.
.. code-block:: yaml
show_timeout: True
.. conf_master:: show_jid
``show_jid``
------------
Default: ``False``
Tell the client to display the jid when a job is published.
.. code-block:: yaml
show_jid: False
.. conf_master:: color
``color``
@ -819,6 +804,32 @@ that connect to a master via localhost.
presence_events: False
.. conf_master:: ping_on_rotate
``ping_on_rotate``
------------------
Default: ``False``
By default, the master AES key rotates every 24 hours. The next command
following a key rotation will trigger a key refresh from the minion which may
result in minions which do not respond to the first command after a key refresh.
To tell the master to ping all minions immediately after an AES key refresh,
set ``ping_on_rotate`` to ``True``. This should mitigate the issue where a
minion does not appear to initially respond after a key is rotated.
Note that ping_on_rotate may cause high load on the master immediately after
the key rotation event as minions reconnect. Consider this carefully if this
salt master is managing a large number of minions.
If disabled, it is recommended to handle this event by listening for the
``aes_key_rotate`` event with the ``key`` tag and acting appropriately.
.. code-block:: yaml
ping_on_rotate: False
.. conf_master:: transport
``transport``
@ -837,6 +848,8 @@ what you are doing! Transports are explained in :ref:`Salt Transports
transport: zeromq
.. conf_master:: transport_opts
``transport_opts``
------------------
@ -855,6 +868,95 @@ what you are doing! Transports are explained in :ref:`Salt Transports
ret_port: 4606
zeromq: []
.. conf_master:: sock_pool_size
``sock_pool_size``
------------------
Default: 1
To avoid blocking waiting while writing a data to a socket, we support
socket pool for Salt applications. For example, a job with a large number
of target host list can cause long period blocking waiting. The option
is used by ZMQ and TCP transports, and the other transport methods don't
need the socket pool by definition. Most of Salt tools, including CLI,
are enough to use a single bucket of socket pool. On the other hands,
it is highly recommended to set the size of socket pool larger than 1
for other Salt applications, especially Salt API, which must write data
to socket concurrently.
.. code-block:: yaml
sock_pool_size: 15
.. conf_master:: ipc_mode
``ipc_mode``
------------
Default: ``ipc``
The ipc strategy. (i.e., sockets versus tcp, etc.) Windows platforms lack
POSIX IPC and must rely on TCP based inter-process communications. ``ipc_mode``
is set to ``tcp`` by default on Windows.
.. code-block:: yaml
ipc_mode: ipc
.. conf_master::
``tcp_master_pub_port``
-----------------------
Default: ``4512``
The TCP port on which events for the master should be published if ``ipc_mode`` is TCP.
.. code-block:: yaml
tcp_master_pub_port: 4512
.. conf_master:: tcp_master_pull_port
``tcp_master_pull_port``
------------------------
Default: ``4513``
The TCP port on which events for the master should be pulled if ``ipc_mode`` is TCP.
.. code-block:: yaml
tcp_master_pull_port: 4513
.. conf_master:: tcp_master_publish_pull
``tcp_master_publish_pull``
---------------------------
Default: ``4514``
The TCP port on which events for the master should be pulled fom and then republished onto
the event bus on the master.
.. code-block:: yaml
tcp_master_publish_pull: 4514
.. conf_master:: tcp_master_workers
``tcp_master_workers``
----------------------
Default: ``4515``
The TCP port for ``mworkers`` to connect to on the master.
.. code-block:: yaml
tcp_master_workers: 4515
.. _salt-ssh-configuration:
@ -874,6 +976,97 @@ Pass in an alternative location for the salt-ssh roster file.
roster_file: /root/roster
.. conf_master:: ssh_passwd
``ssh_passwd``
--------------
Default: ``''``
The ssh password to log in with.
.. code-block:: yaml
ssh_passwd: ''
.. conf_master:: ssh_port
``ssh_port``
------------
Default: ``22``
The target system's ssh port number.
.. code-block:: yaml
ssh_port: 22
.. conf_master:: ssh_scan_ports
``ssh_scan_ports``
------------------
Default: ``22``
Comma-separated list of ports to scan.
.. code-block:: yaml
ssh_scan_ports: 22
.. conf_master:: ssh_scan_timeout
``ssh_scan_timeout``
--------------------
Default: ``0.01``
Scanning socket timeout for salt-ssh.
.. code-block:: yaml
ssh_scan_timeout: 0.01
.. conf_master:: ssh_sudo
``ssh_sudo``
------------
Default: ``False``
Boolean to run command via sudo.
.. code-block:: yaml
ssh_sudo: False
.. conf_master:: ssh_timeout
``ssh_timeout``
---------------
Default: ``60``
Number of seconds to wait for a response when establishing an SSH connection.
.. code-block:: yaml
ssh_timeout: 60
.. conf_master:: ssh_user
``ssh_user``
------------
Default: ``root``
The user to log in as.
.. code-block:: yaml
ssh_user: root
.. conf_master:: ssh_log_file
``ssh_log_file``
@ -905,6 +1098,8 @@ overridden on a per-minion basis in the roster (``minion_opts``)
ssh_minion_opts:
gpg_keydir: /root/gpg
.. conf_master:: ssh_use_home_key
``ssh_use_home_key``
--------------------
@ -917,6 +1112,41 @@ authentication with minions
ssh_use_home_key: False
.. conf_master:: ssh_identities_only
``ssh_identities_only``
-----------------------
Default: ``False``
Set this to ``True`` to default salt-ssh to run with ``-o IdentitiesOnly=yes``. This
option is intended for situations where the ssh-agent offers many different identities
and allows ssh to ignore those identities and use the only one specified in options.
.. code-block:: yaml
ssh_identities_only: False
.. conf_master:: ssh_list_nodegroups
``ssh_list_nodegroups``
-----------------------
Default: ``{}``
List-only nodegroups for salt-ssh. Each group must be formed as either a comma-separated
list, or a YAML list. This option is useful to group minions into easy-to-target groups
when using salt-ssh. These groups can then be targeted with the normal -N argument to
salt-ssh.
.. code-block:: yaml
ssh_list_nodegroups:
groupA: minion1,minion2
groupB: minion1,minion3
.. conf_master:: thin_extra_mods
``thin_extra_mods``
-------------------
@ -973,6 +1203,19 @@ public keys from minions.
auto_accept: False
.. conf_master:: keysize
``keysize``
-----------
Default: ``2048``
The size of key that should be generated when creating new keys.
.. code-block:: yaml
keysize: 2048
.. conf_master:: autosign_timeout
``autosign_timeout``
@ -1017,6 +1260,24 @@ minion IDs for which keys will automatically be rejected. Will override both
membership in the :conf_master:`autosign_file` and the
:conf_master:`auto_accept` setting.
.. conf_master:: permissive_pki_access
``permissive_pki_access``
-------------------------
Default: ``False``
Enable permissive access to the salt keys. This allows you to run the
master or minion as root, but have a non-root group be given access to
your pki_dir. To make the access explicit, root must belong to the group
you've given access to. This is potentially quite insecure. If an autosign_file
is specified, enabling permissive_pki_access will allow group access to that
specific file.
.. code-block:: yaml
permissive_pki_access: False
.. conf_master:: publisher_acl
``publisher_acl``
@ -1059,6 +1320,20 @@ This is completely disabled by default.
- cmd.*
- test.echo
.. conf_master:: sudo_acl
``sudo_acl``
------------
Default: ``False``
Enforce ``publisher_acl`` and ``publisher_acl_blacklist`` when users have sudo
access to the salt command.
.. code-block:: yaml
sudo_acl: False
.. conf_master:: external_auth
``external_auth``
@ -1243,6 +1518,19 @@ Do not disable this unless it is absolutely clear what this does.
rotate_aes_key: True
.. conf_master:: publish_session
``publish_session``
-------------------
Default: ``86400``
The number of seconds between AES key rotations on the master.
.. code-block:: yaml
publish_session: Default: 86400
.. conf_master:: ssl
``ssl``
@ -1273,6 +1561,24 @@ constant names without ssl module prefix: ``CERT_REQUIRED`` or ``PROTOCOL_SSLv23
``allow_minion_key_revoke``
---------------------------
Default: ``False``
By default, the master deletes its cache of minion data when the key for that
minion is removed. To preserve the cache after key deletion, set
``preserve_minion_cache`` to True.
WARNING: This may have security implications if compromised minions auth with
a previous deleted minion ID.
.. code-block:: yaml
preserve_minion_cache: False
.. conf_master:: allow_minion_key_revoke
``allow_minion_key_revoke``
---------------------------
Default: ``True``
Controls whether a minion can request its own key revocation. When True
@ -1285,6 +1591,127 @@ the master will drop the request and the minion's key will remain accepted.
rotate_aes_key: True
Master Large Scale Tuning Settings
==================================
.. conf_master:: max_open_files
``max_open_files``
------------------
Default: ``100000``
Each minion connecting to the master uses AT LEAST one file descriptor, the
master subscription connection. If enough minions connect you might start
seeing on the console(and then salt-master crashes):
.. code-block:: bash
Too many open files (tcp_listener.cpp:335)
Aborted (core dumped)
.. code-block:: yaml
max_open_files: 100000
By default this value will be the one of `ulimit -Hn`, i.e., the hard limit for
max open files.
To set a different value than the default one, uncomment, and configure this
setting. Remember that this value CANNOT be higher than the hard limit. Raising
the hard limit depends on the OS and/or distribution, a good way to find the
limit is to search the internet for something like this:
.. code-block:: text
raise max open files hard limit debian
.. conf_master:: worker_threads
``worker_threads``
------------------
Default: ``5``
The number of threads to start for receiving commands and replies from minions.
If minions are stalling on replies because you have many minions, raise the
worker_threads value.
Worker threads should not be put below 3 when using the peer system, but can
drop down to 1 worker otherwise.
.. note::
When the master daemon starts, it is expected behaviour to see
multiple salt-master processes, even if 'worker_threads' is set to '1'. At
a minimum, a controlling process will start along with a Publisher, an
EventPublisher, and a number of MWorker processes will be started. The
number of MWorker processes is tuneable by the 'worker_threads'
configuration value while the others are not.
.. code-block:: yaml
worker_threads: 5
.. conf_master:: pub_hwm
``pub_hwm``
-----------
Default: ``1000``
The zeromq high water mark on the publisher interface.
.. code-block:: yaml
pub_hwm: 1000
.. conf_master:: zmq_backlog
``zmq_backlog``
---------------
Default: ``1000``
The listen queue size of the ZeroMQ backlog.
.. code-block:: yaml
zmq_backlog: 1000
.. conf_master:: salt_event_pub_hwm
.. conf_master:: event_publisher_pub_hwm
``salt_event_pub_hwm`` and ``event_publisher_pub_hwm``
------------------------------------------------------
These two ZeroMQ High Water Mark settings, ``salt_event_pub_hwm`` and
``event_publisher_pub_hwm`` are significant for masters with thousands of
minions. When these are insufficiently high it will manifest in random
responses missing in the CLI and even missing from the job cache. Masters
that have fast CPUs and many cores with appropriate ``worker_threads``
will not need these set as high.
The ZeroMQ high-water-mark for the ``SaltEvent`` pub socket default is:
.. code-block:: yaml
salt_event_pub_hwm: 20000
The ZeroMQ high-water-mark for the ``EventPublisher`` pub socket default is:
.. code-block:: yaml
event_publisher_pub_hwm: 10000
As an example, on single master deployment with 8,000 minions, 2.4GHz CPUs,
24 cores, and 32GiB memory has these settings:
.. code-block:: yaml
salt_event_pub_hwm: 128000
event_publisher_pub_hwm: 64000
.. _master-module-management:
Master Module Management
@ -1304,6 +1731,22 @@ Set additional directories to search for runner modules.
runner_dirs:
- /var/lib/salt/runners
.. conf_master:: utils_dirs
``utils_dirs``
---------------
.. versionadded:: Oxygen
Default: ``[]``
Set additional directories to search for util modules.
.. code-block:: yaml
utils_dirs:
- /var/lib/salt/utils
.. conf_master:: cython_enable
``cython_enable``
@ -1333,7 +1776,8 @@ Default: ``top.sls``
The state system uses a "top" file to tell the minions what environment to
use and what modules to use. The state_top file is defined relative to the
root of the base environment.
root of the base environment. The value of "state_top" is also used for the
pillar top file
.. code-block:: yaml
@ -1577,6 +2021,21 @@ If set to 'changes', the output will be full unless the state didn't change.
state_output: full
.. conf_master:: state_output_diff
``state_output_diff``
---------------------
Default: ``False``
The state_output_diff setting changes whether or not the output from
successful states is returned. Useful when even the terse output of these
states is cluttering the logs. Set it to True to ignore them.
.. code-block:: yaml
state_output_diff: False
.. conf_master:: state_aggregate
``state_aggregate``
@ -1889,6 +2348,19 @@ Example:
For masterless Salt, this parameter must be specified in the minion config
file.
.. conf_master:: master_roots
``master_roots``
----------------
Default: ``/srv/salt-master``
A master-only copy of the file_roots dictionary, used by the state compiler.
.. code-block:: yaml
master_roots: /srv/salt-master
git: Git Remote File Server Backend
-----------------------------------
@ -2056,6 +2528,60 @@ gitfs remotes.
- dev:
- ref: develop
.. conf_master:: gitfs_disable_saltenv_mapping
``gitfs_disable_saltenv_mapping``
*********************************
.. versionadded:: Oxygen
Default: ``False``
When set to ``True``, all saltenv mapping logic is disregarded (aside from
which branch/tag is mapped to the ``base`` saltenv). To use any other
environments, they must then be defined using :ref:`per-saltenv configuration
parameters <gitfs-per-saltenv-config>`.
.. code-block:: yaml
gitfs_disable_saltenv_mapping: True
.. note::
This is is a global configuration option, see :ref:`here
<gitfs-per-remote-config>` for examples of configuring it for individual
repositories.
.. conf_master:: gitfs_ref_types
``gitfs_ref_types``
*******************
.. versionadded:: Oxygen
Default: ``['branch', 'tag', 'sha']``
This option defines what types of refs are mapped to fileserver environments
(i.e. saltenvs). It also sets the order of preference when there are
ambiguously-named refs (i.e. when a branch and tag both have the same name).
The below example disables mapping of both tags and SHAs, so that only branches
are mapped as saltenvs:
.. code-block:: yaml
gitfs_ref_types:
- branch
.. note::
This is is a global configuration option, see :ref:`here
<gitfs-per-remote-config>` for examples of configuring it for individual
repositories.
.. note::
``sha`` is special in that it will not show up when listing saltenvs (e.g.
with the :py:func:`fileserver.envs <salt.runners.fileserver.envs>` runner),
but works within states and with :py:func:`cp.cache_file
<salt.modules.cp.cache_file>` to retrieve a file from a specific git SHA.
.. conf_master:: gitfs_saltenv_whitelist
``gitfs_saltenv_whitelist``
@ -2944,6 +3470,26 @@ configuration.
pillar_opts: False
.. conf_master:: pillar_safe_render_error
``pillar_safe_render_error``
----------------------------
Default: ``True``
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:
.. code-block:: shell
Rendering SLS 'my.sls' failed. Please see master log for details.
.. code-block:: yaml
pillar_safe_render_error: True
.. _master-configuration-ext-pillar:
.. conf_master:: ext_pillar
@ -3241,7 +3787,7 @@ they were created by a different master.
Default: ``True``
Normally, when processing :ref:`git_pillar remotes
<git-pillar-2015-8-0-and-later>`, if more than one repo under the same ``git``
<git-pillar-configuration>`, if more than one repo under the same ``git``
section in the ``ext_pillar`` configuration refers to the same pillar
environment, then each repo in a given environment will have access to the
other repos' files to be referenced in their top files. However, it may be
@ -3614,6 +4160,62 @@ can be utilized:
pillar_cache_backend: disk
Master Reactor Settings
=======================
.. conf_master:: reactor
``reactor``
-----------
Default: ``[]``
Defines a salt reactor. See the :ref:`Reactor <reactor>` documentation for more
information.
.. code-block:: yaml
reactor: []
.. conf_master:: reactor_refresh_interval
``reactor_refresh_interval``
----------------------------
Default: ``60``
The TTL for the cache of the reactor configuration.
.. code-block:: yaml
reactor_refresh_interval: 60
.. conf_master:: reactor_worker_threads
``reactor_worker_threads``
--------------------------
Default: ``10``
The number of workers for the runner/wheel in the reactor.
.. code-block:: yaml
reactor_worker_threads: 10
.. conf_master:: reactor_worker_hwm
``reactor_worker_hwm``
----------------------
Default: ``10000``
The queue size for workers in the reactor.
.. code-block:: yaml
reactor_worker_hwm: 10000
.. _syndic-server-settings:
Syndic Server Settings
@ -4080,6 +4682,63 @@ option then the master will log a warning message.
- /etc/roles/webserver
Keepalive Settings
==================
.. conf_master:: tcp_keepalive
``tcp_keepalive``
-----------------
Default: ``True``
The tcp keepalive interval to set on TCP ports. This setting can be used to tune Salt
connectivity issues in messy network environments with misbehaving firewalls.
.. code-block:: yaml
tcp_keepalive: True
.. conf_master:: tcp_keepalive_cnt
``tcp_keepalive_cnt``
---------------------
Default: ``-1``
Sets the ZeroMQ TCP keepalive count. May be used to tune issues with minion disconnects.
.. code-block:: yaml
tcp_keepalive_cnt: -1
.. conf_master:: tcp_keepalive_idle
``tcp_keepalive_idle``
----------------------
Default: ``300``
Sets ZeroMQ TCP keepalive idle. May be used to tune issues with minion disconnects.
.. code-block:: yaml
tcp_keepalive_idle: 300
.. conf_master:: tcp_keepalive_intvl
``tcp_keepalive_intvl``
-----------------------
Default: ``-1``
Sets ZeroMQ TCP keepalive interval. May be used to tune issues with minion disconnects.
.. code-block:: yaml
tcp_keepalive_intvl': -1
.. _winrepo-master-config-opts:
Windows Software Repo Settings
@ -4218,7 +4877,7 @@ URL of the repository:
.. code-block:: yaml
winrepo_remotes:
winrepo_remotes_ng:
- '<commit_id> https://github.com/saltstack/salt-winrepo-ng.git'
Replace ``<commit_id>`` with the SHA1 hash of a commit ID. Specifying a commit

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

@ -133,6 +133,24 @@ name) is set in the :conf_minion:`master` configuration setting.
master_uri_format: ip_only
.. conf_minion:: master_tops_first
``master_tops_first``
---------------------
.. versionadded:: Oxygen
Default: ``False``
SLS targets defined using the :ref:`Master Tops <master-tops-system>` system
are normally executed *after* any matches defined in the :ref:`Top File
<states-top>`. Set this option to ``True`` to have the minion execute the
:ref:`Master Tops <master-tops-system>` states first.
.. code-block:: yaml
master_tops_first: True
.. conf_minion:: master_type
``master_type``
@ -319,7 +337,7 @@ The user to run the Salt processes
.. conf_minion:: sudo_user
``sudo_user``
--------------
-------------
Default: ``''``
@ -610,6 +628,26 @@ With ``grains_deep_merge``, the result will be:
k1: v1
k2: v2
.. conf_minion:: grains_refresh_every
``grains_refresh_every``
------------------------
Default: ``0``
The ``grains_refresh_every`` setting allows for a minion to periodically
check its grains to see if they have changed and, if so, to inform the master
of the new grains. This operation is moderately expensive, therefore care
should be taken not to set this value too low.
Note: This value is expressed in minutes.
A value of 10 minutes is a reasonable default.
.. code-block:: yaml
grains_refresh_every: 0
.. conf_minion:: mine_enabled
``mine_enabled``
@ -643,7 +681,7 @@ return for the job cache.
mine_return_job: False
``mine_functions``
-------------------
------------------
Default: Empty
@ -661,6 +699,18 @@ Note these can be defined in the pillar for a minion as well.
interface: eth0
cidr: '10.0.0.0/8'
.. conf_minion:: mine_interval
``mine_interval``
-----------------
Default: ``60``
The number of minutes between mine updates.
.. code-block:: yaml
mine_interval: 60
.. conf_minion:: sock_dir
@ -675,6 +725,19 @@ The directory where Unix sockets will be kept.
sock_dir: /var/run/salt/minion
.. conf_minion:: outputter_dirs
``outputter_dirs``
------------------
Default: ``[]``
A list of additional directories to search for salt outputters in.
.. code-block:: yaml
outputter_dirs: []
.. conf_minion:: backup_mode
``backup_mode``
@ -719,6 +782,20 @@ seconds each iteration.
acceptance_wait_time_max: 0
.. conf_minion:: rejected_retry
``rejected_retry``
------------------
Default: ``False``
If the master rejects the minion's public key, retry instead of exiting.
Rejected keys will be handled the same as waiting on acceptance.
.. code-block:: yaml
rejected_retry: False
.. conf_minion:: random_reauth_delay
``random_reauth_delay``
@ -817,6 +894,20 @@ restart.
auth_safemode: False
.. conf_minion:: ping_interval
``ping_interval``
-----------------
Default: ``0``
Instructs the minion to ping its master(s) every n number of seconds. Used
primarily as a mitigation technique against minion disconnects.
.. code-block:: yaml
ping_interval: 0
.. conf_minion:: recon_default
``random_startup_delay``
@ -1135,7 +1226,7 @@ If certain returners should be disabled, this is the place
.. conf_minion:: enable_whitelist_modules
``whitelist_modules``
----------------------------
---------------------
Default: ``[]`` (Module whitelisting is disabled. Adding anything to the config option
will cause only the listed modules to be enabled. Modules not in the list will
@ -1227,6 +1318,20 @@ A list of extra directories to search for Salt renderers
render_dirs:
- /var/lib/salt/renderers
.. conf_minion:: utils_dirs
``utils_dirs``
--------------
Default: ``[]``
A list of extra directories to search for Salt utilities
.. code-block:: yaml
utils_dirs:
- /var/lib/salt/utils
.. conf_minion:: cython_enable
``cython_enable``
@ -1275,6 +1380,23 @@ below.
providers:
service: systemd
.. conf_minion:: modules_max_memory
``modules_max_memory``
----------------------
Default: ``-1``
Specify a max size (in bytes) for modules on import. This feature is currently
only supported on *nix operating systems and requires psutil.
.. code-block:: yaml
modules_max_memory: -1
.. conf_minion:: extmod_whitelist
.. conf_minion:: extmod_blacklist
``extmod_whitelist/extmod_blacklist``
-------------------------------------
@ -1297,8 +1419,8 @@ whitelist an empty list.
modules:
- specific_module
Valid options:
- beacons
- clouds
- sdb
@ -1444,6 +1566,52 @@ environment lacks one.
default_top: dev
.. conf_minion:: startup_states
``startup_states``
------------------
Default: ``''``
States to run when the minion daemon starts. To enable, set ``startup_states`` to:
- ``highstate``: Execute state.highstate
- ``sls``: Read in the sls_list option and execute the named sls files
- ``top``: Read top_file option and execute based on that file on the Master
.. code-block:: yaml
startup_states: ''
.. conf_minion:: sls_list
``sls_list``
------------
Default: ``[]``
List of states to run when the minion starts up if ``startup_states`` is set to ``sls``.
.. code-block:: yaml
sls_list:
- edit.vim
- hyper
.. conf_minion:: top_file
``top_file``
------------
Default: ``''``
Top file to execute if ``startup_states`` is set to ``top``.
.. code-block:: yaml
top_file: ''
State Management Settings
=========================
@ -1460,7 +1628,7 @@ The default renderer used for local state executions
renderer: yaml_jinja
.. conf_master:: test
.. conf_minion:: test
``test``
--------
@ -1504,6 +1672,22 @@ the output will be shortened to a single line.
state_output: full
.. conf_minion:: state_output_diff
``state_output_diff``
---------------------
Default: ``False``
The state_output_diff setting changes whether or not the output from
successful states is returned. Useful when even the terse output of these
states is cluttering the logs. Set it to True to ignore them.
.. code-block:: yaml
state_output_diff: False
.. conf_minion:: autoload_dynamic_modules
``autoload_dynamic_modules``
@ -1929,6 +2113,41 @@ It will be interpreted as megabytes.
file_recv_max_size: 100
.. conf_minion:: pass_to_ext_pillars
``pass_to_ext_pillars``
-----------------------
Specify a list of configuration keys whose values are to be passed to
external pillar functions.
Suboptions can be specified using the ':' notation (i.e. ``option:suboption``)
The values are merged and included in the ``extra_minion_data`` optional
parameter of the external pillar function. The ``extra_minion_data`` parameter
is passed only to the external pillar functions that have it explicitly
specified in their definition.
If the config contains
.. code-block:: yaml
opt1: value1
opt2:
subopt1: value2
subopt2: value3
pass_to_ext_pillars:
- opt1
- opt2: subopt1
the ``extra_minion_data`` parameter will be
.. code-block:: python
{'opt1': 'value1',
'opt2': {'subopt1': 'value2'}}
Security Settings
=================
@ -1962,6 +2181,35 @@ before the initial key exchange. The master fingerprint can be found by running
master_finger: 'ba:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:11:13'
.. conf_minion:: keysize
``keysize``
-----------
Default: ``2048``
The size of key that should be generated when creating new keys.
.. code-block:: yaml
keysize: 2048
.. conf_minion:: permissive_pki_access
``permissive_pki_access``
-------------------------
Default: ``False``
Enable permissive access to the salt keys. This allows you to run the
master or minion as root, but have a non-root group be given access to
your pki_dir. To make the access explicit, root must belong to the group
you've given access to. This is potentially quite insecure.
.. code-block:: yaml
permissive_pki_access: False
.. conf_minion:: verify_master_pubkey_sign
``verify_master_pubkey_sign``
@ -2069,7 +2317,7 @@ blocked. If `cmd_whitelist_glob` is NOT SET, then all shell commands are permitt
- 'cat /etc/fstab'
.. conf_master:: ssl
.. conf_minion:: ssl
``ssl``
-------
@ -2095,16 +2343,75 @@ constant names without ssl module prefix: ``CERT_REQUIRED`` or ``PROTOCOL_SSLv23
ssl_version: PROTOCOL_TLSv1_2
Reactor Settings
================
.. conf_minion:: reactor
``reactor``
-----------
Default: ``[]``
Defines a salt reactor. See the :ref:`Reactor <reactor>` documentation for more
information.
.. code-block:: yaml
reactor: []
.. conf_minion:: reactor_refresh_interval
``reactor_refresh_interval``
----------------------------
Default: ``60``
The TTL for the cache of the reactor configuration.
.. code-block:: yaml
reactor_refresh_interval: 60
.. conf_minion:: reactor_worker_threads
``reactor_worker_threads``
--------------------------
Default: ``10``
The number of workers for the runner/wheel in the reactor.
.. code-block:: yaml
reactor_worker_threads: 10
.. conf_minion:: reactor_worker_hwm
``reactor_worker_hwm``
----------------------
Default: ``10000``
The queue size for workers in the reactor.
.. code-block:: yaml
reactor_worker_hwm: 10000
Thread Settings
===============
.. conf_minion:: multiprocessing
``multiprocessing``
-------
Default: ``True``
If `multiprocessing` is enabled when a minion receives a
If ``multiprocessing`` is enabled when a minion receives a
publication a new process is spawned and the command is executed therein.
Conversely, if `multiprocessing` is disabled the new publication will be run
Conversely, if ``multiprocessing`` is disabled the new publication will be run
executed in a thread.
@ -2365,6 +2672,62 @@ option then the minion will log a warning message.
- /etc/roles/webserver
Keepalive Settings
==================
.. conf_minion:: tcp_keepalive
``tcp_keepalive``
-----------------
Default: ``True``
The tcp keepalive interval to set on TCP ports. This setting can be used to tune Salt
connectivity issues in messy network environments with misbehaving firewalls.
.. code-block:: yaml
tcp_keepalive: True
.. conf_minion:: tcp_keepalive_cnt
``tcp_keepalive_cnt``
---------------------
Default: ``-1``
Sets the ZeroMQ TCP keepalive count. May be used to tune issues with minion disconnects.
.. code-block:: yaml
tcp_keepalive_cnt: -1
.. conf_minion:: tcp_keepalive_idle
``tcp_keepalive_idle``
----------------------
Default: ``300``
Sets ZeroMQ TCP keepalive idle. May be used to tune issues with minion disconnects.
.. code-block:: yaml
tcp_keepalive_idle: 300
.. conf_minion:: tcp_keepalive_intvl
``tcp_keepalive_intvl``
-----------------------
Default: ``-1``
Sets ZeroMQ TCP keepalive interval. May be used to tune issues with minion disconnects.
.. code-block:: yaml
tcp_keepalive_intvl': -1
Frozen Build Update Settings
============================
@ -2466,6 +2829,36 @@ out.
winrepo_dir: 'D:\winrepo'
.. conf_minion:: winrepo_dir_ng
``winrepo_dir_ng``
------------------
.. versionadded:: 2015.8.0
A new :ref:`ng <windows-package-manager>` repo was added.
Default: ``/srv/salt/win/repo-ng``
Location on the minion where the :conf_minion:`winrepo_remotes_ng` are checked
out for 2015.8.0 and later minions.
.. code-block:: yaml
winrepo_dir_ng: /srv/salt/win/repo-ng
.. conf_minion:: winrepo_source_dir
``winrepo_source_dir``
----------------------
Default: ``salt://win/repo-ng/``
The source location for the winrepo sls files.
.. code-block:: yaml
winrepo_source_dir: salt://win/repo-ng/
.. conf_minion:: winrepo_cachefile
.. conf_minion:: win_repo_cachefile
@ -2518,3 +2911,33 @@ URL of the repository:
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_minion:: winrepo_remotes_ng
``winrepo_remotes_ng``
----------------------
.. versionadded:: 2015.8.0
A new :ref:`ng <windows-package-manager>` repo was added.
Default: ``['https://github.com/saltstack/salt-winrepo-ng.git']``
List of git repositories to checkout and include in the winrepo for
2015.8.0 and later minions.
.. code-block:: yaml
winrepo_remotes_ng:
- https://github.com/saltstack/salt-winrepo-ng.git
To specify a specific revision of the repository, prepend a commit ID to the
URL of the repository:
.. code-block:: yaml
winrepo_remotes_ng:
- '<commit_id> https://github.com/saltstack/salt-winrepo-ng.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.

50
doc/ref/configuration/proxy.rst
View file

@ -118,3 +118,53 @@ has to be closed after every command.
.. code-block:: yaml
proxy_always_alive: False
``proxy_merge_pillar_in_opts``
------------------------------
.. versionadded:: 2017.7.3
Default: ``False``.
Wheter the pillar data to be merged into the proxy configuration options.
As multiple proxies can run on the same server, we may need different
configuration options for each, while there's one single configuration file.
The solution is merging the pillar data of each proxy minion into the opts.
.. code-block:: yaml
proxy_merge_pillar_in_opts: True
``proxy_deep_merge_pillar_in_opts``
-----------------------------------
.. versionadded:: 2017.7.3
Default: ``False``.
Deep merge of pillar data into configuration opts.
This option is evaluated only when :conf_proxy:`proxy_merge_pillar_in_opts` is
enabled.
``proxy_merge_pillar_in_opts_strategy``
---------------------------------------
.. versionadded:: 2017.7.3
Default: ``smart``.
The strategy used when merging pillar configuration into opts.
This option is evaluated only when :conf_proxy:`proxy_merge_pillar_in_opts` is
enabled.
``proxy_mines_pillar``
----------------------
.. versionadded:: 2017.7.3
Default: ``True``.
Allow enabling mine details using pillar data. This evaluates the mine
configuration under the pillar, for the following regular minion options that
are also equally available on the proxy minion: :conf_minion:`mine_interval`,
and :conf_minion:`mine_functions`.

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

@ -44,6 +44,7 @@ execution modules
boto_apigateway
boto_asg
boto_cfn
boto_cloudfront
boto_cloudtrail
boto_cloudwatch
boto_cloudwatch_event
@ -97,6 +98,7 @@ execution modules
cytest
daemontools
data
datadog_api
ddns
deb_apache
deb_postgres
@ -197,6 +199,7 @@ execution modules
keyboard
keystone
kmod
kubernetes
launchctl
layman
ldap3
@ -298,6 +301,7 @@ execution modules
opkg
oracle
osquery
out
pacman
pagerduty
pagerduty_util
@ -323,6 +327,7 @@ execution modules
ps
publish
puppet
purefa
pushbullet
pushover_notify
pw_group
@ -397,7 +402,6 @@ execution modules
state
status
statuspage
stormpath
supervisord
suse_apache
svn
@ -415,6 +419,7 @@ execution modules
test
testinframod
test_virtual
textfsm_mod
timezone
tls
tomcat

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

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

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

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

4
doc/ref/modules/all/salt.modules.kernelpkg.rst
View file

@ -13,7 +13,7 @@ salt.modules.kernelpkg
Execution Module Used for
============================================ ========================================
:py:mod:`~salt.modules.kernelpkg_linux_apt` Debian/Ubuntu-based distros which use
``apt-get(8)`` for package management
``apt-get`` for package management
:py:mod:`~salt.modules.kernelpkg_linux_yum` RedHat-based distros and derivatives
using ``yum(8)`` or ``dnf(8)``
using ``yum`` or ``dnf``
============================================ ========================================

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

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

5
doc/ref/modules/all/salt.modules.out.rst Normal file
View file

@ -0,0 +1,5 @@
salt.modules.out module
=======================
.. automodule:: salt.modules.out
:members:

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

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

6
doc/ref/modules/all/salt.modules.stormpath.rst
View file

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

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

@ -3,4 +3,5 @@ salt.modules.test
=================
.. automodule:: salt.modules.test
:members:
:members:
:exclude-members: rand_str

5
doc/ref/modules/all/salt.modules.textfsm_mod.rst Normal file
View file

@ -0,0 +1,5 @@
salt.modules.textfsm_mod module
===============================
.. automodule:: salt.modules.textfsm_mod
:members:

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

@ -13,7 +13,7 @@ Writing Salt execution modules is straightforward.
A Salt execution module is a Python or `Cython`_ module placed in a directory
called ``_modules/`` at the root of the Salt fileserver. When using the default
fileserver backend (i.e. :py:mod:`roots <salt.fileserver.roots`), unless
fileserver backend (i.e. :py:mod:`roots <salt.fileserver.roots>`), unless
environments are otherwise defined in the :conf_master:`file_roots` config
option, the ``_modules/`` directory would be located in ``/srv/salt/_modules``
on most systems.
@ -209,6 +209,29 @@ default configuration file for the minion contains the information and format
used to pass data to the modules. :mod:`salt.modules.test`,
:file:`conf/minion`.
.. _module_init:
``__init__`` Function
---------------------
If you want your module to have different execution modes based on minion
configuration, you can use the ``__init__(opts)`` function to perform initial
module setup. The parameter ``opts`` is the complete minion configuration,
as also available in the ``__opts__`` dict.
.. code-block:: python
'''
Cheese module initialization example
'''
def __init__(opts):
'''
Allow foreign imports if configured to do so
'''
if opts.get('cheese.allow_foreign', False):
_enable_foreign_products()
Strings and Unicode
===================
@ -273,8 +296,9 @@ module is not loaded. ``False`` lets the module perform system checks and
prevent loading if dependencies are not met.
Since ``__virtual__`` is called before the module is loaded, ``__salt__`` will
be unavailable as it will not have been packed into the module at this point in
time.
be unreliable as not all modules will be available at this point in time. The
``__pillar`` and ``__grains__`` :ref:`"dunder" dictionaries <dunder-dictionaries>`
are available however.
.. note::
Modules which return a string from ``__virtual__`` that is already used by
@ -313,10 +337,14 @@ the case when the dependency is unavailable.
else:
return False, 'The cheese execution module cannot be loaded: enzymes unavailable.'
def slice():
pass
.. code-block:: python
'''
Cheese state module
Cheese state module. Note that this works in state modules because it is
guaranteed that execution modules are loaded first
'''
def __virtual__():
@ -401,10 +429,33 @@ similar to the following:
Confine this module to Mac OS with Homebrew.
'''
if salt.utils.which('brew') and __grains__['os'] == 'MacOS':
if salt.utils.path.which('brew') and __grains__['os'] == 'MacOS':
return __virtualname__
return False
The ``__virtual__()`` function can return a ``True`` or ``False`` boolean, a tuple,
or a string. If it returns a ``True`` value, this ``__virtualname__`` module-level
attribute can be set as seen in the above example. This is the string that the module
should be referred to as.
When ``__virtual__()`` returns a tuple, the first item should be a boolean and the
second should be a string. This is typically done when the module should not load. The
first value of the tuple is ``False`` and the second is the error message to display
for why the module did not load.
For example:
.. code-block:: python
def __virtual__():
'''
Only load if git exists on the system
'''
if salt.utils.path.which('git') is None:
return (False,
'The git execution module cannot be loaded: git unavailable.')
else:
return True
Documentation
=============

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

@ -146,8 +146,10 @@ Here is a simple YAML renderer example:
import yaml
from salt.utils.yamlloader import SaltYamlSafeLoader
from salt.ext import six
def render(yaml_data, saltenv='', sls='', **kws):
if not isinstance(yaml_data, basestring):
if not isinstance(yaml_data, six.string_types):
yaml_data = yaml_data.read()
data = yaml.load(
yaml_data,

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

@ -122,7 +122,7 @@ This example, simplified from the pkg state, shows how to create mod_aggregate f
for chunk in chunks:
# The state runtime uses "tags" to track completed jobs, it may
# look familiar with the _|-
tag = salt.utils.gen_state_tag(chunk)
tag = __utils__['state.gen_tag'](chunk)
if tag in running:
# Already ran the pkg state, skip aggregation
continue

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

@ -31,6 +31,7 @@ state modules
boto_apigateway
boto_asg
boto_cfn
boto_cloudfront
boto_cloudtrail
boto_cloudwatch_alarm
boto_cloudwatch_event
@ -74,6 +75,10 @@ state modules
dellchassis
disk
docker
docker_container
docker_image
docker_network
docker_volume
drac
elasticsearch
elasticsearch_index
@ -132,6 +137,7 @@ state modules
keyboard
keystone
kmod
kubernetes
layman
ldap
libcloud_dns
@ -174,6 +180,7 @@ state modules
netusers
network
netyang
nfs_export
nftables
npm
ntp
@ -245,7 +252,6 @@ state modules
stateconf
status
statuspage
stormpath_account
supervisord
svn
sysctl

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

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

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

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

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

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

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

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

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

@ -519,7 +519,8 @@ runas
.. versionadded:: 2017.7.0
The ``runas`` global option is used to set the user which will be used to run the command in the ``cmd.run`` module.
The ``runas`` global option is used to set the user which will be used to run
the command in the ``cmd.run`` module.
.. code-block:: yaml
@ -532,6 +533,26 @@ The ``runas`` global option is used to set the user which will be used to run th
In the above state, the pip command run by ``cmd.run`` will be run by the daniel user.
runas_password
~~~~~~~~~~~~~~
.. versionadded:: 2017.7.2
The ``runas_password`` global option is used to set the password used by the
runas global option. This is required by ``cmd.run`` on Windows when ``runas``
is specified. It will be set when ``runas_password`` is defined in the state.
.. code-block:: yaml
run_script:
cmd.run:
- name: Powershell -NonInteractive -ExecutionPolicy Bypass -File C:\\Temp\\script.ps1
- runas: frank
- runas_password: supersecret
In the above state, the Powershell script run by ``cmd.run`` will be run by the
frank user with the password ``supersecret``.
.. _requisites-require-in:
.. _requisites-watch-in:
.. _requisites-onchanges-in:

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

@ -135,21 +135,30 @@ A State Module must return a dict containing the following keys/values:
``test=True``, and changes would have been made if the state was not run in
test mode.
+--------------------+-----------+-----------+
| | live mode | test mode |
+====================+===========+===========+
| no changes | ``True`` | ``True`` |
+--------------------+-----------+-----------+
| successful changes | ``True`` | ``None`` |
+--------------------+-----------+-----------+
| failed changes | ``False`` | ``None`` |
+--------------------+-----------+-----------+
+--------------------+-----------+------------------------+
| | live mode | test mode |
+====================+===========+========================+
| no changes | ``True`` | ``True`` |
+--------------------+-----------+------------------------+
| successful changes | ``True`` | ``None`` |
+--------------------+-----------+------------------------+
| failed changes | ``False`` | ``False`` or ``None`` |
+--------------------+-----------+------------------------+
.. note::
Test mode does not predict if the changes will be successful or not.
Test mode does not predict if the changes will be successful or not,
and hence the result for pending changes is usually ``None``.
- **comment:** A string containing a summary of the result.
However, if a state is going to fail and this can be determined
in test mode without applying the change, ``False`` can be returned.
- **comment:** A list of strings or a single string summarizing the result.
Note that support for lists of strings is available as of Salt Oxygen.
Lists of strings will be joined with newlines to form the final comment;
this is useful to allow multiple comments from subparts of a state.
Prefer to keep line lengths short (use multiple lines as needed),
and end with punctuation (e.g. a period) to delimit multiple comments.
The return data can also, include the **pchanges** key, this stands for
`predictive changes`. The **pchanges** key informs the State system what

2
doc/spelling_wordlist.txt
View file

@ -777,8 +777,6 @@ Stateconf
stderr
stdin
stdout
stormpath
Stormpath
str
strftime
subfolder

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

@ -34,7 +34,7 @@ monitored, everything is configured using Salt.
Beacons are typically enabled by placing a ``beacons:`` top level block in
``/etc/salt/minion`` or any file in ``/etc/salt/minion.d/`` such as
``/etc/salt/minion.d/beacons.conf``:
``/etc/salt/minion.d/beacons.conf`` or add it to pillars for that minion:
.. code-block:: yaml

6
doc/topics/cloud/action.rst
View file

@ -21,7 +21,7 @@ Or you may specify a map which includes all VMs to perform the action on:
$ salt-cloud -a reboot -m /path/to/mapfile
The following is a list of actions currently supported by salt-cloud:
The following is an example list of actions currently supported by ``salt-cloud``:
.. code-block:: yaml
@ -36,5 +36,5 @@ The following is a list of actions currently supported by salt-cloud:
- start
- stop
Another useful reference for viewing more salt-cloud actions is the
:ref:Salt Cloud Feature Matrix <salt-cloud-feature-matrix>
Another useful reference for viewing more ``salt-cloud`` actions is the
:ref:`Salt Cloud Feature Matrix <salt-cloud-feature-matrix>`.

3
doc/topics/cloud/aws.rst
View file

@ -78,6 +78,7 @@ parameters are discussed in more detail below.
# RHEL -> ec2-user
# CentOS -> ec2-user
# Ubuntu -> ubuntu
# Debian -> admin
#
ssh_username: ec2-user
@ -470,7 +471,7 @@ EC2 API or AWS Console.
By default, the spot instance type is set to 'one-time', meaning it will
be launched and, if it's ever terminated for whatever reason, it will not
be recreated. If you would like your spot instances to be relaunched after
a termination (by your or AWS), set the ``type`` to 'persistent'.
a termination (by you or AWS), set the ``type`` to 'persistent'.
NOTE: Spot instances are a great way to save a bit of money, but you do
run the risk of losing your spot instances if the current price for the

20
doc/topics/cloud/azurearm.rst
View file

@ -6,7 +6,7 @@ Getting Started With Azure ARM
Azure is a cloud service by Microsoft providing virtual machines, SQL services,
media services, and more. Azure ARM (aka, the Azure Resource Manager) is a next
generatiom version of the Azure portal and API. This document describes how to
generation version of the Azure portal and API. This document describes how to
use Salt Cloud to create a virtual machine on Azure ARM, with Salt installed.
More information about Azure is located at `http://www.windowsazure.com/
@ -15,9 +15,7 @@ More information about Azure is located at `http://www.windowsazure.com/
Dependencies
============
* `Microsoft Azure SDK for Python <https://pypi.python.org/pypi/azure>`_ >= 2.0rc6
* `Microsoft Azure Storage SDK for Python <https://pypi.python.org/pypi/azure-storage>`_ >= 0.32
* The python-requests library, for Python < 2.7.9.
* Azure Cli ```pip install 'azure-cli>=2.0.12'```
* A Microsoft Azure account
* `Salt <https://github.com/saltstack/salt>`_
@ -238,6 +236,20 @@ iface_name
Optional. The name to apply to the VM's network interface. If not supplied, the
value will be set to ``<VM name>-iface0``.
dns_servers
-----------
Optional. A **list** of the DNS servers to configure for the network interface
(will be set on the VM by the DHCP of the VNET).
.. code-block:: yaml
my-azurearm-profile:
provider: azurearm-provider
network: mynetwork
dns_servers:
- 10.1.1.4
- 10.1.1.5
availability_set
----------------
Optional. If set, the VM will be added to the specified availability set.

26
doc/topics/cloud/cloud.rst
View file

@ -146,24 +146,24 @@ library. The following two lines set up the imports:
.. code-block:: python
from salt.cloud.libcloudfuncs import * # pylint: disable=W0614,W0401
from salt.utils import namespaced_function
import salt.utils
And then a series of declarations will make the necessary functions available
within the cloud module.
.. code-block:: python
get_size = namespaced_function(get_size, globals())
get_image = namespaced_function(get_image, globals())
avail_locations = namespaced_function(avail_locations, globals())
avail_images = namespaced_function(avail_images, globals())
avail_sizes = namespaced_function(avail_sizes, globals())
script = namespaced_function(script, globals())
destroy = namespaced_function(destroy, globals())
list_nodes = namespaced_function(list_nodes, globals())
list_nodes_full = namespaced_function(list_nodes_full, globals())
list_nodes_select = namespaced_function(list_nodes_select, globals())
show_instance = namespaced_function(show_instance, globals())
get_size = salt.utils.namespaced_function(get_size, globals())
get_image = salt.utils.namespaced_function(get_image, globals())
avail_locations = salt.utils.namespaced_function(avail_locations, globals())
avail_images = salt.utils.namespaced_function(avail_images, globals())
avail_sizes = salt.utils.namespaced_function(avail_sizes, globals())
script = salt.utils.namespaced_function(script, globals())
destroy = salt.utils.namespaced_function(destroy, globals())
list_nodes = salt.utils.namespaced_function(list_nodes, globals())
list_nodes_full = salt.utils.namespaced_function(list_nodes_full, globals())
list_nodes_select = salt.utils.namespaced_function(list_nodes_select, globals())
show_instance = salt.utils.namespaced_function(show_instance, globals())
If necessary, these functions may be replaced by removing the appropriate
declaration line, and then adding the function as normal.
@ -183,7 +183,7 @@ imports should be absent from the Salt Cloud module.
A good example of a non-libcloud driver is the DigitalOcean driver:
https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/digital_ocean.py
https://github.com/saltstack/salt/tree/develop/salt/cloud/clouds/digitalocean.py
The ``create()`` Function
-------------------------

23
doc/topics/cloud/config.rst
View file

@ -56,6 +56,24 @@ settings can be placed in the provider or profile:
sls_list:
- web
When salt cloud creates a new minon, it can automatically add grain information
to the minion configuration file identifying the sources originally used
to define it.
The generated grain information will appear similar to:
.. code-block:: yaml
grains:
salt-cloud:
driver: ec2
provider: my_ec2:ec2
profile: ec2-web
The generation of the salt-cloud grain can be surpressed by the
option ``enable_cloud_grains: 'False'`` in the cloud configuration file.
Cloud Configuration Syntax
==========================
@ -97,7 +115,7 @@ Using the example configuration above:
.. note::
Salt Cloud provider configurations within ``/etc/cloud.provider.d/ should not
Salt Cloud provider configurations within ``/etc/cloud.provider.d/`` should not
specify the ``providers`` starting key.
It is also possible to have multiple cloud configuration blocks within the same alias block.
@ -371,7 +389,6 @@ both.
compute_name: cloudServersOpenStack
protocol: ipv4
compute_region: DFW
protocol: ipv4
user: myuser
tenant: 5555555
password: mypass
@ -427,7 +444,7 @@ under the API Access tab.
.. code-block:: yaml
my-digitalocean-config:
driver: digital_ocean
driver: digitalocean
personal_access_token: xxx
location: New York 1

2
doc/topics/cloud/deploy.rst
View file

@ -89,7 +89,7 @@ functions include:
A good, well commented example of this process is the Fedora deployment
script:
https://github.com/saltstack/salt-cloud/blob/master/saltcloud/deploy/Fedora.sh
https://github.com/saltstack/salt/blob/develop/salt/cloud/deploy/Fedora.sh
A number of legacy deploy scripts are included with the release tarball. None
of them are as functional or complete as Salt Bootstrap, and are still included

10
doc/topics/cloud/digitalocean.rst
View file

@ -19,7 +19,7 @@ under the "SSH Keys" section.
# /etc/salt/cloud.providers.d/ directory.
my-digitalocean-config:
driver: digital_ocean
driver: digitalocean
personal_access_token: xxx
ssh_key_file: /path/to/ssh/key/file
ssh_key_names: my-key-name,my-key-name-2
@ -63,7 +63,7 @@ command:
# salt-cloud --list-locations my-digitalocean-config
my-digitalocean-config:
----------
digital_ocean:
digitalocean:
----------
Amsterdam 1:
----------
@ -87,7 +87,7 @@ command:
# salt-cloud --list-sizes my-digitalocean-config
my-digitalocean-config:
----------
digital_ocean:
digitalocean:
----------
512MB:
----------
@ -117,7 +117,7 @@ command:
# salt-cloud --list-images my-digitalocean-config
my-digitalocean-config:
----------
digital_ocean:
digitalocean:
----------
10.1:
----------
@ -142,7 +142,7 @@ Profile Specifics:
ssh_username
------------
If using a FreeBSD image from Digital Ocean, you'll need to set the ``ssh_username``
If using a FreeBSD image from DigitalOcean, you'll need to set the ``ssh_username``
setting to ``freebsd`` in your profile configuration.
.. code-block:: yaml

2
doc/topics/cloud/function.rst
View file

@ -26,5 +26,5 @@ gathering information about instances on a provider basis:
$ salt-cloud -f list_nodes_full linode
$ salt-cloud -f list_nodes_select linode
Another useful reference for viewing salt-cloud functions is the
Another useful reference for viewing ``salt-cloud`` functions is the
:ref:`Salt Cloud Feature Matrix <salt-cloud-feature-matrix>`.

5
doc/topics/cloud/index.rst
View file

@ -64,7 +64,9 @@ automatically installed salt-cloud for you. Use your distribution's package
manager to install the ``salt-cloud`` package from the same repo that you
used to install Salt. These repos will automatically be setup by Salt Bootstrap.
If there is no salt-cloud package, install with ``pip install salt-cloud``.
Alternatively, the ``-L`` option can be passed to the `Salt Bootstrap`_ script when
installing Salt. The ``-L`` option will install ``salt-cloud`` and the required
``libcloud`` package.
.. _`Salt Bootstrap`: https://github.com/saltstack/salt-bootstrap
@ -117,6 +119,7 @@ Cloud Provider Specifics
Getting Started With Libvirt <libvirt>
Getting Started With Linode <linode>
Getting Started With LXC <lxc>
Getting Started With OneAndOne <oneandone>
Getting Started With OpenNebula <opennebula>
Getting Started With OpenStack <openstack>
Getting Started With Parallels <parallels>

2
doc/topics/cloud/joyent.rst
View file

@ -49,7 +49,7 @@ Set up an initial profile at ``/etc/salt/cloud.profiles`` or in the
.. code-block:: yaml
joyent_512
joyent_512:
provider: my-joyent-config
size: g4-highcpu-512M
image: ubuntu-16.04

6
doc/topics/cloud/libvirt.rst
View file

@ -8,10 +8,14 @@ libvirt with qemu-kvm.
http://www.libvirt.org/
Dependencies
Host Dependencies
============
* libvirt >= 1.2.18 (older might work)
Salt-Cloud Dependencies
============
* libvirt-python
Provider Configuration
======================

39
doc/topics/cloud/misc.rst
View file

@ -386,3 +386,42 @@ script, a cloud profile using ``file_map`` might look like:
file_map:
/local/path/to/custom/script: /remote/path/to/use/custom/script
/local/path/to/package: /remote/path/to/store/package
Running Pre-Flight Commands
===========================
.. versionadded:: Oxygen
To execute specified preflight shell commands on a VM before the deploy script is
run, use the ``preflight_cmds`` option. These must be defined as a list in a cloud
configuration file. For example:
.. code-block:: yaml
my-cloud-profile:
provider: linode-config
image: Ubuntu 16.04 LTS
size: Linode 2048
preflight_cmds:
- whoami
- echo 'hello world!'
These commands will run in sequence **before** the bootstrap script is executed.
Force Minion Config
===================
.. versionadded:: Oxygen
The ``force_minion_config`` option requests the bootstrap process to overwrite
an existing minion configuration file and public/private key files.
Default: False
This might be important for drivers (such as ``saltify``) which are expected to
take over a connection from a former salt master.
.. code-block:: yaml
my_saltify_provider:
driver: saltify
force_minion_config: true

146
doc/topics/cloud/oneandone.rst Normal file
View file

@ -0,0 +1,146 @@
==========================
Getting Started With 1and1
==========================
1&1 is one of the world’s leading Web hosting providers. 1&1 currently offers
a wide range of Web hosting products, including email solutions and high-end
servers in 10 different countries including Germany, Spain, Great Britain
and the United States. From domains to 1&1 MyWebsite to eBusiness solutions
like Cloud Hosting and Web servers for complex tasks, 1&1 is well placed to deliver
a high quality service to its customers. All 1&1 products are hosted in
1&1‘s high-performance, green data centers in the USA and Europe.
Dependencies
============
* 1and1 >= 1.2.0
Configuration
=============
* Using the new format, set up the cloud configuration at
``/etc/salt/cloud.providers`` or
``/etc/salt/cloud.providers.d/oneandone.conf``:
.. code-block:: yaml
my-oneandone-config:
driver: oneandone
# Set the location of the salt-master
#
minion:
master: saltmaster.example.com
# Configure oneandone authentication credentials
#
api_token: <api_token>
ssh_private_key: /path/to/id_rsa
ssh_public_key: /path/to/id_rsa.pub
Authentication
==============
The ``api_key`` is used for API authorization. This token can be obtained
from the CloudPanel in the Management section below Users.
Profiles
========
Here is an example of a profile:
.. code-block:: yaml
oneandone_fixed_size:
provider: my-oneandone-config
description: Small instance size server
fixed_instance_size: S
appliance_id: 8E3BAA98E3DFD37857810E0288DD8FBA
oneandone_custom_size:
provider: my-oneandone-config
description: Custom size server
vcore: 2
cores_per_processor: 2
ram: 8
appliance_id: 8E3BAA98E3DFD37857810E0288DD8FBA
hdds:
-
is_main: true
size: 20
-
is_main: false
size: 20
The following list explains some of the important properties.
fixed_instance_size_id
When creating a server, either ``fixed_instance_size_id`` or custom hardware params
containing ``vcore``, ``cores_per_processor``, ``ram``, and ``hdds`` must be provided.
Can be one of the IDs listed among the output of the following command:
.. code-block:: bash
salt-cloud --list-sizes oneandone
vcore
Total amount of processors.
cores_per_processor
Number of cores per processor.
ram
RAM memory size in GB.
hdds
Hard disks.
appliance_id
ID of the image that will be installed on server.
Can be one of the IDs listed in the output of the following command:
.. code-block:: bash
salt-cloud --list-images oneandone
datacenter_id
ID of the datacenter where the server will be created.
Can be one of the IDs listed in the output of the following command:
.. code-block:: bash
salt-cloud --list-locations oneandone
description
Description of the server.
password
Password of the server. Password must contain more than 8 characters
using uppercase letters, numbers and other special symbols.
power_on
Power on server after creation. Default is set to true.
firewall_policy_id
Firewall policy ID. If it is not provided, the server will assign
the best firewall policy, creating a new one if necessary. If the parameter
is sent with a 0 value, the server will be created with all ports blocked.
ip_id
IP address ID.
load_balancer_id
Load balancer ID.
monitoring_policy_id
Monitoring policy ID.
deploy
Set to False if Salt should not be installed on the node.
wait_for_timeout
The timeout to wait in seconds for provisioning resources such as servers.
The default wait_for_timeout is 15 minutes.
For more information concerning cloud profiles, see :ref:`here
<salt-cloud-profiles>`.

4
doc/topics/cloud/profitbricks.rst
View file

@ -34,8 +34,8 @@ Configuration
#
username: user@domain.com
password: 123456
# datacenter is the UUID of a pre-existing virtual data center.
datacenter: 9e6709a0-6bf9-4bd6-8692-60349c70ce0e
# datacenter_id is the UUID of a pre-existing virtual data center.
datacenter_id: 9e6709a0-6bf9-4bd6-8692-60349c70ce0e
# Connect to public LAN ID 1.
public_lan: 1
ssh_public_key: /path/to/id_rsa.pub

4
doc/topics/cloud/qs.rst
View file

@ -12,7 +12,9 @@ automatically installed salt-cloud for you. Use your distribution's package
manager to install the ``salt-cloud`` package from the same repo that you
used to install Salt. These repos will automatically be setup by Salt Bootstrap.
If there is no salt-cloud package, install with ``pip install salt-cloud``.
Alternatively, the ``-L`` option can be passed to the `Salt Bootstrap`_ script when
installing Salt. The ``-L`` option will install ``salt-cloud`` and the required
``libcloud`` package.
.. _`Salt Bootstrap`: https://github.com/saltstack/salt-bootstrap

96
doc/topics/cloud/saltify.rst
View file

@ -16,7 +16,7 @@ The Saltify driver has no external dependencies.
Configuration
=============
Because the Saltify driver does not use an actual cloud provider host, it has a
Because the Saltify driver does not use an actual cloud provider host, it can have a
simple provider configuration. The only thing that is required to be set is the
driver name, and any other potentially useful information, like the location of
the salt-master:
@ -31,6 +31,12 @@ the salt-master:
master: 111.222.333.444
provider: saltify
However, if you wish to use the more advanced capabilities of salt-cloud, such as
rebooting, listing, and disconnecting machines, then the salt master must fill
the role usually performed by a vendor's cloud management system. In order to do
that, you must configure your salt master as a salt-api server, and supply credentials
to use it. (See ``salt-api setup`` below.)
Profiles
========
@ -72,6 +78,30 @@ to it can be verified with Salt:
salt my-machine test.ping
Destroy Options
---------------
For obvious reasons, the ``destroy`` action does not actually vaporize hardware.
If the salt master is connected using salt-api, it can tear down parts of
the client machines. It will remove the client's key from the salt master,
and will attempt the following options:
.. code-block:: yaml
- remove_config_on_destroy: true
# default: true
# Deactivate salt-minion on reboot and
# delete the minion config and key files from its ``/etc/salt`` directory,
# NOTE: If deactivation is unsuccessful (older Ubuntu machines) then when
# salt-minion restarts it will automatically create a new, unwanted, set
# of key files. The ``force_minion_config`` option must be used in that case.
- shutdown_on_destroy: false
# default: false
# send a ``shutdown`` command to the client.
.. versionadded:: Oxygen
Using Map Files
---------------
The settings explained in the section above may also be set in a map file. An
@ -135,3 +165,67 @@ Return values:
- ``True``: Credential verification succeeded
- ``False``: Credential verification succeeded
- ``None``: Credential verification was not attempted.
Provisioning salt-api
=====================
In order to query or control minions it created, saltify needs to send commands
to the salt master. It does that using the network interface to salt-api.
The salt-api is not enabled by default. The following example will provide a
simple installation.
.. code-block:: yaml
# file /etc/salt/cloud.profiles.d/my_saltify_profiles.conf
hw_41: # a theoretical example hardware machine
ssh_host: 10.100.9.41 # the hard address of your target
ssh_username: vagrant # a user name which has passwordless sudo
password: vagrant # on your target machine
provider: my_saltify_provider
.. code-block:: yaml
# file /etc/salt/cloud.providers.d/saltify_provider.conf
my_saltify_provider:
driver: saltify
eauth: pam
username: vagrant # supply some sudo-group-member's name
password: vagrant # and password on the salt master
minion:
master: 10.100.9.5 # the hard address of the master
.. code-block:: yaml
# file /etc/salt/master.d/auth.conf
# using salt-api ... members of the 'sudo' group can do anything ...
external_auth:
pam:
sudo%:
- .*
- '@wheel'
- '@runner'
- '@jobs'
.. code-block:: yaml
# file /etc/salt/master.d/api.conf
# see https://docs.saltstack.com/en/latest/ref/netapi/all/salt.netapi.rest_cherrypy.html
rest_cherrypy:
host: localhost
port: 8000
ssl_crt: /etc/pki/tls/certs/localhost.crt
ssl_key: /etc/pki/tls/certs/localhost.key
thread_pool: 30
socket_queue_size: 10
Start your target machine as a Salt minion named "node41" by:
.. code-block:: bash
$ sudo salt-cloud -p hw_41 node41

12
doc/topics/cloud/windows.rst
View file

@ -48,6 +48,15 @@ from saltstack.com:
.. __: https://repo.saltstack.com/windows/
.. _new-pywinrm:
Self Signed Certificates with WinRM
===================================
Salt-Cloud can use versions of ``pywinrm<=0.1.1`` or ``pywinrm>=0.2.1``.
For versions greater than `0.2.1`, ``winrm_verify_ssl`` needs to be set to
`False` if the certificate is self signed and not verifiable.
Firewall Settings
=================
@ -179,7 +188,8 @@ The default Windows user is `Administrator`, and the default Windows password
is blank.
If WinRM is to be used ``use_winrm`` needs to be set to `True`. ``winrm_port``
can be used to specify a custom port (must be HTTPS listener).
can be used to specify a custom port (must be HTTPS listener). And
``winrm_verify_ssl`` can be set to `False` to use a self signed certificate.
Auto-Generated Passwords on EC2

15
doc/topics/development/contributing.rst
View file

@ -260,6 +260,21 @@ The Salt development team will back-port bug fixes made to ``develop`` to the
current release branch if the contributor cannot create the pull request
against that branch.
Release Branches
----------------
For each release, a branch will be created when the SaltStack release team is
ready to tag. The release branch is created from the parent branch and will be
the same name as the tag minus the ``v``. For example, the ``2017.7.1`` release
branch was created from the ``2017.7`` parent branch and the ``v2017.7.1``
release was tagged at the ``HEAD`` of the ``2017.7.1`` branch. This branching
strategy will allow for more stability when there is a need for a re-tag during
the testing phase of the release process.
Once the release branch is created, the fixes required for a given release, as
determined by the SaltStack release team, will be added to this branch. All
commits in this branch will be merged forward into the parent branch as well.
Keeping Salt Forks in Sync
==========================

36
doc/topics/development/conventions/formulas.rst
View file

@ -214,18 +214,34 @@ Writing Formulas
Each Formula is a separate repository in the `saltstack-formulas`_ organization
on GitHub.
.. note:: Get involved creating new Formulas
Get involved creating new Formulas
----------------------------------
The best way to create new Formula repositories for now is to create a
repository in your own account on GitHub and notify a SaltStack employee
when it is ready. We will add you to the contributors team on the
`saltstack-formulas`_ organization and help you transfer the repository
over. Ping a SaltStack employee on IRC (``#salt`` on Freenode) or send an
email to the `salt-users`_ mailing list.
The best way to create new Formula repositories for now is to create a
repository in your own account on GitHub and notify a SaltStack employee when
it is ready. We will add you to the Contributors team on the
`saltstack-formulas`_ organization and help you transfer the repository over.
Ping a SaltStack employee on IRC (``#salt`` on Freenode) or send an email to
the `salt-users`_ mailing list.
There are a lot of repositories in that organization! Team members can
manage which repositories they are subscribed to on GitHub's watching page:
https://github.com/watching.
There are a lot of repositories in that organization! Team members can manage
which repositories they are subscribed to on GitHub's watching page:
https://github.com/watching.
Members of the Contributors team are welcome to participate in reviewing pull
requests across the Organization. Some repositories will have regular
contributors and some repositories will not. As you get involved in a
repository be sure to communicate with any other contributors there on pull
requests that are large or have breaking changes.
In general it is best to have another Contributor review and merge any pull
requests that you open. Feel free to `at-mention`__ other regular contributors
to a repository and request a review. However, there are a lot of formula
repositories so if a repository does not yet have regular contributors or if
your pull request has stayed open for more than a couple days feel free to
"selfie-merge" your own pull request.
__: https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-users-and-teams
Style
-----

26
doc/topics/development/deprecations.rst
View file

@ -18,10 +18,10 @@ on the significance and complexity of the changes required by the user.
Salt feature releases are based on the Periodic Table. Any new features going
into the develop branch will be named after the next element in the Periodic
Table. For example, Beryllium was the feature release name of the develop branch
before the 2015.8 branch was tagged. At that point in time, any new features going
into the develop branch after 2015.8 was branched were part of the Boron feature
release.
Table. For example, Beryllium was the feature release name of the develop
branch before the 2015.8 branch was tagged. At that point in time, any new
features going into the develop branch after 2015.8 was branched were part of
the Boron feature release.
A deprecation warning should be in place for at least two major releases before
the deprecated code and its accompanying deprecation warning are removed. More
@ -29,14 +29,14 @@ time should be given for more complex changes. For example, if the current
release under development is ``Sodium``, the deprecated code and associated
warnings should remain in place and warn for at least ``Aluminum``.
To help in this deprecation task, salt provides :func:`salt.utils.warn_until
<salt.utils.warn_until>`. The idea behind this helper function is to show the
deprecation warning to the user until salt reaches the provided version. Once
that provided version is equaled :func:`salt.utils.warn_until
<salt.utils.warn_until>` will raise a :py:exc:`RuntimeError` making salt stop
its execution. This stoppage is unpleasant and will remind the developer that
the deprecation limit has been reached and that the code can then be safely
removed.
To help in this deprecation task, salt provides
:func:`salt.utils.versions.warn_until <salt.utils.versions.warn_until>`. The
idea behind this helper function is to show the deprecation warning to the user
until salt reaches the provided version. Once that provided version is equaled
:func:`salt.utils.versions.warn_until <salt.utils.versions.warn_until>` will
raise a :py:exc:`RuntimeError` making salt stop its execution. This stoppage is
unpleasant and will remind the developer that the deprecation limit has been
reached and that the code can then be safely removed.
Consider the following example:
@ -44,7 +44,7 @@ Consider the following example:
def some_function(bar=False, foo=None):
if foo is not None:
salt.utils.warn_until(
salt.utils.versions.warn_until(
'Aluminum',
'The \'foo\' argument has been deprecated and its '
'functionality removed, as such, its usage is no longer '

2
doc/topics/development/dunder_dictionaries.rst
View file

@ -1,3 +1,5 @@
.. _dunder-dictionaries:
===================
Dunder Dictionaries
===================

4
doc/topics/development/tests/index.rst
View file

@ -219,7 +219,7 @@ the default cloud provider configuration file for DigitalOcean looks like this:
.. code-block:: yaml
digitalocean-config:
driver: digital_ocean
driver: digitalocean
client_key: ''
api_key: ''
location: New York 1
@ -230,7 +230,7 @@ must be provided:
.. code-block:: yaml
digitalocean-config:
driver: digital_ocean
driver: digitalocean
client_key: wFGEwgregeqw3435gDger
api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg
location: New York 1

11
doc/topics/development/tests/integration.rst
View file

@ -371,6 +371,7 @@ on a minion event bus.
.. code-block:: python
import tests.integration as integration
import salt.utils.event
class TestEvent(integration.SaltEventAssertsMixin):
'''
@ -443,7 +444,7 @@ to test states:
from tests.support.mixins import SaltReturnAssertsMixin
# Import salt libs
import salt.utils
import salt.utils.files
HFILE = os.path.join(TMP, 'hosts')
@ -470,7 +471,7 @@ to test states:
ip = '10.10.10.10'
ret = self.run_state('host.present', name=name, ip=ip)
self.assertSaltTrueReturn(ret)
with salt.utils.fopen(HFILE) as fp_:
with salt.utils.files.fopen(HFILE) as fp_:
output = fp_.read()
self.assertIn('{0}\t\t{1}'.format(ip, name), output)
@ -540,7 +541,7 @@ provider configuration file in the integration test file directory located at
``tests/integration/files/conf/cloud.*.d/``.
The following is an example of the default profile configuration file for Digital
Ocean, located at: ``tests/integration/files/conf/cloud.profiles.d/digital_ocean.conf``:
Ocean, located at: ``tests/integration/files/conf/cloud.profiles.d/digitalocean.conf``:
.. code-block:: yaml
@ -556,12 +557,12 @@ be provided by the user by editing the provider configuration file before runnin
tests.
The following is an example of the default provider configuration file for Digital
Ocean, located at: ``tests/integration/files/conf/cloud.providers.d/digital_ocean.conf``:
Ocean, located at: ``tests/integration/files/conf/cloud.providers.d/digitalocean.conf``:
.. code-block:: yaml
digitalocean-config:
driver: digital_ocean
driver: digitalocean
client_key: ''
api_key: ''
location: New York 1

2
doc/topics/development/tests/unit.rst
View file

@ -319,7 +319,7 @@ function into ``__salt__`` that's actually a MagicMock instance.
def show_patch(self):
with patch.dict(my_module.__salt__,
{'function.to_replace': MagicMock()}:
{'function.to_replace': MagicMock()}):
# From this scope, carry on with testing, with a modified __salt__!

54
doc/topics/eauth/index.rst
View file

@ -93,6 +93,26 @@ By user, by minion:
<minion compound target>:
- <regex to match function>
By user, by runner/wheel:
.. code-block:: yaml
external_auth:
<eauth backend>:
<user or group%>:
<@runner or @wheel>:
- <regex to match function>
By user, by runner+wheel module:
.. code-block:: yaml
external_auth:
<eauth backend>:
<user or group%>:
<@module_name>:
- <regex to match function without module_name>
Groups
------
@ -127,6 +147,14 @@ Positional arguments or keyword arguments to functions can also be whitelisted.
kwargs:
'kwa': 'kwa.*'
'kwb': 'kwb'
- '@runner':
- 'runner_mod.*':
args:
- 'a.*'
- 'b.*'
kwargs:
'kwa': 'kwa.*'
'kwb': 'kwb'
The rules:
@ -246,6 +274,10 @@ Server configuration values and their defaults:
# Redhat Identity Policy Audit
auth.ldap.freeipa: False
Authenticating to the LDAP Server
+++++++++++++++++++++++++++++++++
There are two phases to LDAP authentication. First, Salt authenticates to search for a users' Distinguished Name
and group membership. The user it authenticates as in this phase is often a special LDAP system user with
read-only access to the LDAP directory. After Salt searches the directory to determine the actual user's DN
@ -276,6 +308,10 @@ substitutes the ``{{ username }}`` value for the username when querying LDAP
auth.ldap.filter: uid={{ username }}
Determining Group Memberships (OpenLDAP / non-Active Directory)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
For OpenLDAP, to determine group membership, one can specify an OU that contains
group data. This is prepended to the basedn to create a search path. Then
the results are filtered against ``auth.ldap.groupclass``, default
@ -285,7 +321,16 @@ the results are filtered against ``auth.ldap.groupclass``, default
auth.ldap.groupou: Groups
When using the `ldap('DC=domain,DC=com')` eauth operator, sometimes the records returned
Note that as of 2017.7, auth.ldap.groupclass can refer to either a groupclass or an objectClass.
For some LDAP servers (notably OpenLDAP without the ``memberOf`` overlay enabled) to determine group
membership we need to know both the ``objectClass`` and the ``memberUid`` attributes. Usually for these
servers you will want a ``auth.ldap.groupclass`` of ``posixGroup`` and an ``auth.ldap.groupattribute`` of
``memberUid``.
LDAP servers with the ``memberOf`` overlay will have entries similar to ``auth.ldap.groupclass: person`` and
``auth.ldap.groupattribute: memberOf``.
When using the ``ldap('DC=domain,DC=com')`` eauth operator, sometimes the records returned
from LDAP or Active Directory have fully-qualified domain names attached, while minion IDs
instead are simple hostnames. The parameter below allows the administrator to strip
off a certain set of domain names so the hostnames looked up in the directory service
@ -295,8 +340,9 @@ can match the minion IDs.
auth.ldap.minion_stripdomains: ['.external.bigcorp.com', '.internal.bigcorp.com']
Active Directory
----------------
Determining Group Memberships (Active Directory)
++++++++++++++++++++++++++++++++++++++++++++++++
Active Directory handles group membership differently, and does not utilize the
``groupou`` configuration variable. AD needs the following options in
@ -361,5 +407,5 @@ be part of the eAuth definition, they can be specified like this:
- ldap('DC=corp,DC=example,DC=com'):
- test.echo
The string inside `ldap()` above is any valid LDAP/AD tree limiter. `OU=` in
The string inside ``ldap()`` above is any valid LDAP/AD tree limiter. ``OU=`` in
particular is permitted as long as it would return a list of computer objects.

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

@ -18,7 +18,7 @@ Installation from official Debian and Raspbian repositories is described
Installation from the Official SaltStack Repository
===================================================
Packages for Debian 8 (Jessie) and Debian 7 (Wheezy) are available in the
Packages for Debian 9 (Stretch) and Debian 8 (Jessie) are available in the
Official SaltStack repository.
Instructions are at https://repo.saltstack.com/#debian.

154
doc/topics/installation/eos.rst Normal file
View file

@ -0,0 +1,154 @@
=========================================
Arista EOS Salt minion installation guide
=========================================
The Salt minion for Arista EOS is distributed as a SWIX extension and can be installed directly on the switch. The EOS network operating system is based on old Fedora distributions and the installation of the ``salt-minion`` requires backports. This SWIX extension contains the necessary backports, together with the Salt basecode.
.. note::
This SWIX extension has been tested on Arista DCS-7280SE-68-R, running EOS 4.17.5M and vEOS 4.18.3F.
Important Notes
===============
This package is in beta, make sure to test it carefully before running it in production.
If confirmed working correctly, please report and add a note on this page with the platform model and EOS version.
If you want to uninstall this package, please refer to the uninstalling_ section.
Installation from the Official SaltStack Repository
===================================================
Download the swix package and save it to flash.
.. code-block:: bash
veos#copy https://salt-eos.netops.life/salt-eos-latest.swix flash:
veos#copy https://salt-eos.netops.life/startup.sh flash:
Install the Extension
=====================
Copy the Salt package to extension
.. code-block:: bash
veos#copy flash:salt-eos-latest.swix extension:
Install the SWIX
.. code-block:: bash
veos#extension salt-eos-latest.swix force
Verify the installation
.. code-block:: bash
veos#show extensions | include salt-eos
salt-eos-2017-07-19.swix 1.0.11/1.fc25 A, F 27
Change the Salt master IP address or FQDN, by edit the variable (SALT_MASTER)
.. code-block:: bash
veos#bash vi /mnt/flash/startup.sh
Make sure you enable the eAPI with unix-socket
.. code-block:: bash
veos(config)#management api http-commands
protocol unix-socket
no shutdown
Post-installation tasks
=======================
Generate Keys and host record and start Salt minion
.. code-block:: bash
veos#bash
#sudo /mnt/flash/startup.sh
``salt-minion`` should be running
Copy the installed extensions to boot-extensions
.. code-block:: bash
veos#copy installed-extensions boot-extensions
Apply event-handler to let EOS start salt-minion during boot-up
.. code-block:: bash
veos(config)#event-handler boot-up-script
trigger on-boot
action bash sudo /mnt/flash/startup.sh
For more specific installation details of the ``salt-minion``, please refer to :ref:`Configuring Salt<configuring-salt>`.
.. _uninstalling:
Uninstalling
============
If you decide to uninstall this package, the following steps are recommended for safety:
1. Remove the extension from boot-extensions
.. code-block:: bash
veos#bash rm /mnt/flash/boot-extensions
2. Remove the extension from extensions folder
.. code-block:: bash
veos#bash rm /mnt/flash/.extensions/salt-eos-latest.swix
2. Remove boot-up script
.. code-block:: bash
veos(config)#no event-handler boot-up-script
Additional Information
======================
This SWIX extension contains the following RPM packages:
.. code-block:: text
libsodium-1.0.11-1.fc25.i686.rpm
libstdc++-6.2.1-2.fc25.i686.rpm
openpgm-5.2.122-6.fc24.i686.rpm
python-Jinja2-2.8-0.i686.rpm
python-PyYAML-3.12-0.i686.rpm
python-babel-0.9.6-5.fc18.noarch.rpm
python-backports-1.0-3.fc18.i686.rpm
python-backports-ssl_match_hostname-3.4.0.2-1.fc18.noarch.rpm
python-backports_abc-0.5-0.i686.rpm
python-certifi-2016.9.26-0.i686.rpm
python-chardet-2.0.1-5.fc18.noarch.rpm
python-crypto-1.4.1-1.noarch.rpm
python-crypto-2.6.1-1.fc18.i686.rpm
python-futures-3.1.1-1.noarch.rpm
python-jtextfsm-0.3.1-0.noarch.rpm
python-kitchen-1.1.1-2.fc18.noarch.rpm
python-markupsafe-0.18-1.fc18.i686.rpm
python-msgpack-python-0.4.8-0.i686.rpm
python-napalm-base-0.24.3-1.noarch.rpm
python-napalm-eos-0.6.0-1.noarch.rpm
python-netaddr-0.7.18-0.noarch.rpm
python-pyeapi-0.7.0-0.noarch.rpm
python-salt-2017.7.0_1414_g2fb986f-1.noarch.rpm
python-singledispatch-3.4.0.3-0.i686.rpm
python-six-1.10.0-0.i686.rpm
python-tornado-4.4.2-0.i686.rpm
python-urllib3-1.5-7.fc18.noarch.rpm
python2-zmq-15.3.0-2.fc25.i686.rpm
zeromq-4.1.4-5.fc25.i686.rpm

1
doc/topics/installation/index.rst
View file

@ -46,6 +46,7 @@ These guides go into detail how to install Salt on a given platform.
arch
debian
eos
fedora
freebsd
gentoo

122
doc/topics/jinja/index.rst
View file

@ -150,6 +150,22 @@ starts at the root of the state tree or pillar.
.. _`macro`: http://jinja.pocoo.org/docs/templates/#macros
.. _`whitespace control`: http://jinja.pocoo.org/docs/templates/#whitespace-control
Errors
======
Saltstack allows to raise custom errors using the ``raise`` jinja function.
.. code-block:: jinja
{{ raise('Custom Error') }}
When rendering the template containing the above statement, a ``TemplateError``
exception is raised, causing the rendering to fail with the following message:
.. code-block:: text
TemplateError: Custom Error
Filters
=======
@ -335,7 +351,7 @@ Returns:
.. versionadded:: 2017.7.0
Wraps a text around quoutes.
This text will be wrapped in quotes.
.. jinja_ref:: regex_search
@ -750,19 +766,43 @@ Returns:
Check a whitelist and/or blacklist to see if the value matches it.
Example:
This filter can be used with either a whitelist or a blacklist individually,
or a whitelist and a blacklist can be passed simultaneously.
If whitelist is used alone, value membership is checked against the
whitelist only. If the value is found, the function returns ``True``.
Otherwise, it returns ``False``.
If blacklist is used alone, value membership is checked against the
blacklist only. If the value is found, the function returns ``False``.
Otherwise, it returns ``True``.
If both a whitelist and a blacklist are provided, value membership in the
blacklist will be examined first. If the value is not found in the blacklist,
then the whitelist is checked. If the value isn't found in the whitelist,
the function returns ``False``.
Whitelist Example:
.. code-block:: jinja
{{ 5 | check_whitelist_blacklist(whitelist=[5, 6, 7]) }}
{{ 5 | check_whitelist_blacklist(blacklist=[5, 6, 7]) }}
{{ 5 | check_whitelist_blacklist(whitelist=[5, 6, 7]) }}
Returns:
.. code-block:: python
True
True
Blacklist Example:
.. code-block:: jinja
{{ 5 | check_whitelist_blacklist(blacklist=[5, 6, 7]) }}
.. code-block:: python
False
.. jinja_ref:: date_format
@ -788,12 +828,14 @@ Returns:
08.03.2017 17:00
.. jinja_ref:: str_to_num
.. jinja_ref:: to_num
``str_to_num``
--------------
``to_num``
----------
.. versionadded:: 2017.7.0
.. versionadded:: Oxygen
Renamed from ``str_to_num`` to ``to_num``.
Converts a string to its numerical value.
@ -801,7 +843,7 @@ Example:
.. code-block:: jinja
{{ '5' | str_to_num }}
{{ '5' | to_num }}
Returns:
@ -825,6 +867,13 @@ Example:
{{ 'wall of text' | to_bytes }}
.. note::
This option may have adverse effects when using the default renderer, ``yaml_jinja``.
This is due to the fact that YAML requires proper handling in regard to special
characters. Please see the section on :ref:`YAML ASCII support <yaml_plain_ascii>`
in the :ref:`YAML Idiosyncracies <yaml-idiosyncrasies>` documentation for more
information.
.. jinja_ref:: json_decode_list
@ -870,22 +919,28 @@ Returns:
{'a': 'b'}
.. jinja_ref:: rand_str
.. jinja_ref:: random_hash
``rand_str``
------------
``random_hash``
---------------
.. versionadded:: 2017.7.0
.. versionadded:: Oxygen
Renamed from ``rand_str`` to ``random_hash`` to more accurately describe
what the filter does.
Generate a random string and applies a hash. Default hashing: md5.
Generates a random number between 1 and the number passed to the filter, and
then hashes it. The default hash type is the one specified by the minion's
:conf_minion:`hash_type` config option, but an alternate hash type can be
passed to the filter as an argument.
Example:
.. code-block:: jinja
{% set passwd_length = 17 %}
{{ passwd_length | rand_str }}
{{ passwd_length | rand_str('sha512') }}
{% set num_range = 99999999 %}
{{ num_range | random_hash }}
{{ num_range | random_hash('sha512') }}
Returns:
@ -1186,7 +1241,7 @@ Example:
.. code-block:: jinja
{{ ['192.168.0.1', 'foo', 'bar', 'fe80::'] | ipv4 }}
{{ ['192.168.0.1', 'foo', 'bar', 'fe80::'] | ipv6 }}
Returns:
@ -1202,7 +1257,12 @@ Returns:
.. versionadded:: 2017.7.0
Return the list of hosts within a networks.
Return the list of hosts within a networks. This utility works for both IPv4 and IPv6.
.. note::
When running this command with a large IPv6 network, the command will
take a long time to gather all of the hosts.
Example:
@ -1224,7 +1284,7 @@ Returns:
.. versionadded:: 2017.7.0
Return the size of the network.
Return the size of the network. This utility works for both IPv4 and IPv6.
Example:
@ -1284,6 +1344,13 @@ Example:
{{ '00:11:22:33:44:55' | mac_str_to_bytes }}
.. note::
This option may have adverse effects when using the default renderer, ``yaml_jinja``.
This is due to the fact that YAML requires proper handling in regard to special
characters. Please see the section on :ref:`YAML ASCII support <yaml_plain_ascii>`
in the :ref:`YAML Idiosyncracies <yaml-idiosyncrasies>` documentation for more
information.
.. jinja_ref:: dns_check
@ -1684,6 +1751,23 @@ Will insert the following message in the minion logs:
.. jinja_ref:: custom-execution-modules
Python Methods
====================
A powerful feature of jinja that is only hinted at in the official jinja
documentation is that you can use the native python methods of the
variable type. Here is the python documentation for `string methods`_.
.. code-block:: jinja
{% set hostname,domain = grains.id.partition('.')[::2] %}{{ hostname }}
.. code-block:: jinja
{% set strings = grains.id.split('-') %}{{ strings[0] }}
.. _`string methods`: https://docs.python.org/2/library/stdtypes.html#string-methods
Custom Execution Modules
========================

4
doc/topics/network_automation/index.rst
View file

@ -40,7 +40,7 @@ and the interaction with the network device does not rely on a particular vendor
.. image:: /_static/napalm_logo.png
Beginning with Nitrogen, the NAPALM modules have been transformed so they can
Beginning with 2017.7.0, the NAPALM modules have been transformed so they can
run in both proxy and regular minions. That means, if the operating system
allows, the salt-minion package can be installed directly on the network gear.
The interface between the network operating system and Salt in that case would
@ -50,7 +50,7 @@ For example, if the user installs the
salt-minion on a Arista switch, the only requirement is
`napalm-eos <https://github.com/napalm-automation/napalm-eos>`_.
The following modules are available in Nitrogen:
The following modules are available in 2017.7.0:
- :mod:`NAPALM grains <salt.grains.napalm>`
- :mod:`NET execution module <salt.modules.napalm_network>` - Networking basic

34
doc/topics/proxyminion/index.rst
View file

@ -89,7 +89,7 @@ they are being loaded for the correct proxytype, example below:
Only work on proxy
'''
try:
if salt.utils.is_proxy() and \
if salt.utils.platform.is_proxy() and \
__opts__['proxy']['proxytype'] == 'ssh_sample':
return __virtualname__
except KeyError:
@ -156,20 +156,23 @@ will need to be restarted to pick up any changes. A corresponding utility funct
``saltutil.sync_proxymodules``, has been added to sync these modules to minions.
In addition, a salt.utils helper function called `is_proxy()` was added to make
it easier to tell when the running minion is a proxy minion.
it easier to tell when the running minion is a proxy minion. **NOTE: This
function was renamed to salt.utils.platform.is_proxy() for the Oxygen release**
New in 2015.8
-------------
Starting with the 2015.8 release of Salt, proxy processes are no longer forked off from a controlling minion.
Instead, they have their own script ``salt-proxy`` which takes mostly the same arguments that the
standard Salt minion does with the addition of ``--proxyid``. This is the id that the salt-proxy will
use to identify itself to the master. Proxy configurations are still best kept in Pillar and their format
has not changed.
Starting with the 2015.8 release of Salt, proxy processes are no longer forked
off from a controlling minion. Instead, they have their own script
``salt-proxy`` which takes mostly the same arguments that the standard Salt
minion does with the addition of ``--proxyid``. This is the id that the
salt-proxy will use to identify itself to the master. Proxy configurations are
still best kept in Pillar and their format has not changed.
This change allows for better process control and logging. Proxy processes can now be listed with standard
process management utilities (``ps`` from the command line). Also, a full Salt minion is no longer
required (though it is still strongly recommended) on machines hosting proxies.
This change allows for better process control and logging. Proxy processes can
now be listed with standard process management utilities (``ps`` from the
command line). Also, a full Salt minion is no longer required (though it is
still strongly recommended) on machines hosting proxies.
Getting Started
@ -619,9 +622,10 @@ in the proxymodule itself. This might be useful if a proxymodule author wants t
all the code for the proxy interface in the same place instead of splitting it between
the proxy and grains directories.
This function will only be called automatically if the configuration variable ``proxy_merge_grains_in_module``
is set to True in the proxy configuration file (default ``/etc/salt/proxy``). This
variable defaults to ``True`` in the release code-named *2017.7.0*.
This function will only be called automatically if the configuration variable
``proxy_merge_grains_in_module`` is set to True in the proxy configuration file
(default ``/etc/salt/proxy``). This variable defaults to ``True`` in the
release code-named *2017.7.0*.
.. code: python::
@ -640,7 +644,7 @@ variable defaults to ``True`` in the release code-named *2017.7.0*.
def __virtual__():
try:
if salt.utils.is_proxy() and __opts__['proxy']['proxytype'] == 'rest_sample':
if salt.utils.platform.is_proxy() and __opts__['proxy']['proxytype'] == 'rest_sample':
return __virtualname__
except KeyError:
pass
@ -708,7 +712,7 @@ Example from ``salt/grains/rest_sample.py``:
def __virtual__():
try:
if salt.utils.is_proxy() and __opts__['proxy']['proxytype'] == 'rest_sample':
if salt.utils.platform.is_proxy() and __opts__['proxy']['proxytype'] == 'rest_sample':
return __virtualname__
except KeyError:
pass

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

@ -106,7 +106,7 @@ bringing with it the ability to access authenticated repositories.
Using the new features will require updates to the git ext_pillar
configuration, further details can be found in the :ref:`pillar.git_pillar
<git-pillar-2015-8-0-and-later>` docs.
<git-pillar-configuration>` docs.
.. _pygit2: https://github.com/libgit2/pygit2

945
doc/topics/releases/2016.11.6.rst
View file

File diff suppressed because it is too large Load diff

15
doc/topics/releases/2016.11.7.rst Normal file
View file

@ -0,0 +1,15 @@
============================
Salt 2016.11.7 Release Notes
============================
Version 2016.11.7 is a bugfix release for :ref:`2016.11.0 <release-2016-11-0>`.
Changes for v2016.11.6..v2016.11.7
----------------------------------
Security Fix
============
CVE-2017-12791 Maliciously crafted minion IDs can cause unwanted directory traversals on the Salt-master
Correct a flaw in minion id validation which could allow certain minions to authenticate to a master despite not having the correct credentials. To exploit the vulnerability, an attacker must create a salt-minion with an ID containing characters that will cause a directory traversal. Credit for discovering the security flaw goes to: Vernhk@qq.com

4
doc/topics/releases/2016.3.0.rst
View file

@ -175,6 +175,10 @@ they are being loaded for the correct proxytype, example below:
return False
.. note::
``salt.utils.is_proxy()`` has been renamed to
``salt.utils.platform.is_proxy`` as of the Oxygen release.
The try/except block above exists because grains are processed very early
in the proxy minion startup process, sometimes earlier than the proxy
key in the ``__opts__`` dictionary is populated.

23
doc/topics/releases/2016.3.7.rst
View file

@ -4,23 +4,12 @@ Salt 2016.3.7 Release Notes
Version 2016.3.7 is a bugfix release for :ref:`2016.3.0 <release-2016-3-0>`.
New master configuration option `allow_minion_key_revoke`, defaults to True. This option
controls whether a minion can request that the master revoke its key. When True, a minion
can request a key revocation and the master will comply. If it is False, the key will not
be revoked by the msater.
Changes for v2016.3.6..v2016.3.7
--------------------------------
New master configuration option `require_minion_sign_messages`
This requires that minions cryptographically sign the messages they
publish to the master. If minions are not signing, then log this information
at loglevel 'INFO' and drop the message without acting on it.
Security Fix
============
New master configuration option `drop_messages_signature_fail`
Drop messages from minions when their signatures do not validate.
Note that when this option is False but `require_minion_sign_messages` is True
minions MUST sign their messages but the validity of their signatures
is ignored.
CVE-2017-12791 Maliciously crafted minion IDs can cause unwanted directory traversals on the Salt-master
New minion configuration option `minion_sign_messages`
Causes the minion to cryptographically sign the payload of messages it places
on the event bus for the master. The payloads are signed with the minion's
private key so the master can verify the signature with its public key.
Correct a flaw in minion id validation which could allow certain minions to authenticate to a master despite not having the correct credentials. To exploit the vulnerability, an attacker must create a salt-minion with an ID containing characters that will cause a directory traversal. Credit for discovering the security flaw goes to: Vernhk@qq.com

29
doc/topics/releases/2016.3.8.rst Normal file
View file

@ -0,0 +1,29 @@
===========================
Salt 2016.3.8 Release Notes
===========================
Version 2016.3.8 is a bugfix release for :ref:`2016.3.0 <release-2016-3-0>`.
Changes for v2016.3.7..v2016.3.8
--------------------------------
New master configuration option `allow_minion_key_revoke`, defaults to True. This option
controls whether a minion can request that the master revoke its key. When True, a minion
can request a key revocation and the master will comply. If it is False, the key will not
be revoked by the msater.
New master configuration option `require_minion_sign_messages`
This requires that minions cryptographically sign the messages they
publish to the master. If minions are not signing, then log this information
at loglevel 'INFO' and drop the message without acting on it.
New master configuration option `drop_messages_signature_fail`
Drop messages from minions when their signatures do not validate.
Note that when this option is False but `require_minion_sign_messages` is True
minions MUST sign their messages but the validity of their signatures
is ignored.
New minion configuration option `minion_sign_messages`
Causes the minion to cryptographically sign the payload of messages it places
on the event bus for the master. The payloads are signed with the minion's
private key so the master can verify the signature with its public key.

118
doc/topics/releases/2017.7.0.rst
View file

@ -4,6 +4,45 @@
Salt 2017.7.0 Release Notes - Codename Nitrogen
===============================================
========
Python 3
========
The 2017.7 Salt Release adds initial Python 3 support.
The default Python version of Salt will remain Python 2, although Python 3 packages will be supplied for users who want to help test this new feature.
======================
Python 2.6 Deprecation
======================
Salt will no longer support Python 2.6. We will provide python2.7 packages on our repo_ for RedHat and CentOS 6 to ensure users can still run Salt on these platforms.
.. _repo: https://repo.saltstack.com/
============
Known Issues
============
The following salt-cloud drivers have known issues running with Python 3. These drivers will not work with Python 3, and Python 2.7 should be used instead:
- Joyent
- When running under Python 3, users who require Unicode support should ensure that a locale is set on their machines.
Users using the `C` locale are advised to switch to a UTF-aware locale to ensure proper functionality with Salt with Python 3.
Remember to update the Salt Master first
========================================
Salt's policy has always been that when upgrading, the minion should never be
on a newer version than the master. Specifically with this update, because of
changes in the fileclient, the 2017.7 minion requires a 2017.7 master.
Backwards compatiblity is still maintained, so older minions can still be used.
More information can be found in the :ref:`Salt FAQ<which-version>`
States Added for Management of systemd Unit Masking
===================================================
@ -83,13 +122,12 @@ State Module Changes
# After
run_something:
module.run:
mymodule.something:
- mymodule.something:
- name: some name
- first_arg: one
- second_arg: two
- do_stuff: True
Since a lot of users are already using :py:func:`module.run
<salt.states.module.run>` states, this new behavior must currently be
explicitly turned on, to allow users to take their time updating their SLS
@ -97,6 +135,36 @@ State Module Changes
the next feature release of Salt (Oxygen) and the old usage will no longer be
supported at that time.
Another feature of the new :py:func:`module.run <salt.states.module.run>` is that
it allows calling many functions in a single batch, such as:
.. code-block:: yaml
run_something:
module.run:
- mymodule.function_without_parameters:
- mymodule.another_function:
- myparam
- my_other_param
In a rare case that you have a function that needs to be called several times but
with the different parameters, an additional feature of "tagging" is to the
rescue. In order to tag a function, use a colon delimeter. For example:
.. code-block:: yaml
run_something:
module.run:
- mymodule.same_function:1:
- mymodule.same_function:2:
- myparam
- my_other_param
- mymodule.same_function:3:
- foo: bar
The example above will run `mymodule.same_function` three times with the
different parameters.
To enable the new behavior for :py:func:`module.run <salt.states.module.run>`,
add the following to the minion config file:
@ -104,6 +172,7 @@ State Module Changes
use_superseded:
- module.run
- The default for the ``fingerprint_hash_type`` option used in the ``present``
function in the :mod:`ssh <salt.states.ssh_know_hosts>` state changed from
``md5`` to ``sha256``.
@ -161,6 +230,7 @@ Wildcard Versions in :py:func:`pkg.installed <salt.states.pkg.installed>` States
- The :py:func:`pkg.installed <salt.states.pkg.installed>` state now supports
wildcards in package versions, for the following platforms:
- SUSE/openSUSE Leap/Thumbleweed
- Debian/Ubuntu
- RHEL/CentOS
- Arch Linux
@ -542,6 +612,38 @@ Using the new ``roster_order`` configuration syntax it's now possible to compose
of grains, pillar and mine data and even Salt SDB URLs.
The new release is also fully IPv4 and IPv6 enabled and even has support for CIDR ranges.
Salt-SSH Default Options
========================
Defaults for rosters can now be set, so that they don't have to be set on every
entry in a roster or specified from the commandline.
The new option is :ref:`roster_defaults<roster-defaults>` and is specified in
the master config file.
.. code-block:: yaml
roster_defaults:
user: daniel
sudo: True
priv: /root/.ssh/id_rsa
tty: True
Blacklist or Whitelist Extmod Sync
==================================
The modules that are synced to minions can now be limited.
The following configuration options have been added for the master:
- :conf_master:`extmod_whitelist`
- :conf_master:`extmod_blacklist`
and for the minion:
- :conf_minion:`extmod_whitelist`
- :conf_minion:`extmod_blacklist`
Additional Features
===================
@ -604,6 +706,7 @@ Execution modules
- :mod:`salt.modules.grafana4 <salt.modules.grafana4>`
- :mod:`salt.modules.heat <salt.modules.heat>`
- :mod:`salt.modules.icinga2 <salt.modules.icinga2>`
- :mod:`salt.modules.kubernetes <salt.modules.kubernetes>`
- :mod:`salt.modules.logmod <salt.modules.logmod>`
- :mod:`salt.modules.mattermost <salt.modules.mattermost>`
- :mod:`salt.modules.namecheap_dns <salt.modules.namecheap_dns>`
@ -682,6 +785,7 @@ States
- :mod:`salt.states.icinga2 <salt.states.icinga2>`
- :mod:`salt.states.influxdb_continuous_query <salt.states.influxdb_continuous_query>`
- :mod:`salt.states.influxdb_retention_policy <salt.states.influxdb_retention_policy>`
- :mod:`salt.states.kubernetes <salt.states.kubernetes>`
- :mod:`salt.states.logadm <salt.states.logadm>`
- :mod:`salt.states.logrotate <salt.states.logrotate>`
- :mod:`salt.states.msteams <salt.states.msteams>`
@ -871,3 +975,13 @@ The ``glusterfs`` state had the following function removed:
The ``openvswitch_port`` state had the following change:
- The ``type`` option was removed from the ``present`` function. Please use ``tunnel_type`` instead.
Build Notes
===========
Windows Installer Packages
--------------------------
Windows Installer packages have been patched with the following PR: 42347_
.. _42347: https://github.com/saltstack/salt/pull/42347

190
doc/topics/releases/2017.7.1.rst Normal file
View file

@ -0,0 +1,190 @@
============================
Salt 2017.7.1 Release Notes
============================
Version 2017.7.1 is a bugfix release for :ref:`2017.7.0 <release-2017-7-0>`.
Security Fix
============
CVE-2017-12791 Maliciously crafted minion IDs can cause unwanted directory traversals on the Salt-master
Correct a flaw in minion id validation which could allow certain minions to authenticate to a master despite not having the correct credentials. To exploit the vulnerability, an attacker must create a salt-minion with an ID containing characters that will cause a directory traversal. Credit for discovering the security flaw goes to: Vernhk@qq.com
Changes for v2017.7.0..v2017.7.1
--------------------------------
Extended changelog courtesy of Todd Stansell (https://github.com/tjstansell/salt-changelogs):
*Generated at: 2017-07-26T01:09:40Z*
Statistics:
- Total Merges: **11**
- Total Issue references: **9**
- Total PR references: **22**
Changes:
- **PR** `#42548`_: (*gtmanfred*) pass in empty kwarg for reactor
@ *2017-07-26T00:41:20Z*
- **ISSUE** `#460`_: (*whiteinge*) Add a topic and a ref for modules/states/returners/renderers/runners
| refs: `#42548`_
* 711b742c54 Merge pull request `#42548`_ from gtmanfred/2017.7.1
* 0257c1dc32 pass in empty kwarg for reactor
* b948e980d2 update chunk, not kwarg in chunk
- **PR** `#42522`_: (*gtmanfred*) pacman wildcard is only for repository installs
@ *2017-07-24T20:51:05Z*
- **ISSUE** `#42519`_: (*xuhcc*) Error when installing package from file under Arch Linux
| refs: `#42522`_
* 50c1635dcc Merge pull request `#42522`_ from gtmanfred/2017.7.1
* 7787fb9e1b pacman wildcard is only for repository installs
- **PR** `#42508`_: (*rallytime*) Back-port `#42474`_ to 2017.7.1
@ *2017-07-24T20:49:51Z*
- **PR** `#42474`_: (*whiteinge*) Cmd arg kwarg parsing test
| refs: `#42508`_
- **PR** `#39646`_: (*terminalmage*) Handle deprecation of passing string args to load_args_and_kwargs
| refs: `#42474`_
* 05c07ac049 Merge pull request `#42508`_ from rallytime/`bp-42474`_
* 76fb074433 Add a test.arg variant that cleans the pub kwargs by default
* 624f63648e Lint fixes
* d246a5fc61 Add back support for string kwargs
* 854e098aa0 Add LocalClient.cmd test for arg/kwarg parsing
- **PR** `#42472`_: (*rallytime*) Back-port `#42435`_ to 2017.7.1
@ *2017-07-24T15:11:13Z*
- **ISSUE** `#42427`_: (*grichmond-salt*) Issue Passing Variables created from load_json as Inline Pillar Between States
| refs: `#42435`_
- **PR** `#42435`_: (*terminalmage*) Modify our custom YAML loader to treat unicode literals as unicode strings
| refs: `#42472`_
* 95fe2558e4 Merge pull request `#42472`_ from rallytime/`bp-42435`_
* 5c47af5b98 Modify our custom YAML loader to treat unicode literals as unicode strings
- **PR** `#42473`_: (*rallytime*) Back-port `#42436`_ to 2017.7.1
@ *2017-07-24T15:10:29Z*
- **ISSUE** `#42374`_: (*tyhunt99*) [2017.7.0] salt-run mange.versions throws exception if minion is offline or unresponsive
| refs: `#42436`_
- **PR** `#42436`_: (*garethgreenaway*) Fixes to versions function in manage runner
| refs: `#42473`_
* 5b99d45f54 Merge pull request `#42473`_ from rallytime/`bp-42436`_
* 82ed919803 Updating the versions function inside the manage runner to account for when a minion is offline and we are unable to determine it's version.
- **PR** `#42471`_: (*rallytime*) Back-port `#42399`_ to 2017.7.1
@ *2017-07-24T15:09:50Z*
- **ISSUE** `#42381`_: (*zebooka*) Git.detached broken in 2017.7.0
| refs: `#42399`_
- **ISSUE** `#38878`_: (*tomlaredo*) [Naming consistency] git.latest "rev" option VS git.detached "ref" option
| refs: `#38898`_
- **PR** `#42399`_: (*rallytime*) Update old "ref" references to "rev" in git.detached state
| refs: `#42471`_
- **PR** `#38898`_: (*terminalmage*) git.detached: rename ref to rev for consistency
| refs: `#42399`_
* 3d1a2d3f9f Merge pull request `#42471`_ from rallytime/`bp-42399`_
* b9a4669e5a Update old "ref" references to "rev" in git.detached state
- **PR** `#42470`_: (*rallytime*) Back-port `#42031`_ to 2017.7.1
@ *2017-07-24T15:09:30Z*
- **ISSUE** `#42400`_: (*Enquier*) Conflict in execution of passing pillar data to orch/reactor event executions 2017.7.0
| refs: `#42031`_
- **PR** `#42031`_: (*skizunov*) Fix: Reactor emits critical error
| refs: `#42470`_
* 09766bccbc Merge pull request `#42470`_ from rallytime/`bp-42031`_
* 0a0c6287a4 Fix: Reactor emits critical error
- **PR** `#42469`_: (*rallytime*) Back-port `#42027`_ to 2017.7.1
@ *2017-07-21T22:41:02Z*
- **ISSUE** `#41949`_: (*jrporcaro*) Event returner doesn't work with Windows Master
| refs: `#42027`_
- **PR** `#42027`_: (*gtmanfred*) import salt.minion for EventReturn for Windows
| refs: `#42469`_
* d7b172a15b Merge pull request `#42469`_ from rallytime/`bp-42027`_
* ed612b4ee7 import salt.minion for EventReturn for Windows
- **PR** `#42466`_: (*rallytime*) Back-port `#42452`_ to 2017.7.1
@ *2017-07-21T19:41:24Z*
- **PR** `#42452`_: (*Ch3LL*) update windows urls to new py2/py3 naming scheme
| refs: `#42466`_
* 8777b1a825 Merge pull request `#42466`_ from rallytime/`bp-42452`_
* c10196f68c update windows urls to new py2/py3 naming scheme
- **PR** `#42439`_: (*rallytime*) Back-port `#42409`_ to 2017.7.1
@ *2017-07-21T17:38:10Z*
- **PR** `#42409`_: (*twangboy*) Add Scripts to build Py3 on Mac
| refs: `#42439`_
* fceaaf41d0 Merge pull request `#42439`_ from rallytime/`bp-42409`_
* 8176964b41 Remove build and dist, sign pkgs
* 2c14d92a07 Fix hard coded pip path
* 82fdd7c2e1 Add support for Py3
* 2478447246 Update Python and other reqs
- **PR** `#42441`_: (*rallytime*) Back-port `#42433`_ to 2017.7.1
@ *2017-07-21T17:37:01Z*
- **ISSUE** `#42403`_: (*astronouth7303*) [2017.7] Pillar empty when state is applied from orchestrate
| refs: `#42433`_
- **PR** `#42433`_: (*terminalmage*) Only force saltenv/pillarenv to be a string when not None
| refs: `#42441`_
* 660400560b Merge pull request `#42441`_ from rallytime/`bp-42433`_
* 17f347123a Only force saltenv/pillarenv to be a string when not None
.. _`#38878`: https://github.com/saltstack/salt/issues/38878
.. _`#38898`: https://github.com/saltstack/salt/pull/38898
.. _`#39646`: https://github.com/saltstack/salt/pull/39646
.. _`#41949`: https://github.com/saltstack/salt/issues/41949
.. _`#42027`: https://github.com/saltstack/salt/pull/42027
.. _`#42031`: https://github.com/saltstack/salt/pull/42031
.. _`#42374`: https://github.com/saltstack/salt/issues/42374
.. _`#42381`: https://github.com/saltstack/salt/issues/42381
.. _`#42399`: https://github.com/saltstack/salt/pull/42399
.. _`#42400`: https://github.com/saltstack/salt/issues/42400
.. _`#42403`: https://github.com/saltstack/salt/issues/42403
.. _`#42409`: https://github.com/saltstack/salt/pull/42409
.. _`#42427`: https://github.com/saltstack/salt/issues/42427
.. _`#42433`: https://github.com/saltstack/salt/pull/42433
.. _`#42435`: https://github.com/saltstack/salt/pull/42435
.. _`#42436`: https://github.com/saltstack/salt/pull/42436
.. _`#42439`: https://github.com/saltstack/salt/pull/42439
.. _`#42441`: https://github.com/saltstack/salt/pull/42441
.. _`#42452`: https://github.com/saltstack/salt/pull/42452
.. _`#42466`: https://github.com/saltstack/salt/pull/42466
.. _`#42469`: https://github.com/saltstack/salt/pull/42469
.. _`#42470`: https://github.com/saltstack/salt/pull/42470
.. _`#42471`: https://github.com/saltstack/salt/pull/42471
.. _`#42472`: https://github.com/saltstack/salt/pull/42472
.. _`#42473`: https://github.com/saltstack/salt/pull/42473
.. _`#42474`: https://github.com/saltstack/salt/pull/42474
.. _`#42508`: https://github.com/saltstack/salt/pull/42508
.. _`#42519`: https://github.com/saltstack/salt/issues/42519
.. _`#42522`: https://github.com/saltstack/salt/pull/42522
.. _`#42548`: https://github.com/saltstack/salt/pull/42548
.. _`#460`: https://github.com/saltstack/salt/issues/460
.. _`bp-42027`: https://github.com/saltstack/salt/pull/42027
.. _`bp-42031`: https://github.com/saltstack/salt/pull/42031
.. _`bp-42399`: https://github.com/saltstack/salt/pull/42399
.. _`bp-42409`: https://github.com/saltstack/salt/pull/42409
.. _`bp-42433`: https://github.com/saltstack/salt/pull/42433
.. _`bp-42435`: https://github.com/saltstack/salt/pull/42435
.. _`bp-42436`: https://github.com/saltstack/salt/pull/42436
.. _`bp-42452`: https://github.com/saltstack/salt/pull/42452
.. _`bp-42474`: https://github.com/saltstack/salt/pull/42474

691
doc/topics/releases/oxygen.rst
View file

@ -13,18 +13,655 @@ packages on minions which use :mod:`yum/dnf <salt.modules.yumpkg>` or :mod:`apt
<salt.states.pkg.installed>` state and in the ``pkg.install`` remote execution
function.
Configuration Option Deprecations
:ref:`Master Tops <master-tops-system>` Changes
-----------------------------------------------
When both :ref:`Master Tops <master-tops-system>` and a :ref:`Top File
<states-top>` produce SLS matches for a given minion, the matches were being
merged in an unpredictable manner which did not preserve ordering. This has
been changed. The top file matches now execute in the expected order, followed
by any master tops matches that are not matched via a top file.
To make master tops matches execute first, followed by top file matches, set
the new :conf_minion:`master_tops_first` minion config option to ``True``.
LDAP via External Authentication Changes
----------------------------------------
In this release of Salt, if LDAP Bind Credentials are supplied, then
these credentials will be used for all LDAP access except the first
authentication when a job is submitted. The first authentication will
use the user's credentials as passed on the CLI. This behavior is to
accommodate certain two-factor authentication schemes where the authentication
token can only be used once.
In previous releases the bind credentials would only be used to determine
the LDAP user's existence and group membership. The user's LDAP credentials
were used from then on.
Stormpath External Authentication Removed
-----------------------------------------
Per Stormpath's announcement, their API will be shutting down on 8/17/2017 at
noon PST so the Stormpath external authentication module has been removed.
https://stormpath.com/oktaplusstormpath
New NaCl Renderer
-----------------
A new renderer has been added for encrypted data.
New support for Cisco UCS Chassis
---------------------------------
The salt proxy minion now allows for control of Cisco USC chassis. See
the `cimc` modules for details.
New salt-ssh roster
-------------------
A new roster has been added that allows users to pull in a list of hosts
for salt-ssh targeting from a ~/.ssh configuration. For full details,
please see the `sshconfig` roster.
New GitFS Features
------------------
Two new features which affect how GitFS maps branches/tags to fileserver
environments (i.e. ``saltenvs``) have been added:
1. It is now possible to completely turn off Salt's default mapping logic
(aside from the mapping of the ``base`` saltenv). This can be triggered
using the new :conf_master:`gitfs_disable_saltenv_mapping` config option.
.. note::
When this is disabled, only the ``base`` saltenv and any configured
using :ref:`per-saltenv configuration parameters
<gitfs-per-saltenv-config>` will be available.
2. The types of refs which Salt will use as saltenvs can now be controlled. In
previous releases, branches and tags were both mapped as environments, and
individual commit SHAs could be specified as saltenvs in states (and when
caching files using :py:func:`cp.cache_file <salt.modules.cp.cache_file>`).
Using the new :conf_master:`gitfs_ref_types` config option, the types of
refs which are used as saltenvs can be restricted. This makes it possible to
ignore all tags and use branches only, and also to keep SHAs from being made
available as saltenvs.
Salt Cloud Features
-------------------
Pre-Flight Commands
===================
Support has been added for specified "preflight commands" to run on a VM before
the deploy script is run. These must be defined as a list in a cloud configuration
file. For example:
.. code-block:: yaml
my-cloud-profile:
provider: linode-config
image: Ubuntu 16.04 LTS
size: Linode 2048
preflight_cmds:
- whoami
- echo 'hello world!'
These commands will run in sequence **before** the bootstrap script is executed.
Newer PyWinRM Versions
----------------------
Versions of ``pywinrm>=0.2.1`` are finally able to disable validation of self
signed certificates. :ref:`Here<new-pywinrm>` for more information.
DigitalOcean
------------
The DigitalOcean driver has been renamed to conform to the companies name. The
new driver name is ``digitalocean``. The old name ``digital_ocean`` and a
short one ``do`` will still be supported through virtual aliases, this is mostly
cosmetic.
Solaris Logical Domains In Virtual Grain
----------------------------------------
Support has been added to the ``virtual`` grain for detecting Solaris LDOMs
running on T-Series SPARC hardware. The ``virtual_subtype`` grain is
populated as a list of domain roles.
Lists of comments in state returns
----------------------------------
State functions can now return a list of strings for the ``comment`` field,
as opposed to only a single string.
This is meant to ease writing states with multiple or multi-part comments.
Beacon configuration changes
----------------------------
In order to remain consistent and to align with other Salt components such as states,
support for configuring beacons using dictionary based configuration has been deprecated
in favor of list based configuration. All beacons have a validation function which will
check the configuration for the correct format and only load if the validation passes.
- ``avahi_announce`` beacon
Old behavior:
```
beacons:
avahi_announce:
run_once: True
servicetype: _demo._tcp
port: 1234
txt:
ProdName: grains.productname
SerialNo: grains.serialnumber
Comments: 'this is a test'
```
New behavior:
```
beacons:
avahi_announce:
- run_once: True
- servicetype: _demo._tcp
- port: 1234
- txt:
ProdName: grains.productname
SerialNo: grains.serialnumber
Comments: 'this is a test'
```
- ``bonjour_announce`` beacon
Old behavior:
```
beacons:
bonjour_announce:
run_once: True
servicetype: _demo._tcp
port: 1234
txt:
ProdName: grains.productname
SerialNo: grains.serialnumber
Comments: 'this is a test'
```
New behavior:
```
beacons:
bonjour_announce:
- run_once: True
- servicetype: _demo._tcp
- port: 1234
- txt:
ProdName: grains.productname
SerialNo: grains.serialnumber
Comments: 'this is a test'
```
- ``btmp`` beacon
Old behavior:
```
beacons:
btmp: {}
```
New behavior:
```
beacons:
btmp: []
```
- ``glxinfo`` beacon
Old behavior:
```
beacons:
glxinfo:
user: frank
screen_event: True
```
New behavior:
```
beacons:
glxinfo:
- user: frank
- screen_event: True
```
- ``haproxy`` beacon
Old behavior:
```
beacons:
haproxy:
- www-backend:
threshold: 45
servers:
- web1
- web2
- interval: 120
```
New behavior:
```
beacons:
haproxy:
- backends:
www-backend:
threshold: 45
servers:
- web1
- web2
- interval: 120
```
- ``inotify`` beacon
Old behavior:
```
beacons:
inotify:
/path/to/file/or/dir:
mask:
- open
- create
- close_write
recurse: True
auto_add: True
exclude:
- /path/to/file/or/dir/exclude1
- /path/to/file/or/dir/exclude2
- /path/to/file/or/dir/regex[a-m]*$:
regex: True
coalesce: True
```
New behavior:
```
beacons:
inotify:
- files:
/path/to/file/or/dir:
mask:
- open
- create
- close_write
recurse: True
auto_add: True
exclude:
- /path/to/file/or/dir/exclude1
- /path/to/file/or/dir/exclude2
- /path/to/file/or/dir/regex[a-m]*$:
regex: True
- coalesce: True
```
- ``journald`` beacon
Old behavior:
```
beacons:
journald:
sshd:
SYSLOG_IDENTIFIER: sshd
PRIORITY: 6
```
New behavior:
```
beacons:
journald:
- services:
sshd:
SYSLOG_IDENTIFIER: sshd
PRIORITY: 6
```
- ``load`` beacon
Old behavior:
```
beacons:
load:
1m:
- 0.0
- 2.0
5m:
- 0.0
- 1.5
15m:
- 0.1
- 1.0
emitatstartup: True
onchangeonly: False
```
New behavior:
```
beacons:
load:
- averages:
1m:
- 0.0
- 2.0
5m:
- 0.0
- 1.5
15m:
- 0.1
- 1.0
- emitatstartup: True
- onchangeonly: False
```
- ``log`` beacon
Old behavior:
```
beacons:
log:
file: <path>
<tag>:
regex: <pattern>
```
New behavior:
```
beacons:
log:
- file: <path>
- tags:
<tag>:
regex: <pattern>
```
- ``network_info`` beacon
Old behavior:
```
beacons:
network_info:
- eth0:
type: equal
bytes_sent: 100000
bytes_recv: 100000
packets_sent: 100000
packets_recv: 100000
errin: 100
errout: 100
dropin: 100
dropout: 100
```
New behavior:
```
beacons:
network_info:
- interfaces:
eth0:
type: equal
bytes_sent: 100000
bytes_recv: 100000
packets_sent: 100000
packets_recv: 100000
errin: 100
errout: 100
dropin: 100
dropout: 100
```
- ``network_settings`` beacon
Old behavior:
```
beacons:
network_settings:
eth0:
ipaddr:
promiscuity:
onvalue: 1
eth1:
linkmode:
```
New behavior:
```
beacons:
network_settings:
- interfaces:
- eth0:
ipaddr:
promiscuity:
onvalue: 1
- eth1:
linkmode:
```
- ``proxy_example`` beacon
Old behavior:
```
beacons:
proxy_example:
endpoint: beacon
```
New behavior:
```
beacons:
proxy_example:
- endpoint: beacon
```
- ``ps`` beacon
Old behavior:
```
beacons:
ps:
- salt-master: running
- mysql: stopped
```
New behavior:
```
beacons:
ps:
- processes:
salt-master: running
mysql: stopped
```
- ``salt_proxy`` beacon
Old behavior:
```
beacons:
salt_proxy:
- p8000: {}
- p8001: {}
```
New behavior:
```
beacons:
salt_proxy:
- proxies:
p8000: {}
p8001: {}
```
- ``sensehat`` beacon
Old behavior:
```
beacons:
sensehat:
humidity: 70%
temperature: [20, 40]
temperature_from_pressure: 40
pressure: 1500
```
New behavior:
```
beacons:
sensehat:
- sensors:
humidity: 70%
temperature: [20, 40]
temperature_from_pressure: 40
pressure: 1500
```
- ``service`` beacon
Old behavior:
```
beacons:
service:
salt-master:
mysql:
```
New behavior:
```
beacons:
service:
- services:
nginx:
onchangeonly: True
delay: 30
uncleanshutdown: /run/nginx.pid
```
- ``sh`` beacon
Old behavior:
```
beacons:
sh: {}
```
New behavior:
```
beacons:
sh: []
```
- ``status`` beacon
Old behavior:
```
beacons:
status: {}
```
New behavior:
```
beacons:
status: []
```
- ``telegram_bot_msg`` beacon
Old behavior:
```
beacons:
telegram_bot_msg:
token: "<bot access token>"
accept_from:
- "<valid username>"
interval: 10
```
New behavior:
```
beacons:
telegram_bot_msg:
- token: "<bot access token>"
- accept_from:
- "<valid username>"
- interval: 10
```
- ``twilio_txt_msg`` beacon
Old behavior:
```
beacons:
twilio_txt_msg:
account_sid: "<account sid>"
auth_token: "<auth token>"
twilio_number: "+15555555555"
interval: 10
```
New behavior:
```
beacons:
twilio_txt_msg:
- account_sid: "<account sid>"
- auth_token: "<auth token>"
- twilio_number: "+15555555555"
- interval: 10
```
- ``wtmp`` beacon
Old behavior:
```
beacons:
wtmp: {}
```
New behavior:
```
beacons:
wtmp: []
```
Deprecations
------------
Configuration Option Deprecations
=================================
- The ``requests_lib`` configuration option has been removed. Please use
``backend`` instead.
Profitbricks Cloud Updated Dependency
=====================================
The minimum version of the ``profitbrick`` python package for the ``profitbricks``
cloud driver has changed from 3.0.0 to 3.1.0.
Azure Cloud Updated Dependency
------------------------------
The azure sdk used for the ``azurearm`` cloud driver now depends on ``azure-cli>=2.0.12``
Module Deprecations
-------------------
===================
The ``blockdev`` execution module has been removed. Its functions were merged
with the ``disk`` module. Please use the ``disk`` execution module instead.
The ``lxc`` execution module had the following changes:
- The ``dnsservers`` option to the ``cloud_init_interface`` function no longer
defaults to ``4.4.4.4`` and ``8.8.8.8``.
- The ``dns_via_dhcp`` option to the ``cloud_init_interface`` function defaults
to ``True`` now instead of ``False``.
The ``win_psget`` module had the following changes:
- The ``psversion`` function was removed. Please use ``cmd.shell_info`` instead.
@ -52,8 +689,16 @@ The ``win_service`` module had the following changes:
- The ``type`` option was removed from the ``create`` function. Please use
``service_type`` instead.
Runner Deprecations
===================
The ``manage`` runner had the following changes:
- The ``root_user`` kwarg was removed from the ``bootstrap`` function. Please
use ``salt-ssh`` roster entries for the host instead.
State Deprecations
------------------
==================
The ``archive`` state had the following changes:
@ -76,9 +721,47 @@ The ``file`` state had the following changes:
- The ``show_diff`` option was removed. Please use ``show_changes`` instead.
Grain Deprecations
------------------
==================
For ``smartos`` some grains have been deprecated. These grains will be removed in Neon.
- The ``hypervisor_uuid`` has been replaced with ``mdata:sdc:server_uuid`` grain.
- The ``datacenter`` has been replaced with ``mdata:sdc:datacenter_name`` grain.
Minion Blackout
---------------
During a blackout, minions will not execute any remote execution commands,
except for :mod:`saltutil.refresh_pillar <salt.modules.saltutil.refresh_pillar>`.
Previously, support was added so that blackouts are enabled using a special
pillar key, ``minion_blackout`` set to ``True`` and an optional pillar key
``minion_blackout_whitelist`` to specify additional functions that are permitted
during blackout. This release adds support for using this feature in the grains
as well, by using special grains keys ``minion_blackout`` and
``minion_blackout_whitelist``.
Pillar Deprecations
-------------------
The legacy configuration for ``git_pillar`` has been removed. Please use the new
configuration for ``git_pillar``, which is documented in the external pillar module
for :mod:`git_pillar <salt.pillar.git_pillar>`.
Utils Deprecations
==================
The ``salt.utils.cloud.py`` file had the following change:
- The ``fire_event`` function now requires a ``sock_dir`` argument. It was previously
optional.
Other Miscellaneous Deprecations
================================
The ``version.py`` file had the following changes:
- The ``rc_info`` function was removed. Please use ``pre_info`` instead.
Warnings for moving away from the ``env`` option were removed. ``saltenv`` should be
used instead. The removal of these warnings does not have a behavior change. Only
the warning text was removed.

36
doc/topics/releases/releasecandidate.rst
View file

@ -8,7 +8,7 @@ Installing/Testing a Salt Release Candidate
It's time for a new feature release of Salt! Follow the instructions below to
install the latest release candidate of Salt, and try :ref:`all the shiny new
features <release-2016-11-0>`! Be sure to report any bugs you find on `Github
features <release-2017-7-0>`! Be sure to report any bugs you find on `Github
<https://github.com/saltstack/salt/issues/new/>`_.
Installing Using Packages
@ -32,32 +32,12 @@ Builds for a few platforms are available as part of the RC at https://repo.salts
Available builds:
- Amazon Linux
- Debian 8
- macOS
- RHEL 7
- SmartOS (see below)
- Ubuntu 16.04
- Ubuntu16
- Redhat7
- Windows
.. FreeBSD
SmartOS
-------
Release candidate builds for SmartOS are available at http://pkg.blackdot.be/extras/salt-2016.11rc/.
On a base64 2015Q4-x86_64 based native zone the package can be installed by the following:
.. code-block:: bash
pfexec pkg_add -U https://pkg.blackdot.be/extras/salt-2016.11rc/salt-2016.11.0rc2_2015Q4_x86_64.tgz
When using the 2016Q2-tools release on the global zone by the following:
.. code-block:: bash
pfexec pkg_add -U https://pkg.blackdot.be/extras/salt-2016.11rc/salt-2016.11.0rc2_2016Q2_TOOLS.tgz
Installing Using Bootstrap
==========================
@ -67,14 +47,14 @@ You can install a release candidate of Salt using `Salt Bootstrap
.. code-block:: bash
curl -o install_salt.sh -L https://bootstrap.saltstack.com
sudo sh install_salt.sh -P git v2016.11.0rc2
sudo sh install_salt.sh -P git v2017.7.0rc1
If you want to also install a master using Salt Bootstrap, use the ``-M`` flag:
.. code-block:: bash
curl -o install_salt.sh -L https://bootstrap.saltstack.com
sudo sh install_salt.sh -P -M git v2016.11.0rc2
sudo sh install_salt.sh -P -M git v2017.7.0rc1
If you want to install only a master and not a minion using Salt Bootstrap, use
the ``-M`` and ``-N`` flags:
@ -82,13 +62,13 @@ the ``-M`` and ``-N`` flags:
.. code-block:: bash
curl -o install_salt.sh -L https://bootstrap.saltstack.com
sudo sh install_salt.sh -P -M -N git v2016.11.0rc2
sudo sh install_salt.sh -P -M -N git v2017.7.0rc1
Installing Using PyPI
=====================
Installing from the `source archive
<https://pypi.python.org/packages/7a/87/3b29ac215208bed9559d6c4df24175ddd1d52e62c5c00ae3afb3b7d9144d/salt-2016.11.0rc2.tar.gz>`_ on
<https://pypi.python.org/packages/5c/cf/13c14f8bcd7b5076b9a8c3580f9582c1c4ea8b0458793ac6744ea66c0baf/salt-2017.7.0rc1.tar.gz>`_ on
`PyPI <https://pypi.python.org/pypi>`_ is fairly straightforward.
.. note::
@ -126,4 +106,4 @@ Then install salt using the following command:
.. code-block:: bash
sudo pip install salt==2016.11.0rc2
sudo pip install salt==2017.7.0rc1

2
doc/topics/spm/dev.rst
View file

@ -256,7 +256,7 @@ This function will not generally be more complex than:
.. code-block:: python
def hash_file(path, hashobj, conn=None):
with salt.utils.fopen(path, 'r') as f:
with salt.utils.files.fopen(path, 'r') as f:
hashobj.update(f.read())
return hashobj.hexdigest()

2
doc/topics/spm/spm_formula.rst
View file

@ -11,7 +11,7 @@ describes the package. An example of this file is:
name: apache
os: RedHat, Debian, Ubuntu, SUSE, FreeBSD
os_family: RedHat, Debian, SUSE, FreeBSD
os_family: RedHat, Debian, Suse, FreeBSD
version: 201506
release: 2
summary: Formula for installing Apache

3
doc/topics/ssh/index.rst
View file

@ -64,7 +64,8 @@ Deploy ssh key for salt-ssh
===========================
By default, salt-ssh will generate key pairs for ssh, the default path will be
/etc/salt/pki/master/ssh/salt-ssh.rsa
``/etc/salt/pki/master/ssh/salt-ssh.rsa``. The key generation happens when you run
``salt-ssh`` for the first time.
You can use ssh-copy-id, (the OpenSSH key deployment tool) to deploy keys to your servers.

10
doc/topics/ssh/roster.rst
View file

@ -61,6 +61,8 @@ The information which can be stored in a roster ``target`` is the following:
cmd_umask: # umask to enforce for the salt-call command. Should be in
# octal (so for 0o077 in YAML you would do 0077, or 63)
.. _roster_defaults:
Target Defaults
---------------
@ -71,10 +73,10 @@ not need to be passed with commandline arguments.
.. code-block:: yaml
roster_defaults:
user: daniel
sudo: True
priv: /root/.ssh/id_rsa
tty: True
user: daniel
sudo: True
priv: /root/.ssh/id_rsa
tty: True
thin_dir
--------

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

@ -28,6 +28,7 @@ hit `Enter`. Also, you can convert tabs to 2 spaces by these commands in Vim:
Indentation
===========
The suggested syntax for YAML files is to use 2 spaces for indentation,
but YAML will follow whatever indentation system that the individual file
uses. Indentation of two spaces works very well for SLS files given the
@ -112,8 +113,24 @@ PyYAML will load these values as boolean ``True`` or ``False``. Un-capitalized
versions will also be loaded as booleans (``true``, ``false``, ``yes``, ``no``,
``on``, and ``off``). This can be especially problematic when constructing
Pillar data. Make sure that your Pillars which need to use the string versions
of these values are enclosed in quotes. Pillars will be parsed twice by salt,
so you'll need to wrap your values in multiple quotes, for example '"false"'.
of these values are enclosed in quotes. Pillars will be parsed twice by salt,
so you'll need to wrap your values in multiple quotes, including double quotation
marks (``" "``) and single quotation marks (``' '``). Note that spaces are included
in the quotation type examples for clarity.
Multiple quoting examples looks like this:
.. code-block:: yaml
- '"false"'
- "'True'"
- "'YES'"
- '"No"'
.. note::
When using multiple quotes in this manner, they must be different. Using ``"" ""``
or ``'' ''`` won't work in this case (spaces are included in examples for clarity).
The '%' Sign
============
@ -248,8 +265,10 @@ Alternatively, they can be defined the "old way", or with multiple
- require:
- user: fred
YAML support only plain ASCII
=============================
.. _yaml_plain_ascii:
YAML supports only plain ASCII
==============================
According to YAML specification, only ASCII characters can be used.

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

@ -91,8 +91,6 @@ firewall.
yast2 firewall
.. _linux-iptables:
Windows
=======
@ -137,6 +135,8 @@ following command from the command line or a run prompt:
netsh advfirewall firewall add rule name="Salt" dir=in action=allow protocol=TCP localport=4505-4506
.. _linux-iptables:
iptables
========

47
doc/topics/tutorials/gitfs.rst
View file

@ -166,13 +166,15 @@ Ubuntu 14.04 LTS and Debian Wheezy (7.x) also have a compatible version packaged
# apt-get install python-git
If your master is running an older version (such as Ubuntu 12.04 LTS or Debian
Squeeze), then you will need to install GitPython using either pip_ or
easy_install (it is recommended to use pip). Version 0.3.2.RC1 is now marked as
the stable release in PyPI, so it should be a simple matter of running ``pip
install GitPython`` (or ``easy_install GitPython``) as root.
GitPython_ requires the ``git`` CLI utility to work. If installed from a system
package, then git should already be installed, but if installed via pip_ then
it may still be necessary to install git separately. For MacOS users,
GitPython_ comes bundled in with the Salt installer, but git must still be
installed for it to work properly. Git can be installed in several ways,
including by installing XCode_.
.. _`pip`: http://www.pip-installer.org/
.. _pip: http://www.pip-installer.org/
.. _XCode: https://developer.apple.com/xcode/
.. warning::
@ -330,6 +332,8 @@ configured gitfs remotes):
* :conf_master:`gitfs_privkey` (**pygit2 only**, new in 2014.7.0)
* :conf_master:`gitfs_passphrase` (**pygit2 only**, new in 2014.7.0)
* :conf_master:`gitfs_refspecs` (new in 2017.7.0)
* :conf_master:`gitfs_disable_saltenv_mapping` (new in Oxygen)
* :conf_master:`gitfs_ref_types` (new in Oxygen)
.. note::
pygit2 only supports disabling SSL verification in versions 0.23.2 and
@ -355,11 +359,17 @@ tremendous amount of customization. Here's some example usage:
- root: other/salt
- mountpoint: salt://other/bar
- base: salt-base
- ref_types:
- branch
- http://foo.com/baz.git:
- root: salt/states
- user: joe
- password: mysupersecretpassword
- insecure_auth: True
- disable_saltenv_mapping: True
- saltenv:
- foo:
- ref: foo
- http://foo.com/quux.git:
- all_saltenvs: master
@ -391,18 +401,24 @@ In the example configuration above, the following is true:
will only serve files from the ``salt/states`` directory (and its
subdirectories).
3. The first and fourth remotes will have files located under the root of the
3. The third remote will only serve files from branches, and not from tags or
SHAs.
4. The fourth remote will only have two saltenvs available: ``base`` (pointed
at ``develop``), and ``foo`` (pointed at ``foo``).
5. The first and fourth remotes will have files located under the root of the
Salt fileserver namespace (``salt://``). The files from the second remote
will be located under ``salt://bar``, while the files from the third remote
will be located under ``salt://other/bar``.
4. The second and third remotes reference the same repository and unique names
6. The second and third remotes reference the same repository and unique names
need to be declared for duplicate gitfs remotes.
5. The fourth remote overrides the default behavior of :ref:`not authenticating
7. The fourth remote overrides the default behavior of :ref:`not authenticating
to insecure (non-HTTPS) remotes <gitfs-insecure-auth>`.
6. Because ``all_saltenvs`` is configured for the fifth remote, files from the
8. Because ``all_saltenvs`` is configured for the fifth remote, files from the
branch/tag ``master`` will appear in every fileserver environment.
.. note::
@ -1094,15 +1110,8 @@ Using Git as an External Pillar Source
The git external pillar (a.k.a. git_pillar) has been rewritten for the 2015.8.0
release. This rewrite brings with it pygit2_ support (allowing for access to
authenticated repositories), as well as more granular support for per-remote
configuration.
To make use of the new features, changes to the git ext_pillar configuration
must be made. The new configuration schema is detailed :ref:`here
<git-pillar-2015-8-0-and-later>`.
For Salt releases before 2015.8.0, click :ref:`here <git-pillar-pre-2015-8-0>`
for documentation.
configuration. This configuration schema is detailed :ref:`here
<git-pillar-configuration>`.
.. _faq-gitfs-bug:

12
doc/topics/tutorials/http.rst
View file

@ -110,7 +110,7 @@ To pass through a file that contains jinja + yaml templating (the default):
method='POST',
data_file='/srv/salt/somefile.jinja',
data_render=True,
template_data={'key1': 'value1', 'key2': 'value2'}
template_dict={'key1': 'value1', 'key2': 'value2'}
)
To pass through a file that contains mako templating:
@ -123,7 +123,7 @@ To pass through a file that contains mako templating:
data_file='/srv/salt/somefile.mako',
data_render=True,
data_renderer='mako',
template_data={'key1': 'value1', 'key2': 'value2'}
template_dict={'key1': 'value1', 'key2': 'value2'}
)
Because this function uses Salt's own rendering system, any Salt renderer can
@ -140,7 +140,7 @@ However, this can be changed to ``master`` if necessary.
method='POST',
data_file='/srv/salt/somefile.jinja',
data_render=True,
template_data={'key1': 'value1', 'key2': 'value2'},
template_dict={'key1': 'value1', 'key2': 'value2'},
opts=__opts__
)
@ -149,7 +149,7 @@ However, this can be changed to ``master`` if necessary.
method='POST',
data_file='/srv/salt/somefile.jinja',
data_render=True,
template_data={'key1': 'value1', 'key2': 'value2'},
template_dict={'key1': 'value1', 'key2': 'value2'},
node='master'
)
@ -170,11 +170,11 @@ a Python dict.
header_file='/srv/salt/headers.jinja',
header_render=True,
header_renderer='jinja',
template_data={'key1': 'value1', 'key2': 'value2'}
template_dict={'key1': 'value1', 'key2': 'value2'}
)
Because much of the data that would be templated between headers and data may be
the same, the ``template_data`` is the same for both. Correcting possible
the same, the ``template_dict`` is the same for both. Correcting possible
variable name collisions is up to the user.
Authentication

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