Merge pull request #32179 from rallytime/merge-develop

[develop] Merge forward from 2016.3 to develop

doc/faq.rst

@@ -38,8 +38,8 @@ I'm seeing weird behavior (including but not limited to packages not installing
 This is often caused by SELinux.  Try disabling SELinux or putting it in
 permissive mode and see if the weird behavior goes away.
 
-My script runs every time I run a *state.highstate*. Why?
----------------------------------------------------------
+My script runs every time I run a *state.apply*. Why?
+-----------------------------------------------------
 
 You are probably using :mod:`cmd.run <salt.states.cmd.run>` rather than
 :mod:`cmd.wait <salt.states.cmd.wait>`. A :mod:`cmd.wait
@@ -134,11 +134,11 @@ should be opened on our tracker_, with the following information:
 Why aren't my custom modules/states/etc. available on my Minions?
 -----------------------------------------------------------------
 
-Custom modules are only synced to Minions when :mod:`state.highstate
-<salt.modules.state.highstate>`, :mod:`saltutil.sync_modules
+Custom modules are only synced to Minions when :mod:`state.apply
+<salt.modules.state.apply_>`, :mod:`saltutil.sync_modules
 <salt.modules.saltutil.sync_modules>`, or :mod:`saltutil.sync_all
 <salt.modules.saltutil.sync_all>` is run. Similarly, custom states are only
-synced to Minions when :mod:`state.highstate <salt.modules.state.highstate>`,
+synced to Minions when :mod:`state.apply <salt.modules.state.apply_>`,
 :mod:`saltutil.sync_states <salt.modules.saltutil.sync_states>`, or
 :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` is run.
 

doc/ref/cli/_includes/target-selection-ssh.rst

@@ -0,0 +1,11 @@
+Target Selection
+----------------
+
+The default matching that Salt utilizes is shell-style globbing around the
+minion id. See https://docs.python.org/2/library/fnmatch.html#module-fnmatch.
+
+.. option:: -E, --pcre
+
+    The target expression will be interpreted as a PCRE regular expression
+    rather than a shell glob.
+

doc/ref/cli/_includes/target-selection.rst

@@ -1,6 +1,9 @@
 Target Selection
 ----------------
 
+The default matching that Salt utilizes is shell-style globbing around the
+minion id. See https://docs.python.org/2/library/fnmatch.html#module-fnmatch.
+
 .. option:: -E, --pcre
 
     The target expression will be interpreted as a PCRE regular expression

doc/ref/cli/salt-ssh.rst

@@ -79,7 +79,7 @@ Options
 
 .. include:: _includes/common-options.rst
 
-.. include:: _includes/target-selection.rst
+.. include:: _includes/target-selection-ssh.rst
 
 .. include:: _includes/logging-options.rst
 .. |logfile| replace:: /var/log/salt/ssh

doc/ref/clients/index.rst

@@ -72,6 +72,8 @@ Each module type has a corresponding loader function.
 Salt's Client Interfaces
 ========================
 
+.. _local-client:
+
 LocalClient
 -----------
 

doc/ref/configuration/minion.rst

@@ -331,10 +331,10 @@ Verify and set permissions on configuration directories at startup.
 
 .. note::
 
-    When marked as True the verify_env option requires WRITE access to the
+    When set to ``True`` the verify_env option requires WRITE access to the
     configuration directory (/etc/salt/). In certain situations such as
-    mounting /etc/salt/ as read-only for templating this will create a
-    stack trace when state.highstate is called.
+    mounting /etc/salt/ as read-only for templating this will create a stack
+    trace when :py:func:`state.apply <salt.modules.state.apply_>` is called.
 
 .. conf_minion:: cache_jobs
 

doc/ref/modules/index.rst

@@ -20,7 +20,7 @@ default this is ``/srv/salt/_modules`` on Linux systems.
 Modules placed in ``_modules/`` will be synced to the minions when any of the following
 Salt functions are called:
 
-* :mod:`state.highstate <salt.modules.state.highstate>`
+* :mod:`state.apply <salt.modules.state.apply_>`
 * :mod:`saltutil.sync_modules <salt.modules.saltutil.sync_modules>`
 * :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
 

doc/ref/renderers/index.rst

@@ -121,11 +121,10 @@ Custom renderers must be placed in a ``_renderers`` directory within the
 :conf_master:`file_roots` specified by the master config file.
 
 Custom renderers are distributed when any of the following are run:
-    :mod:`state.highstate <salt.modules.state.highstate>`
 
-    :mod:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>`
-
-    :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
+- :py:func:`state.apply <salt.modules.state.apply_>`
+- :py:func:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>`
+- :py:func:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
 
 Any custom renderers which have been synced to a minion, that are named the
 same as one of Salt's default set of renderers, will take the place of the

doc/ref/returners/index.rst

@@ -289,11 +289,10 @@ Place custom returners in a ``_returners`` directory within the
 :conf_master:`file_roots` specified by the master config file.
 
 Custom returners are distributed when any of the following are called:
-    :mod:`state.highstate <salt.modules.state.highstate>`
 
-    :mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>`
-
-    :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
+- :mod:`state.apply <salt.modules.state.apply_>`
+- :mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>`
+- :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
 
 Any custom returners which have been synced to a minion that are named the
 same as one of Salt's default set of returners will take the place of the

doc/ref/states/compiler_ordering.rst

@@ -226,7 +226,7 @@ In the following case:
     include:
       - qux
 
-In the above case if ``state.sls foo`` were called then the formulas will be
+In the above case if ``state.apply foo`` were called then the formulas will be
 loaded in the following order:
 
 1. quo

doc/ref/states/highstate.rst

@@ -34,7 +34,7 @@ Include declaration
 
 Defines a list of :ref:`module-reference` strings to include in this ``SLS``.
 
-Occurs only in the top level of the highstate structure.
+Occurs only in the top level of the SLS data structure.
 
 Example:
 
@@ -58,10 +58,10 @@ file ``salt://edit/vim.sls``.
 ID declaration
 --------------
 
-Defines an individual highstate component. Always references a value of a
-dictionary containing keys referencing :ref:`state-declaration` and
-:ref:`requisite-declaration`. Can be overridden by a :ref:`name-declaration` or
-a :ref:`names-declaration`.
+Defines an individual :ref:`highstate <running-highstate>` component. Always
+references a value of a dictionary containing keys referencing
+:ref:`state-declaration` and :ref:`requisite-declaration`. Can be overridden by
+a :ref:`name-declaration` or a :ref:`names-declaration`.
 
 Occurs on the top level or under the :ref:`extend-declaration`.
 
@@ -72,7 +72,7 @@ ID declarations with the same name will be ignored.
 .. note:: Naming gotchas
 
     In Salt versions earlier than 0.9.7, ID declarations containing dots would
-    result in unpredictable highstate output.
+    result in unpredictable output.
 
 .. _extend-declaration:
 

doc/ref/states/include.rst

@@ -74,10 +74,10 @@ another SLS file or a specific id. The component is excluded after the
 high data has been compiled, so nothing should be able to override an
 exclude.
 
-Since the exclude can remove an id or an SLS the type of component to exclude
+Since the exclude can remove an id or an sls the type of component to exclude
 needs to be defined. An exclude statement that verifies that the running
-highstate does not contain the ``http`` SLS and the ``/etc/vimrc`` id would
-look like this:
+:ref:`highstate <running-highstate>` does not contain the ``http`` sls and the
+``/etc/vimrc`` id would look like this:
 
 .. code-block:: yaml
 
@@ -89,3 +89,4 @@ look like this:
     The current state processing flow checks for duplicate IDs before
     processing excludes. An error occurs if duplicate IDs are present even if
     one of the IDs is targeted by an ``exclude``.
+

doc/ref/states/index.rst

@@ -213,7 +213,7 @@ earlier, requires `pip`_ to be installed system-wide. Let's execute this state:
 
 .. code-block:: bash
 
-    salt-call state.sls pep8
+    salt-call state.apply pep8
 
 The execution output would be something like:
 
@@ -292,7 +292,7 @@ Let's run it, once:
 
 .. code-block:: bash
 
-    salt-call state.sls pep8
+    salt-call state.apply pep8
 
 The output is:
 

doc/ref/states/layers.rst

@@ -46,7 +46,7 @@ Low State
 =========
 
 The `Low State` layer is the list of low chunks "evaluated" in order. To see
-what the low state looks like for a highstate, run:
+what the low state looks like for a :ref:`highstate <running-highstate>`, run:
 
 .. code-block:: bash
 
@@ -96,11 +96,12 @@ The SLS layer can be called directly to execute individual sls formulas.
     in a much more dynamic way by combining pillar and other sources, and the
     SLS can be dynamically generated.
 
-To call a single SLS formula named ``edit.vim``, execute ``state.sls``:
+To call a single SLS formula named ``edit.vim``, execute :py:func:`state.apply
+<salt.modules.state.apply_>` and pass ``edit.vim`` as an argument:
 
 .. code-block:: bash
 
-    salt '*' state.sls edit.vim
+    salt '*' state.apply edit.vim
 
 .. _state-layers-highstate:
 
@@ -116,11 +117,12 @@ assigned from the master without needing to execute or configure anything on
 the target minion. This also means that the minion can independently retrieve
 information about its complete configuration from the master.
 
-To execute the High State call ``state.highstate``:
+To execute the :ref:`highstate <running-highstate>` use :py:func:`state.apply
+<salt.modules.state.apply_>`:
 
 .. code-block:: bash
 
-    salt '*' state.highstate
+    salt '*' state.apply
 
 .. _state-layers-orchestrate:
 
@@ -131,4 +133,4 @@ The orchestrate layer expresses the highest functional layer of Salt's automated
 logic systems. The Overstate allows for stateful and functional orchestration
 of routines from the master. The orchestrate defines in data execution stages
 which minions should execute states, or functions, and in what order using
-requisite logic.
+requisite logic.

doc/ref/states/startup.rst

@@ -13,8 +13,8 @@ executed at startup. The options are `startup_states`, `sls_list`, and
 The `startup_states` option can be passed one of a number of arguments to
 define how to execute states. The available options are:
 
-highstate
-  Execute ``state.highstate``
+:ref:`highstate <running-highstate>`
+  Execute :py:func:`state.apply <salt.modules.state.apply_>`
 
 sls
   Read in the ``sls_list`` option and execute the named sls files
@@ -26,8 +26,8 @@ top
 Examples:
 ---------
 
-Execute ``state.highstate`` when starting the minion:
-
+Execute :py:func:`state.apply <salt.modules.state.apply_>` to run the
+:ref:`highstate <running-highstate>` when starting the minion:
 
 .. code-block:: yaml
 

doc/ref/states/testing.rst

@@ -11,8 +11,8 @@ interface can be invoked on any of the major state run functions:
 
 .. code-block:: bash
 
-    salt '*' state.highstate test=True
-    salt '*' state.sls test=True
+    salt '*' state.apply test=True
+    salt '*' state.apply mysls test=True
     salt '*' state.single test=True
 
 The test run is mandated by adding the ``test=True`` option to the states. The
@@ -28,6 +28,6 @@ states can still be run by calling test=False:
 
 .. code-block:: bash
 
-    salt '*' state.highstate test=False
-    salt '*' state.sls test=False
-    salt '*' state.single test=False
+    salt '*' state.apply test=False
+    salt '*' state.apply mysls test=False
+    salt '*' state.single test=False

doc/ref/states/writing.rst

@@ -56,8 +56,8 @@ Using Custom State Modules
 Place your custom state modules inside a ``_states`` directory within the
 :conf_master:`file_roots` specified by the master config file. These custom
 state modules can then be distributed in a number of ways. Custom state modules
-are distributed when :mod:`state.highstate <salt.modules.state.highstate>` is
-run, or by executing the :mod:`saltutil.sync_states
+are distributed when :py:func:`state.apply <salt.modules.state.apply_>` is run,
+or by executing the :mod:`saltutil.sync_states
 <salt.modules.saltutil.sync_states>` or :mod:`saltutil.sync_all
 <salt.modules.saltutil.sync_all>` functions.
 

doc/topics/cloud/deploy.rst

@@ -65,13 +65,14 @@ Post-Deploy Commands
 ====================
 
 Once a minion has been deployed, it has the option to run a salt command.
-Normally, this would be the state.highstate command, which would finish
-provisioning the VM. Another common option is state.sls, or for just testing,
-test.ping. This is configured in the main cloud config file:
+Normally, this would be the :py:func:`state.apply <salt.modules.state.apply_>`,
+which would finish provisioning the VM. Another common option (for testing) is
+to use :py:func:`test.ping <salt.modules.test.ping>`. This is configured in the
+main cloud config file:
 
 .. code-block:: yaml
 
-    start_action: state.highstate
+    start_action: state.apply
 
 
 This is currently considered to be experimental functionality, and may not work

doc/topics/cloud/reactor.rst

@@ -202,8 +202,8 @@ When Salt Cloud creates an instance, by default it will install the Salt Minion
 onto the instance, along with any specified minion configuration, and
 automatically accept that minion's keys on the master. One of the configuration
 options that can be specified is ``startup_states``, which is commonly set to
-``highstate``. This will tell the minion to immediately apply a highstate, as
-soon as it is able to do so.
+``highstate``. This will tell the minion to immediately apply a :ref:`highstate
+<running-highstate>`, as soon as it is able to do so.
 
 This can present a problem with some system images on some cloud hosts. For
 instance, Salt Cloud can be configured to log in as either the ``root`` user, or
@@ -213,12 +213,13 @@ log in (notably EC2, with their ``ec2-user`` login), most cloud hosts fall
 back to ``root`` as the default login on all images, including for operating
 systems (such as Ubuntu) which normally disallow remote ``root`` login.
 
-For users of these operating systems, it is understandable that a highstate
-would include configuration to block remote ``root`` logins again. However,
-Salt Cloud may not have finished cleaning up its deployment files by the time
-the minion process has started, and kicked off a highstate run. Users have
-reported errors from Salt Cloud getting locked out while trying to clean up
-after itself.
+For users of these operating systems, it is understandable that a
+:ref:`highstate <running-highstate>` would include configuration to block
+remote ``root`` logins again. However, Salt Cloud may not have finished
+cleaning up its deployment files by the time the minion process has started,
+and kicked off a :ref:`highstate <running-highstate>` run. Users have reported
+errors from Salt Cloud getting locked out while trying to clean up after
+itself.
 
 The goal of a startup state may be achieved using the Event Reactor. Because a
 minion fires an event when it is able to receive commands, this event can
@@ -231,17 +232,18 @@ the reactor system to the right ``sls`` file:
       - 'salt/cloud/*/created':
         - '/srv/reactor/startup_highstate.sls'
 
-And the following ``sls`` file will start a highstate run on the target minion:
+And the following ``sls`` file will start a :ref:`highstate
+<running-highstate>` run on the target minion:
 
 .. code-block:: yaml
 
     # /srv/reactor/startup_highstate.sls
     reactor_highstate:
-      cmd.state.highstate:
+      cmd.state.apply:
         - tgt: {{ data['name'] }}
 
 Because this event will not be fired until Salt Cloud has cleaned up after
-itself, the highstate run will not step on Salt Cloud's toes. And because every
-file on the minion is configurable, including ``/etc/salt/minion``, the
-``startup_states`` can still be configured for future minion restarts, if
-desired.
+itself, the :ref:`highstate <running-highstate>` run will not step on
+salt-cloud's toes. And because every file on the minion is configurable,
+including ``/etc/salt/minion``, the ``startup_states`` can still be configured
+for future minion restarts, if desired.

doc/topics/development/conventions/formulas.rst

@@ -367,7 +367,8 @@ variables or interact.
   for :ref:`any of the alternate renderers <all-salt.renderers>` in Salt.)
 * Highstate can be thought of as a human-friendly data structure; easy to write
   and easy to read.
-* Salt's state compiler validates the highstate and compiles it to low state.
+* Salt's state compiler validates the :ref:`highstate <running-highstate>` and
+  compiles it to low state.
 * Low state can be thought of as a machine-friendly data structure. It is a
   list of dictionaries that each map directly to a function call.
 * Salt's state system finally starts and executes on each "chunk" in the low
@@ -1317,9 +1318,9 @@ structure can be performed by with the :py:func:`state.show_sls
     salt '*' state.show_sls apache
 
 Salt Formulas can then be tested by running each ``.sls`` file via
-:py:func:`state.sls <salt.modules.state.sls>` and checking the output for the
-success or failure of each state in the Formula. This should be done for each
-supported platform.
+:py:func:`state.apply <salt.modules.state.apply_>` and checking the output for
+the success or failure of each state in the Formula. This should be done for
+each supported platform.
 
 .. ............................................................................