Merge branch '2015.5' into '2015.8'

Conflicts:
  - doc/ref/states/include.rst
  - doc/topics/cloud/reactor.rst
  - doc/topics/reactor/index.rst
  - doc/topics/releases/2015.5.10.rst
  - doc/topics/tutorials/states_pt5.rst
  - doc/topics/windows/windows-package-manager.rst
  - salt/config.py
  - salt/modules/state.py
  - salt/states/grains.py
  - tests/integration/modules/sysmod.py
  - tests/unit/states/grains_test.py

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
+Custom modules are only synced to Minions when :mod:`state.apply
-<salt.modules.state.highstate>`, :mod:`saltutil.sync_modules
+<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/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
+    mounting /etc/salt/ as read-only for templating this will create a stack
-    stack trace when state.highstate is called.
+    trace when :py:func:`state.apply <salt.modules.state.apply_>` is called.
 
 .. conf_minion:: cache_jobs
 

doc/ref/modules/index.rst

@@ -32,7 +32,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>`
+- :py:func:`state.apply <salt.modules.state.apply_>`
-
+- :py:func:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>`
-    :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
+- :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:`state.apply <salt.modules.state.apply_>`
-
+- :mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>`
-    :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
+- :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
+Defines an individual :ref:`highstate <running-highstate>` component. Always
-dictionary containing keys referencing :ref:`state-declaration` and
+references a value of a dictionary containing keys referencing
-:ref:`requisite-declaration`. Can be overridden by a :ref:`name-declaration` or
+:ref:`state-declaration` and :ref:`requisite-declaration`. Can be overridden by
-a :ref:`names-declaration`.
+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
+:ref:`highstate <running-highstate>` does not contain the ``http`` sls and the
-look like this:
+``/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
+:ref:`highstate <running-highstate>`
-  Execute ``state.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.apply test=True
-    salt '*' state.sls 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.apply test=False
-    salt '*' state.sls test=False
+    salt '*' state.apply mysls test=False
-    salt '*' state.single 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
+are distributed when :py:func:`state.apply <salt.modules.state.apply_>` is run,
-run, or by executing the :mod:`saltutil.sync_states
+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
+Normally, this would be the :py:func:`state.apply <salt.modules.state.apply_>`,
-provisioning the VM. Another common option is state.sls, or for just testing,
+which would finish provisioning the VM. Another common option (for testing) is
-test.ping. This is configured in the main cloud config file:
+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
+``highstate``. This will tell the minion to immediately apply a :ref:`highstate
-soon as it is able to do so.
+<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
+For users of these operating systems, it is understandable that a
-would include configuration to block remote ``root`` logins again. However,
+:ref:`highstate <running-highstate>` would include configuration to block
-Salt Cloud may not have finished cleaning up its deployment files by the time
+remote ``root`` logins again. However, Salt Cloud may not have finished
-the minion process has started, and kicked off a highstate run. Users have
+cleaning up its deployment files by the time the minion process has started,
-reported errors from Salt Cloud getting locked out while trying to clean up
+and kicked off a :ref:`highstate <running-highstate>` run. Users have reported
-after itself.
+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
+itself, the :ref:`highstate <running-highstate>` run will not step on
-file on the minion is configurable, including ``/etc/salt/minion``, the
+salt-cloud's toes. And because every file on the minion is configurable,
-``startup_states`` can still be configured for future minion restarts, if
+including ``/etc/salt/minion``, the ``startup_states`` can still be configured
-desired.
+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
@@ -1302,9 +1303,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
+:py:func:`state.apply <salt.modules.state.apply_>` and checking the output for
-success or failure of each state in the Formula. This should be done for each
+the success or failure of each state in the Formula. This should be done for
-supported platform.
+each supported platform.
 
 .. ............................................................................
 

doc/topics/development/dunder_dictionaries.rst

@@ -91,8 +91,9 @@ During a state run the ``__context__`` dictionary persists across all states
 that are run and then is destroyed when the state ends.
 
 When running an execution module ``__context__`` persists across all module
-executions until the modules are refreshed; such as when ``saltutils.sync_all``
+executions until the modules are refreshed; such as when
-or ``state.highstate`` are executed.
+:py:func:`saltutil.sync_all <salt.modules.saltutil.sync_all>` or
+:py:func:`state.apply <salt.modules.state.apply_>` are executed.
 
 A great place to see how to use ``__context__`` is in the cp.py module in
 salt/modules/cp.py. The fileclient authenticates with the master when it is
@@ -109,4 +110,4 @@ each file. Here is an example from salt/modules/cp.py:
 
 .. note:: Because __context__ may or may not have been destroyed, always be
           sure to check for the existence of the key in __context__ and
-          generate the key before using it.
+          generate the key before using it.

doc/topics/jobs/schedule.rst

@@ -26,25 +26,28 @@ and could step on each other or otherwise double execute.  The default for
 States are executed on the minion, as all states are. You can pass positional
 arguments and provide a yaml dict of named arguments.
 
+The below example will schedule the command ``state.apply httpd test=True``
+every 3600 seconds (every hour):
+
 .. code-block:: yaml
 
     schedule:
       job1:
-        function: state.sls
+        function: state.apply
         seconds: 3600
         args:
           - httpd
         kwargs:
           test: True
 
-This will schedule the command: state.sls httpd test=True every 3600 seconds
+This next example will schedule the command ``state.apply httpd test=True``
-(every hour)
+every 3600 seconds (every hour) splaying the time between 0 and 15 seconds:
 
 .. code-block:: yaml
 
     schedule:
       job1:
-        function: state.sls
+        function: state.apply
         seconds: 3600
         args:
           - httpd
@@ -52,14 +55,15 @@ This will schedule the command: state.sls httpd test=True every 3600 seconds
           test: True
         splay: 15
 
-This will schedule the command: state.sls httpd test=True every 3600 seconds
+Finally, the next example will schedule the command ``state.apply httpd
-(every hour) splaying the time between 0 and 15 seconds
+test=True`` every 3600 seconds (every hour) splaying the time between 10 and 15
+seconds:
 
 .. code-block:: yaml
 
     schedule:
       job1:
-        function: state.sls
+        function: state.apply
         seconds: 3600
         args:
           - httpd
@@ -69,34 +73,34 @@ This will schedule the command: state.sls httpd test=True every 3600 seconds
           start: 10
           end: 15
 
-This will schedule the command: state.sls httpd test=True every 3600 seconds
-(every hour) splaying the time between 10 and 15 seconds
-
 .. versionadded:: 2014.7.0
 
 Frequency of jobs can also be specified using date strings supported by
 the python dateutil library. This requires python-dateutil to be installed on
 the minion.
 
+For example, this will schedule the command ``state.apply httpd test=True`` at
+5:00pm localtime on the minion.
+
 .. code-block:: yaml
 
     schedule:
       job1:
-        function: state.sls
+        function: state.apply
         args:
           - httpd
         kwargs:
           test: True
         when: 5:00pm
 
-This will schedule the command: state.sls httpd test=True at 5:00pm minion
+To schedule the command ``state.apply httpd test=True`` at 5pm on Monday,
-localtime.
+Wednesday, and Friday, and 3pm on Tuesday and Thursday, use the following:
 
 .. code-block:: yaml
 
     schedule:
       job1:
-        function: state.sls
+        function: state.apply
         args:
           - httpd
         kwargs:
@@ -108,14 +112,16 @@ localtime.
             - Thursday 3:00pm
             - Friday 5:00pm
 
-This will schedule the command: state.sls httpd test=True at 5pm on Monday,
+Time ranges are also supported. For example, the below configuration will
-Wednesday, and Friday, and 3pm on Tuesday and Thursday.
+schedule the command ``state.apply httpd test=True`` every 3600 seconds (every
+hour) between the hours of 8am and 5pm. The range parameter must be a
+dictionary with the date strings using the ``dateutil`` format.
 
 .. code-block:: yaml
 
     schedule:
       job1:
-        function: state.sls
+        function: state.apply
         seconds: 3600
         args:
           - httpd
@@ -125,18 +131,18 @@ Wednesday, and Friday, and 3pm on Tuesday and Thursday.
             start: 8:00am
             end: 5:00pm
 
-This will schedule the command: state.sls httpd test=True every 3600 seconds
+.. note::
-(every hour) between the hours of 8am and 5pm.  The range parameter must be a
+    Using time ranges requires python-dateutil_ to be installed on the minion.
-dictionary with the date strings using the dateutil format. This requires
+
-python-dateutil to be installed on the minion.
+.. _python-dateutil: https://github.com/dateutil/dateutil#dateutil---powerful-extensions-to-datetime
 
 .. versionadded:: 2014.7.0
 
-The scheduler also supports ensuring that there are no more than N copies of
+The scheduler also supports ensuring that there are no more than N copies of a
-a particular routine running.  Use this for jobs that may be long-running
+particular routine running. Use this for jobs that may be long-running and
-and could step on each other or pile up in case of infrastructure outage.
+could step on each other or pile up in case of infrastructure outage.
 
-The default for maxrunning is 1.
+The default for ``maxrunning`` is 1.
 
 .. code-block:: yaml
 
@@ -163,14 +169,14 @@ States
 Highstates
 ==========
 
-To set up a highstate to run on a minion every 60 minutes set this in the
+To set up a :ref:`highstate <running-highstate>` to run on a minion every 60
-minion config or pillar:
+minutes set this in the minion config or pillar:
 
 .. code-block:: yaml
 
     schedule:
       highstate:
-        function: state.highstate
+        function: state.apply
         minutes: 60
 
 Time intervals can be specified as seconds, minutes, hours, or days.

doc/topics/master_tops/index.rst

@@ -3,8 +3,8 @@ Master Tops System
 ==================
 
 In 0.10.4 the `external_nodes` system was upgraded to allow for modular
-subsystems to be used to generate the top file data for a highstate run on
+subsystems to be used to generate the top file data for a :ref:`highstate
-the master.
+<running-highstate>` run on the master.
 
 The old `external_nodes` option has been removed.
 The master tops system contains a number of subsystems that
@@ -74,4 +74,4 @@ a degenerate example:
    minion
        ----------
        base:
-         - test
+         - test

doc/topics/pillar/index.rst

@@ -352,14 +352,9 @@ Pillar data can be set at the command line like the following example:
 
 .. code-block:: bash
 
-    salt '*' state.highstate pillar='{"cheese": "spam"}'
+    salt '*' state.apply pillar='{"cheese": "spam"}'
 
-This will create a dict with a key of 'cheese' and a value of 'spam'. A list
+This will add a Pillar key of ``cheese`` with its value set to ``spam``.
-can be created like this:
-
-.. code-block:: bash
-
-    salt '*' state.highstate pillar='["cheese", "milk", "bread"]'
 
 .. note::
 

doc/topics/reactor/index.rst

@@ -75,7 +75,7 @@ Here is a simple reactor sls:
 
     {% if data['id'] == 'mysql1' %}
     highstate_run:
-      local.state.highstate:
+      local.state.apply:
         - tgt: mysql1
     {% endif %}
 
@@ -85,8 +85,8 @@ the minion is ``mysql1``) then the following reaction is defined.  The same
 data structure and compiler used for the state system is used for the reactor
 system. The only difference is that the data is matched up to the salt command
 API and the runner system.  In this example, a command is published to the
-``mysql1`` minion with a function of ``state.highstate``. Similarly, a runner
+``mysql1`` minion with a function of :py:func:`state.apply
-can be called:
+<salt.modules.state.apply_>`. Similarly, a runner can be called:
 
 .. code-block:: yaml
 
@@ -306,8 +306,8 @@ Passing event data to Minions or Orchestrate as Pillar
 ------------------------------------------------------
 
 An interesting trick to pass data from the Reactor script to
-``state.highstate`` or ``state.sls`` is to pass it as inline Pillar data since
+:py:func:`state.apply <salt.modules.state.apply_>` is to pass it as inline
-both functions take a keyword argument named ``pillar``.
+Pillar data since both functions take a keyword argument named ``pillar``.
 
 The following example uses Salt's Reactor to listen for the event that is fired
 when the key for a new minion is accepted on the master using ``salt-key``.
@@ -320,9 +320,9 @@ when the key for a new minion is accepted on the master using ``salt-key``.
       - 'salt/key':
         - /srv/salt/haproxy/react_new_minion.sls
 
-The Reactor then fires a ``state.sls`` command targeted to the HAProxy servers
+The Reactor then fires a ::py:func:`state.apply <salt.modules.state.apply_>`
-and passes the ID of the new minion from the event to the state file via inline
+command targeted to the HAProxy servers and passes the ID of the new minion
-Pillar.
+from the event to the state file via inline Pillar.
 
 :file:`/srv/salt/haproxy/react_new_minion.sls`:
 
@@ -330,7 +330,7 @@ Pillar.
 
     {% if data['act'] == 'accept' and data['id'].startswith('web') %}
     add_new_minion_to_pool:
-      local.state.sls:
+      local.state.apply:
         - tgt: 'haproxy*'
         - arg:
           - haproxy.refresh_pool
@@ -343,7 +343,7 @@ The above command is equivalent to the following command at the CLI:
 
 .. code-block:: bash
 
-    salt 'haproxy*' state.sls haproxy.refresh_pool 'pillar={new_minion: minionid}'
+    salt 'haproxy*' state.apply haproxy.refresh_pool 'pillar={new_minion: minionid}'
 
 This works with Orchestrate files as well:
 
@@ -391,9 +391,9 @@ In this example, we're going to assume that we have a group of servers that
 will come online at random and need to have keys automatically accepted. We'll
 also add that we don't want all servers being automatically accepted. For this
 example, we'll assume that all hosts that have an id that starts with 'ink'
-will be automatically accepted and have state.highstate executed. On top of
+will be automatically accepted and have :py:func:`state.apply
-this, we're going to add that a host coming up that was replaced (meaning a new
+<salt.modules.state.apply_>` executed. On top of this, we're going to add that
-key) will also be accepted.
+a host coming up that was replaced (meaning a new key) will also be accepted.
 
 Our master configuration will be rather simple. All minions that attempte to
 authenticate will match the :strong:`tag` of :strong:`salt/auth`. When it comes
@@ -448,17 +448,17 @@ Ink servers in the master configuration.
 
 .. code-block:: yaml
 
-    {# When an Ink server connects, run state.highstate. #}
+    {# When an Ink server connects, run state.apply. #}
     highstate_run:
-      local.state.highstate:
+      local.state.apply:
         - tgt: {{ data['id'] }}
         - ret: smtp
 
-The above will also return the highstate result data using the `smtp_return`
+The above will also return the :ref:`highstate <running-highstate>` result data
-returner (use virtualname like when using from the command line with `--return`).
+using the `smtp_return` returner (use virtualname like when using from the
-The returner needs to be configured on the minion for this to work.
+command line with `--return`).  The returner needs to be configured on the
-See :mod:`salt.returners.smtp_return <salt.returners.smtp_return>` documentation
+minion for this to work.  See :mod:`salt.returners.smtp_return
-for that.
+<salt.returners.smtp_return>` documentation for that.
 
 .. _minion-start-reactor:
 
@@ -466,11 +466,12 @@ Syncing Custom Types on Minion Start
 ====================================
 
 Salt will sync all custom types (by running a :mod:`saltutil.sync_all
-<salt.modules.saltutil.sync_all>`) on every highstate. However, there is a
+<salt.modules.saltutil.sync_all>`) on every :ref:`highstate
-chicken-and-egg issue where, on the initial highstate, a minion will not yet
+<running-highstate>`. However, there is a chicken-and-egg issue where, on the
-have these custom types synced when the top file is first compiled. This can be
+initial :ref:`highstate <running-highstate>`, a minion will not yet have these
-worked around with a simple reactor which watches for ``minion_start`` events,
+custom types synced when the top file is first compiled. This can be worked
-which each minion fires when it first starts up and connects to the master.
+around with a simple reactor which watches for ``minion_start`` events, which
+each minion fires when it first starts up and connects to the master.
 
 On the master, create **/srv/reactor/sync_grains.sls** with the following
 contents:
@@ -490,8 +491,8 @@ And in the master config file, add the following reactor configuration:
         - /srv/reactor/sync_grains.sls
 
 This will cause the master to instruct each minion to sync its custom grains
-when it starts, making these grains available when the initial highstate is
+when it starts, making these grains available when the initial :ref:`highstate
-executed.
+<running-highstate>` is executed.
 
 Other types can be synced by replacing ``local.saltutil.sync_grains`` with
 ``local.saltutil.sync_modules``, ``local.saltutil.sync_all``, or whatever else

doc/topics/releases/2015.5.10.rst

@@ -19,3 +19,16 @@ in the Salt Master configuration.
 
 (No additional fixes are contained in this release).
 
+Read Before Upgrading Debian 8 (Jessie) from Salt Versions Earlier than 2015.5.9
+================================================================================
+
+Salt ``systemd`` service files are missing the following statement in these versions:
+
+.. code-block:: ini
+
+    [Service]
+    KillMode=process
+
+This statement must be added to successfully upgrade on these earlier versions
+of Salt.
+

doc/topics/targeting/grains.rst

@@ -168,12 +168,11 @@ keys in the :ref:`dict <python2:typesmapping>` are the names of the grains and
 the values are the values.
 
 Custom grains should be placed in a ``_grains`` directory located under the
-:conf_master:`file_roots` specified by the master config file.  The default path
+:conf_master:`file_roots` specified by the master config file.  The default
-would be ``/srv/salt/_grains``.  Custom grains will be
+path would be ``/srv/salt/_grains``.  Custom grains will be distributed to the
-distributed to the minions when :mod:`state.highstate
+minions when :py:func:`state.apply <salt.modules.state.apply_>` is run, or by
-<salt.modules.state.highstate>` is run, or by executing the
+executing the :mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>`
-:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
+or :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
-:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
 
 Grains are easy to write, and only need to return a dictionary.  A common
 approach would be code something similar to the following:
@@ -197,9 +196,9 @@ change, consider using :doc:`Pillar <../pillar/index>` instead.
 
     Custom grains will not be available in the top file until after the first
     :ref:`highstate <running-highstate>`. To make custom grains available on a
-    minion's first highstate, it is recommended to use :ref:`this example
+    minion's first :ref:`highstate <running-highstate>`, it is recommended to
-    <minion-start-reactor>` to ensure that the custom grains are synced when
+    use :ref:`this example <minion-start-reactor>` to ensure that the custom
-    the minion starts.
+    grains are synced when the minion starts.
 
 Loading Custom Grains
 ---------------------
@@ -295,7 +294,7 @@ Syncing Grains
 ==============
 
 Syncing grains can be done a number of ways, they are automatically synced when
-:mod:`state.highstate <salt.modules.state.highstate>` is called, or (as noted
+:mod:`state.apply <salt.modules.state.apply_>` is called, or (as noted above)
-above) the grains can be manually synced and reloaded by calling the
+the grains can be manually synced and reloaded by calling the
 :mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
 :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.

doc/topics/troubleshooting/index.rst

@@ -85,17 +85,17 @@ The ``salt-call`` command was originally developed for aiding in the development
 of new Salt modules. Since then, many applications have been developed for
 running any Salt module locally on a minion. These range from the original
 intent of salt-call, development assistance, to gathering more verbose output
-from calls like :mod:`state.highstate <salt.modules.state.highstate>`.
+from calls like :mod:`state.apply <salt.modules.state.apply_>`.
 
-When creating your state tree, it is generally recommended to invoke
+When initially creating your state tree, it is generally recommended to invoke
-:mod:`state.highstate <salt.modules.state.highstate>` with ``salt-call``. This
+:mod:`state.apply <salt.modules.state.apply_>` directly from the minion with
-displays far more information about the highstate execution than calling it
+``salt-call``, rather than remotely from the master. This displays far more
-remotely. For even more verbosity, increase the loglevel with the same argument
+information about the execution than calling it remotely. For even more
-as ``salt-minion``:
+verbosity, increase the loglevel using the ``-l`` argument:
 
 .. code-block:: bash
 
-    salt-call -l debug state.highstate
+    salt-call -l debug state.apply
 
 The main difference between using ``salt`` and using ``salt-call`` is that
 ``salt-call`` is run from the minion, and it only runs the selected function on
@@ -262,4 +262,4 @@ Debugging the Master and Minion
 
 A list of common :doc:`master</topics/troubleshooting/master>` and
 :doc:`minion</topics/troubleshooting/minion>` troubleshooting steps provide a
-starting point for resolving issues you may encounter.
+starting point for resolving issues you may encounter.

doc/topics/troubleshooting/master.rst

@@ -181,8 +181,9 @@ Commands Time Out or Do Not Return Output
 =========================================
 
 Depending on your OS (this is most common on Ubuntu due to apt-get) you may
-sometimes encounter times where your highstate, or other long running commands
+sometimes encounter times where a :py:func:`state.apply
-do not return output.
+<salt.modules.state.apply_>`, or other long running commands do not return
+output.
 
 By default the timeout is set to 5 seconds. The timeout value can easily be
 increased by modifying the ``timeout`` line within your ``/etc/salt/master``

doc/topics/troubleshooting/minion.rst

@@ -71,21 +71,21 @@ check that no additional access control system such as `SELinux`_ or
 Using salt-call
 ===============
 
-The ``salt-call`` command was originally developed for aiding in the development
+The ``salt-call`` command was originally developed for aiding in the
-of new Salt modules. Since then, many applications have been developed for
+development of new Salt modules. Since then, many applications have been
-running any Salt module locally on a minion. These range from the original
+developed for running any Salt module locally on a minion. These range from the
-intent of salt-call, development assistance, to gathering more verbose output
+original intent of salt-call (development assistance), to gathering more
-from calls like :mod:`state.highstate <salt.modules.state.highstate>`.
+verbose output from calls like :mod:`state.apply <salt.modules.state.apply_>`.
 
 When initially creating your state tree, it is generally recommended to invoke
-:mod:`state.highstate <salt.modules.state.highstate>` from the minion with
+highstates by running :mod:`state.apply <salt.modules.state.apply_>` directly
-``salt-call``. This displays far more information about the highstate execution
+from the minion with ``salt-call``, rather than remotely from the master. This
-than calling it remotely. For even more verbosity, increase the loglevel with
+displays far more information about the execution than calling it remotely. For
-the same argument as ``salt-minion``:
+even more verbosity, increase the loglevel using the ``-l`` argument:
 
 .. code-block:: bash
 
-    # salt-call -l debug state.highstate
+    # salt-call -l debug state.apply
 
 The main difference between using ``salt`` and using ``salt-call`` is that
 ``salt-call`` is run from the minion, and it only runs the selected function on
@@ -148,4 +148,4 @@ salt-minion service.
 
     Modifying the minion timeout value is not required when running commands
     from a Salt Master. It is only required when running commands locally on
-    the minion.
+    the minion.

doc/topics/tutorials/cron.rst

@@ -1,32 +1,38 @@
-===============================================
 Using cron with Salt
-===============================================
+====================
 
-The Salt Minion can initiate its own highstate using the ``salt-call`` command.
+The Salt Minion can initiate its own :ref:`highstate <running-highstate>` using
+the ``salt-call`` command.
 
 .. code-block:: bash
 
-    $ salt-call state.highstate
+    $ salt-call state.apply
 
 
 This will cause the minion to check in with the master and ensure it is in the
-correct 'state'.
+correct "state".
 
 
 Use cron to initiate a highstate
 ================================
 
 If you would like the Salt Minion to regularly check in with the master you can
-use the venerable cron to run the ``salt-call`` command.
+use cron to run the ``salt-call`` command:
 
 .. code-block:: bash
 
-    # PATH=/bin:/sbin:/usr/bin:/usr/sbin
+    0 0 * * * salt-call state.apply
 
-    00 00 * * * salt-call state.highstate
+The above cron entry will run a :ref:`highstate <running-highstate>` every day
-
+at midnight.
-The above cron entry will run a highstate every day at midnight.
 
 .. note::
-    Be aware that you may need to ensure the PATH for cron includes any
+    When executing Salt using cron, keep in mind that the default PATH for cron
-    scripts or commands that need to be executed.
+    may not include the path for any scripts or commands used by Salt, and it
+    may be necessary to set the PATH accordingly in the crontab:
+
+    .. code-block:: cron
+
+        PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin
+
+        0 0 * * * salt-call state.apply

doc/topics/tutorials/multimaster_pki.rst

@@ -149,10 +149,11 @@ In a case like this, it should be checked, that the verification pubkey
 Once the verification is successful, the minion can be started in daemon mode
 again.
 
-For the paranoid among us, its also possible to verify the public whenever it
+For the paranoid among us, its also possible to verify the publication whenever
-is received from the master. That is, for every single auth-attempt which can be
+it is received from the master. That is, for every single auth-attempt which
-quite frequent. For example just the start of the minion will force the signature
+can be quite frequent. For example just the start of the minion will force the
-to be checked 6 times for various things like auth, mine, highstate, etc.
+signature to be checked 6 times for various things like auth, mine,
+:ref:`highstate <running-highstate>`, etc.
 
 If that is desired, enable the setting
 
@@ -162,7 +163,6 @@ If that is desired, enable the setting
     always_verify_signature: True
 
 
-
 Multiple Masters For A Minion
 =============================
 

doc/topics/tutorials/pillar.rst

@@ -297,18 +297,13 @@ Ensuring that the right vimrc is sent out to the correct minions.
 Setting Pillar Data on the Command Line
 =======================================
 
-Pillar data can be set on the command line like so:
+Pillar data can be set on the command line when running :py:func:`state.apply
+<salt.modules.state.apply_` like so:
 
 .. code-block:: bash
 
-    salt '*' state.highstate pillar='{"foo": "bar"}'
+    salt '*' state.apply pillar='{"foo": "bar"}'
-
+    salt '*' state.apply my_sls_file pillar='{"hello": "world"}'
-The ``state.sls`` command can also be used to set pillar values via the command
-line:
-
-.. code-block:: bash
-
-    salt '*' state.sls my_sls_file pillar='{"hello": "world"}'
 
 .. note::
 
@@ -321,7 +316,7 @@ specified list, notice the nested pillar dict:
 
 .. code-block:: bash
 
-    salt '*' state.sls edit.vim pillar='{"pkgs": {"vim": "telnet"}}'
+    salt '*' state.apply edit.vim pillar='{"pkgs": {"vim": "telnet"}}'
 
 .. note::
 

doc/topics/tutorials/preseed_key.rst

@@ -63,6 +63,5 @@ You will want to place the minion keys before starting the salt-minion daemon:
     /etc/salt/pki/minion/minion.pem
     /etc/salt/pki/minion/minion.pub
 
-Once in place, you should be able to start salt-minion and run
+Once in place, you should be able to start salt-minion and run ``salt-call
-``salt-call state.highstate`` or any other salt commands that require master
+state.apply`` or any other salt commands that require master authentication.
-authentication.

doc/topics/tutorials/quickstart.rst

@@ -99,21 +99,20 @@ ensures that the server has the Apache webserver installed.
     instance on Debian/Ubuntu it is apache2, on Fedora/RHEL it is httpd
     and on Arch it is apache
 
-The only thing left is to provision our minion using salt-call and the
+The only thing left is to provision our minion using ``salt-call``.
-highstate command.
 
 Salt-call
 ---------
 
-The salt-call command is used to run module functions locally on a minion
+The salt-call command is used to run remote execution functions locally on a
-instead of executing them from the master. Normally the salt-call command
+minion instead of executing them from the master. Normally the salt-call
-checks into the master to retrieve file server and pillar data, but when
+command checks into the master to retrieve file server and pillar data, but
-running standalone salt-call needs to be instructed to not check the master for
+when running standalone salt-call needs to be instructed to not check the
-this data:
+master for this data:
 
 .. code-block:: bash
 
-    salt-call --local state.highstate
+    salt-call --local state.apply
 
 The ``--local`` flag tells the salt-minion to look for the state tree in the
 local file system and not to contact a Salt Master for instructions.
@@ -122,7 +121,7 @@ To provide verbose output, use ``-l debug``:
 
 .. code-block:: bash
 
-    salt-call --local state.highstate -l debug
+    salt-call --local state.apply -l debug
 
 The minion first examines the ``top.sls`` file and determines that it is a part
 of the group matched by ``*`` glob and that the ``webserver`` SLS should be applied.

doc/topics/tutorials/standalone_minion.rst

@@ -72,14 +72,14 @@ The declared state can now be executed with:
 
 .. code-block:: bash
 
-    salt-call state.highstate
+    salt-call state.apply
 
 Or the salt-call command can be executed with the ``--local`` flag, this makes
 it unnecessary to change the configuration file:
 
 .. code-block:: bash
 
-    salt-call state.highstate --local
+    salt-call state.apply --local
 
 External Pillars
 ================

doc/topics/tutorials/starting_states.rst

@@ -538,12 +538,17 @@ Running and debugging salt states.
 
 Once the rules in an SLS are ready, they should be tested to ensure they
 work properly. To invoke these rules, simply execute
-``salt '*' state.highstate`` on the command line. If you get back only
+``salt '*' state.apply`` on the command line. If you get back only
 hostnames with a ``:`` after, but no return, chances are there is a problem with
-one or more of the sls files. On the minion, use the ``salt-call`` command:
+one or more of the sls files. On the minion, use the ``salt-call`` command to
-``salt-call state.highstate -l debug`` to examine the output for errors.
+examine the output for errors:
-This should help troubleshoot the issue. The minions can also be started in
+
-the foreground in debug mode: ``salt-minion -l debug``.
+.. code-block:: bash
+
+    salt-call state.apply -l debug
+
+This should help troubleshoot the issue. The minion can also be started in the
+foreground in debug mode by running ``salt-minion -l debug``.
 
 Next Reading
 ============

doc/topics/tutorials/states_pt1.rst

@@ -68,7 +68,7 @@ collection of minion matches is defined; for now simply specify all hosts
     .. code-block:: yaml
 
         base:
-          'os:Fedora':
+          'G@os:Fedora':
             - match: grain
             - webserver
 
@@ -125,13 +125,31 @@ Next, let's run the state we created. Open a terminal on the master and run:
 
 .. code-block:: bash
 
-    % salt '*' state.highstate
+    salt '*' state.apply
 
-Our master is instructing all targeted minions to run :func:`state.highstate
+Our master is instructing all targeted minions to run :func:`state.apply
-<salt.modules.state.highstate>`. When a minion executes a highstate call it
+<salt.modules.state.apply>`. When this function is executied without any SLS
-will download the :ref:`top file <states-top>` and attempt to match the
+targets, a minion will download the :ref:`top file <states-top>` and attempt to
-expressions. When it does match an expression the modules listed for it will be
+match the expressions within it. When the minion does match an expression the
-downloaded, compiled, and executed.
+modules listed for it will be downloaded, compiled, and executed.
+
+.. note::
+    This action is referred to as a "highstate", and can be run using the
+    :py:func:`state.highstate <salt.modules.state.highstate>` function.
+    However, to make the usage easier to understand ("highstate" is not
+    necessarily an intuitive name), a :py:func:`state.apply
+    <salt.modules.state.apply_>` function was added in version 2015.5.0, which
+    when invoked without any SLS names will trigger a highstate.
+    :py:func:`state.highstate <salt.modules.state.highstate>` still exists and
+    can be used, but the documentation (as can be seen above) has been updated
+    to reference :py:func:`state.apply <salt.modules.state.apply_>`, so keep
+    the following in mind as you read the documentation:
+
+    - :py:func:`state.apply <salt.modules.state.apply_>` invoked without any
+      SLS names will run :py:func:`state.highstate
+      <salt.modules.state.highstate>`
+    - :py:func:`state.apply <salt.modules.state.apply_>` invoked with SLS names
+      will run :py:func:`state.sls <salt.modules.state.sls>`
 
 Once completed, the minion will report back with a summary of all actions taken
 and all changes made.
@@ -141,9 +159,9 @@ and all changes made.
     If you have created :ref:`custom grain modules <writing-grains>`, they will
     not be available in the top file until after the first :ref:`highstate
     <running-highstate>`. To make custom grains available on a minion's first
-    highstate, it is recommended to use :ref:`this example
+    :ref:`highstate <running-highstate>`, it is recommended to use :ref:`this
-    <minion-start-reactor>` to ensure that the custom grains are synced when
+    example <minion-start-reactor>` to ensure that the custom grains are synced
-    the minion starts.
+    when the minion starts.
 
 .. _sls-file-namespace:
 .. admonition:: SLS File Namespace
@@ -190,7 +208,7 @@ and all changes made.
 
         .. code-block:: bash
 
-            salt-minion &
+            salt-minion
 
     Increase the default timeout value when running :command:`salt`. For
     example, to change the default timeout to 60 seconds:
@@ -203,8 +221,8 @@ and all changes made.
 
     .. code-block:: bash
 
-        salt-minion -l debug &          # On the minion
+        salt-minion -l debug        # On the minion
-        salt '*' state.highstate -t 60  # On the master
+        salt '*' state.apply -t 60  # On the master
 
 Next steps
 ==========

doc/topics/tutorials/states_pt2.rst

@@ -28,8 +28,8 @@ You can specify multiple :ref:`state-declaration` under an
         - require:
           - pkg: apache
 
-Try stopping Apache before running ``state.highstate`` once again and observe
+Try stopping Apache before running :py:func:`state.apply
-the output.
+<salt.modules.state.apply_>` once again and observe the output.
 
 .. note::
 
@@ -101,13 +101,13 @@ directory:
         </body>
     </html>
 
-Last, call :func:`state.highstate <salt.modules.state.highstate>` again and the
+Last, call :func:`state.apply <salt.modules.state.apply_>` again and the minion
-minion will fetch and execute the highstate as well as our HTML file from the
+will fetch and execute the :ref:`highstate <running-highstate>` as well as our
-master using Salt's File Server:
+HTML file from the master using Salt's File Server:
 
 .. code-block:: bash
 
-    salt '*' state.highstate
+    salt '*' state.apply
 
 Verify that Apache is now serving your custom HTML.
 

doc/topics/tutorials/states_pt4.rst

@@ -153,20 +153,21 @@ Given the above SLS, the source for the website should initially be placed in
 ``/srv/salt/dev/webserver/src/foobarcom``.
 
 First, let's deploy to dev. Given the configuration in the top file, this can
-be done using :mod:`state.highstate <salt.modules.state.highstate>`:
+be done using :py:func:`state.apply <salt.modules.state.apply_>`:
 
 .. code-block:: bash
 
-    salt --pillar 'webserver_role:dev' state.highstate
+    salt --pillar 'webserver_role:dev' state.apply
 
 However, in the event that it is not desirable to apply all states configured
 in the top file (which could be likely in more complex setups), it is possible
-to apply just the states for the ``foobarcom`` website, using :mod:`state.sls
+to apply just the states for the ``foobarcom`` website, by invoking
-<salt.modules.state.sls>`:
+:py:func:`state.apply <salt.modules.state.apply_>` with the desired SLS target
+as an argument:
 
 .. code-block:: bash
 
-    salt --pillar 'webserver_role:dev' state.sls webserver.foobarcom
+    salt --pillar 'webserver_role:dev' state.apply webserver.foobarcom
 
 Once the site has been tested in dev, then the files can be moved from
 ``/srv/salt/dev/webserver/src/foobarcom`` to
@@ -174,7 +175,7 @@ Once the site has been tested in dev, then the files can be moved from
 
 .. code-block:: bash
 
-    salt --pillar 'webserver_role:qa' state.sls webserver.foobarcom
+    salt --pillar 'webserver_role:qa' state.apply webserver.foobarcom
 
 Finally, once the site has been tested in qa, then the files can be moved from
 ``/srv/salt/qa/webserver/src/foobarcom`` to
@@ -182,7 +183,7 @@ Finally, once the site has been tested in qa, then the files can be moved from
 
 .. code-block:: bash
 
-    salt --pillar 'webserver_role:prod' state.sls webserver.foobarcom
+    salt --pillar 'webserver_role:prod' state.apply webserver.foobarcom
 
 Thanks to Salt's fileserver inheritance, even though the files have been moved
 to within ``/srv/salt/prod``, they are still available from the same

doc/topics/tutorials/states_pt5.rst

@@ -35,31 +35,32 @@ The Orchestrate Runner
   2015.8.0.
 
 The orchestrate runner generalizes the Salt state system to a Salt master
-context.  Whereas the ``state.sls``, ``state.highstate``, et al functions are
+context.  Whereas :py:func:`state.apply <salt.modules.state.apply_>` is
 concurrently and independently executed on each Salt minion, the
-``state.orchestrate`` runner is executed on the master, giving it a
+:py:func:`state.orchestrate <salt.runners.state.orchestrate>` runner is
-master-level view and control over requisites, such as state ordering and
+executed on the master, giving it a master-level view and control over
-conditionals.  This allows for inter minion requisites, like ordering the
+requisites, such as state ordering and conditionals.  This allows for inter
-application of states on different minions that must not happen simultaneously,
+minion requisites, like ordering the application of states on different minions
-or for halting the state run on all minions if a minion fails one of its
+that must not happen simultaneously, or for halting the state run on all
-states.
+minions if a minion fails one of its states.
 
 If you want to setup a load balancer in front of a cluster of web servers, for
 example, you can ensure the load balancer is setup before the web servers or
 stop the state run altogether if one of the minions does not set up correctly.
 
-The ``state.sls``, ``state.highstate``, et al functions allow you to statefully
+:py:func:`state.apply <salt.modules.state.apply_>` allows you to statefully
-manage each minion and the ``state.orchestrate`` runner allows you to
+manage each minion and the :py:func:`state.orchestrate
-statefully manage your entire infrastructure.
+<salt.runners.state.orchestrate>` runner allows you to statefully manage your
+entire infrastructure.
 
 Executing the Orchestrate Runner
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The Orchestrate Runner command format is the same as for the ``state.sls``
+The Orchestrate Runner command format is the same as for the
-function, except that since it is a runner, it is executed with ``salt-run``
+:py:func:`state.sls <salt.modules.state.sls>` function, except that since it is
-rather than ``salt``.  Assuming you have a state.sls file called
+a runner, it is executed with ``salt-run`` rather than ``salt``.  Assuming you
-``/srv/salt/orch/webserver.sls`` the following command run on the master will
+have a state.sls file called ``/srv/salt/orch/webserver.sls`` the following
-apply the states defined in that file.
+command run on the master will apply the states defined in that file.
 
 .. code-block:: bash
 
@@ -72,8 +73,8 @@ apply the states defined in that file.
 .. versionchanged:: 2014.1.1
 
     The runner function was renamed to ``state.orchestrate`` to avoid confusion
-    with the :mod:`state.sls <salt.modules.state.sls>` execution function. In
+    with the :mod:`state.sls <salt.modules.state.sls>` remote execution
-    versions 0.17.0 through 2014.1.0, ``state.sls`` must be used.
+    function. In versions 0.17.0 through 2014.1.0, ``state.sls`` must be used.
 
 Examples
 ~~~~~~~~
@@ -117,7 +118,8 @@ To execute a state, use :mod:`salt.state <salt.states.saltmod.state>`.
 Highstate
 ^^^^^^^^^
 
-To run a highstate, set ``highstate: True`` in your state config:
+To run a :ref:`highstate <running-highstate>`, set ``highstate: True`` in your
+state config:
 
 .. code-block:: yaml
 

doc/topics/tutorials/walkthrough.rst

@@ -510,7 +510,7 @@ Now install vim on the minions by calling the SLS directly:
 
 .. code-block:: bash
 
-    salt '*' state.sls vim
+    salt '*' state.apply vim
 
 This command will invoke the state system and run the ``vim`` SLS.
 
@@ -586,14 +586,13 @@ This formula can be referenced via the following command:
 
 .. code-block:: bash
 
-    salt '*' state.sls nginx
+    salt '*' state.apply nginx
 
 .. note::
-    Reminder!
+    :py:func:`state.apply <salt.modules.state.apply_>` is just another remote
-
+    execution function, just like :py:func:`test.ping <salt.modules.test.ping>`
-    Just as one could call the ``test.ping`` or ``disk.usage`` execution modules,
+    or :py:func:`disk.usage <salt.modules.disk.usage>`. It simply takes the
-    ``state.sls`` is simply another execution module. It simply takes the name of an
+    name of an SLS file as an argument.
-    SLS file as an argument.
 
 Now that subdirectories can be used, the ``vim.sls`` formula can be cleaned up.
 To make things more flexible, move the ``vim.sls`` and vimrc into a new subdirectory

doc/topics/tutorials/walkthrough_macosx.rst

@@ -428,10 +428,10 @@ error saying the site cannot be reached.
 Initialize the top.sls file
 ---------------------------
 
-System configuration is done in the /srv/salt/top.sls file (and
+System configuration is done in ``/srv/salt/top.sls`` (and subfiles/folders),
-subfiles/folders), and then applied by running the ``state.highstate``
+and then applied by running the :py:func:`state.apply
-command to have the Salt master give orders so minions will update their
+<salt.modules.state.apply_>` function to have the Salt master order its minions
-instructions and run the associated commands.
+to update their instructions and run the associated commands.
 
 First Create an empty file on your Salt master (Mac OS X machine):
 
@@ -444,10 +444,10 @@ an error is reported:
 
 .. code-block:: bash
 
-    sudo salt 'minion1' state.highstate
+    sudo salt 'minion1' state.apply
 
-Should return an error stating:
+This should return an error stating: **No Top file or external nodes data
-"No Top file or external nodes data matches found".
+matches found**.
 
 Create The Nginx Configuration
 ------------------------------
@@ -456,8 +456,8 @@ Now is finally the time to enter the real meat of our server's configuration.
 For this tutorial our minion will be treated as a web server that needs to
 have Nginx installed.
 
-Insert the following lines into the ``/srv/salt/top.sls`` file (which should
+Insert the following lines into ``/srv/salt/top.sls`` (which should current be
-current be empty).
+empty).
 
 .. code-block:: yaml
 
@@ -465,7 +465,7 @@ current be empty).
       'minion1':
         - bin.nginx
 
-Now create a ``/srv/salt/bin/nginx.sls`` file containing the following:
+Now create ``/srv/salt/bin/nginx.sls`` containing the following:
 
 .. code-block:: yaml
 
@@ -479,11 +479,12 @@ Now create a ``/srv/salt/bin/nginx.sls`` file containing the following:
 Check Minion State
 ------------------
 
-Finally run the state.highstate command again:
+Finally, run the :py:func:`state.apply <salt.modules.state.apply_>` function
+again:
 
 .. code-block:: bash
 
-    sudo salt 'minion1' state.highstate
+    sudo salt 'minion1' state.apply
 
 You should see a log showing that the Nginx package has been installed
 and the service configured. To prove it, open your browser and navigate to

salt/config.py

@@ -63,7 +63,7 @@ FLO_DIR = os.path.join(
 
 VALID_OPTS = {
     # The address of the salt master. May be specified as IP address or hostname
-    'master': str,
+    'master': (str, list),
 
     # The TCP/UDP port of the master to connect to in order to listen to publications
     'master_port': int,
@@ -1348,26 +1348,30 @@ def _validate_opts(opts):
     Check that all of the types of values passed into the config are
     of the right types
     '''
+    def format_multi_opt(valid_type):
+        try:
+            num_types = len(valid_type)
+        except TypeError:
+            # Bare type name won't have a length, return the name of the type
+            # passed.
+            return valid_type.__name__
+        else:
+            if num_types == 1:
+                return valid_type.__name__
+            elif num_types > 1:
+                ret = ', '.join(x.__name__ for x in valid_type[:-1])
+                ret += ' or ' + valid_type[-1].__name__
+
     errors = []
-    err = ('Key {0} with value {1} has an invalid type of {2}, a {3} is '
+
+    err = ('Key \'{0}\' with value {1} has an invalid type of {2}, a {3} is '
            'required for this value')
     for key, val in six.iteritems(opts):
         if key in VALID_OPTS:
-            if isinstance(VALID_OPTS[key](), list):
+            if isinstance(val, VALID_OPTS[key]):
-                if isinstance(val, VALID_OPTS[key]):
+                continue
-                    continue
+
-                else:
+            if hasattr(VALID_OPTS[key], '__call__'):
-                    errors.append(
-                        err.format(key, val, type(val).__name__, 'list')
-                    )
-            if isinstance(VALID_OPTS[key](), dict):
-                if isinstance(val, VALID_OPTS[key]):
-                    continue
-                else:
-                    errors.append(
-                        err.format(key, val, type(val).__name__, 'dict')
-                    )
-            else:
                 try:
                     VALID_OPTS[key](val)
                     if isinstance(val, (list, dict)):
@@ -1384,14 +1388,21 @@ def _validate_opts(opts):
                                 VALID_OPTS[key].__name__
                             )
                         )
-                except ValueError:
+                except (TypeError, ValueError):
                     errors.append(
-                        err.format(key, val, type(val).__name__, VALID_OPTS[key])
+                        err.format(key,
-                    )
+                                   val,
-                except TypeError:
+                                   type(val).__name__,
-                    errors.append(
+                                   VALID_OPTS[key].__name__)
-                        err.format(key, val, type(val).__name__, VALID_OPTS[key])
                     )
+                continue
+
+            errors.append(
+                err.format(key,
+                           val,
+                           type(val).__name__,
+                           format_multi_opt(VALID_OPTS[key].__name__))
+            )
 
     # RAET on Windows uses 'win32file.CreateMailslot()' for IPC. Due to this,
     # sock_dirs must start with '\\.\mailslot\' and not contain any colons.
@@ -1404,7 +1415,7 @@ def _validate_opts(opts):
                 '\\\\.\\mailslot\\' + opts['sock_dir'].replace(':', ''))
 
     for error in errors:
-        log.warning(error)
+        log.debug(error)
     if errors:
         return False
     return True

salt/modules/state.py

@@ -106,9 +106,9 @@ def _wait(jid):
 
 def running(concurrent=False):
     '''
-    Return a list of strings that contain state return data if a state function is
+    Return a list of strings that contain state return data if a state function
-    already running. This function is used to prevent multiple state calls from being
+    is already running. This function is used to prevent multiple state calls
-    run at the same time.
+    from being run at the same time.
 
     CLI Example:
 
@@ -175,7 +175,9 @@ def _get_opts(localconfig=None):
 def low(data, queue=False, **kwargs):
     '''
     Execute a single low data call
-    This function is mostly intended for testing the state system
+
+    This function is mostly intended for testing the state system and is not
+    likely to be needed in everyday usage.
 
     CLI Example:
 
@@ -205,7 +207,9 @@ def low(data, queue=False, **kwargs):
 def high(data, test=False, queue=False, **kwargs):
     '''
     Execute the compound calls stored in a single set of high data
-    This function is mostly intended for testing the state system
+
+    This function is mostly intended for testing the state system andis not
+    likely to be needed in everyday usage.
 
     CLI Example:
 
@@ -307,17 +311,127 @@ def apply_(mods=None,
     '''
     .. versionadded:: 2015.5.0
 
-    Apply states! This function will call highstate or state.sls based on the
+    This function will call :mod:`state.highstate
-    arguments passed in, state.apply is intended to be the main gateway for
+    <salt.modules.state.highstate>` or :mod:`state.sls
-    all state executions.
+    <salt.modules.state.sls>` based on the arguments passed to this function.
+    It exists as a more intuitive way of applying states.
 
-    CLI Example:
+    .. rubric:: APPLYING ALL STATES CONFIGURED IN TOP.SLS (A.K.A. :ref:`HIGHSTATE <running-highstate>`)
+
+    To apply all configured states, simply run ``state.apply``:
 
     .. code-block:: bash
 
         salt '*' state.apply
+
+    The following additional arguments are also accepted when applying all
+    states configured in top.sls:
+
+    test
+        Run states in test-only (dry-run) mode
+
+    pillar
+        Custom Pillar values, passed as a dictionary of key-value pairs
+
+        .. code-block:: bash
+
+            salt '*' state.apply test pillar='{"foo": "bar"}'
+
+        .. note::
+            Values passed this way will override Pillar values set via
+            ``pillar_roots`` or an external Pillar source.
+
+    queue : False
+        Instead of failing immediately when another state run is in progress,
+        queue the new state run to begin running once the other has finished.
+
+        This option starts a new thread for each queued state run, so use this
+        option sparingly.
+
+    localconfig
+        Optionally, instead of using the minion config, load minion opts from
+        the file specified by this argument, and then merge them with the
+        options from the minion config. This functionality allows for specific
+        states to be run with their own custom minion configuration, including
+        different pillars, file_roots, etc.
+
+        .. code-block:: bash
+
+            salt '*' state.apply localconfig=/path/to/minion.yml
+
+
+    .. rubric:: APPLYING INDIVIDUAL SLS FILES (A.K.A. :py:func:`STATE.SLS <salt.modules.state.sls>`)
+
+    To apply individual SLS files, pass them as a comma-separated list:
+
+    .. code-block:: bash
+
+        # Run the states configured in salt://test.sls (or salt://test/init.sls)
         salt '*' state.apply test
+        # Run the states configured in salt://test.sls (or salt://test/init.sls)
+        # and salt://pkgs.sls (or salt://pkgs/init.sls).
         salt '*' state.apply test,pkgs
+
+    The following additional arguments are also accepted when applying
+    individual SLS files:
+
+    test
+        Run states in test-only (dry-run) mode
+
+    pillar
+        Custom Pillar values, passed as a dictionary of key-value pairs
+
+        .. code-block:: bash
+
+            salt '*' state.apply test pillar='{"foo": "bar"}'
+
+        .. note::
+            Values passed this way will override Pillar values set via
+            ``pillar_roots`` or an external Pillar source.
+
+    queue : False
+        Instead of failing immediately when another state run is in progress,
+        queue the new state run to begin running once the other has finished.
+
+        This option starts a new thread for each queued state run, so use this
+        option sparingly.
+
+    concurrent : False
+        Execute state runs concurrently instead of serially
+
+        .. warning::
+
+            This flag is potentially dangerous. It is designed for use when
+            multiple state runs can safely be run at the same time. Do *not*
+            use this flag for performance optimization.
+
+    saltenv : None
+        Specify a salt fileserver environment to be used when applying states
+
+        .. versionchanged:: 0.17.0
+            Argument name changed from ``env`` to ``saltenv``
+
+        .. versionchanged:: 2014.7.0
+            If no saltenv is specified, the minion config will be checked for a
+            ``saltenv`` parameter and if found, it will be used. If none is
+            found, ``base`` will be used. In prior releases, the minion config
+            was not checked and ``base`` would always be assumed when the
+            saltenv was not explicitly set.
+
+    pillarenv
+        Specify a Pillar environment to be used when applying states. By
+        default, all Pillar environments will be merged together and used.
+
+    localconfig
+        Optionally, instead of using the minion config, load minion opts from
+        the file specified by this argument, and then merge them with the
+        options from the minion config. This functionality allows for specific
+        states to be run with their own custom minion configuration, including
+        different pillars, file_roots, etc.
+
+        .. code-block:: bash
+
+            salt '*' state.apply test localconfig=/path/to/minion.yml
     '''
     if mods:
         return sls(mods, **kwargs)
@@ -468,24 +582,32 @@ def highstate(test=None,
     Retrieve the state data from the salt master for this minion and execute it
 
     test
-        Notify states to execute in test-only (dry-run) mode.
+        Run states in test-only (dry-run) mode
 
-        Sets the ``test`` variable in the minion ``opts`` for the duration of
-        the state run.
     pillar
-        Custom Pillar data can be passed with the ``pillar`` kwarg. Values
+        Custom Pillar values, passed as a dictionary of key-value pairs
-        passed here will override hard-coded Pillar values.
+
-    queue : ``False``
+        .. code-block:: bash
+
+            salt '*' state.apply test pillar='{"foo": "bar"}'
+
+        .. note::
+            Values passed this way will override Pillar values set via
+            ``pillar_roots`` or an external Pillar source.
+
+    queue : False
         Instead of failing immediately when another state run is in progress,
         queue the new state run to begin running once the other has finished.
 
-        This option starts a new thread for each queued state run so use this
+        This option starts a new thread for each queued state run, so use this
         option sparingly.
-    localconfig:
+
-        Instead of using running minion opts, load ``localconfig`` and merge that
+    localconfig
-        with the running minion opts. This functionality is intended for using
+        Optionally, instead of using the minion config, load minion opts from
-        "roots" of salt directories (with their own minion config, pillars,
+        the file specified by this argument, and then merge them with the
-        file_roots) to run highstate out of.
+        options from the minion config. This functionality allows for specific
+        states to be run with their own custom minion configuration, including
+        different pillars, file_roots, etc.
 
     mock:
         The mock option allows for the state run to execute without actually
@@ -494,7 +616,7 @@ def highstate(test=None,
 
         .. versionadded:: 2015.8.4
 
-    CLI Example:
+    CLI Examples:
 
     .. code-block:: bash
 
@@ -595,43 +717,62 @@ def sls(mods,
         pillarenv=None,
         **kwargs):
     '''
-    Execute a set list of state files from an environment.
+    Execute the states in one or more SLS files
 
     test
-        Notify states to execute in test-only (dry-run) mode.
+        Run states in test-only (dry-run) mode
 
-        Sets the ``test`` variable in the minion ``opts`` for the duration of
-        the state run.
     pillar
-        Custom Pillar data can be passed with the ``pillar`` kwarg. Values
+        Custom Pillar values, passed as a dictionary of key-value pairs
-        passed here will override hard-coded Pillar values.
+
-    queue : ``False``
+        .. code-block:: bash
+
+            salt '*' state.apply test pillar='{"foo": "bar"}'
+
+        .. note::
+            Values passed this way will override Pillar values set via
+            ``pillar_roots`` or an external Pillar source.
+
+    queue : False
         Instead of failing immediately when another state run is in progress,
         queue the new state run to begin running once the other has finished.
 
-        This option starts a new thread for each queued state run so use this
+        This option starts a new thread for each queued state run, so use this
         option sparingly.
+
+    concurrent : False
+        Execute state runs concurrently instead of serially
+
+        .. warning::
+
+            This flag is potentially dangerous. It is designed for use when
+            multiple state runs can safely be run at the same time. Do *not*
+            use this flag for performance optimization.
+
     saltenv : None
-        Specify a ``file_roots`` environment.
+        Specify a salt fileserver environment to be used when applying states
 
         .. versionchanged:: 0.17.0
-            Argument name changed from ``env`` to ``saltenv``.
+            Argument name changed from ``env`` to ``saltenv``
-        .. versionchanged:: 2014.7
+
-            Defaults to None. If no saltenv is specified, the minion config will
+        .. versionchanged:: 2014.7.0
-            be checked for a saltenv and if found, it will be used. If none is found,
+            If no saltenv is specified, the minion config will be checked for a
-            base will be used.
+            ``saltenv`` parameter and if found, it will be used. If none is
-    pillarenv : None
+            found, ``base`` will be used. In prior releases, the minion config
-        Specify a ``pillar_roots`` environment. By default all pillar environments
+            was not checked and ``base`` would always be assumed when the
-        merged together will be used.
+            saltenv was not explicitly set.
-    concurrent:
+
-        WARNING: This flag is potentially dangerous. It is designed
+    pillarenv
-        for use when multiple state runs can safely be run at the same
+        Specify a Pillar environment to be used when applying states. By
-        Do not use this flag for performance optimization.
+        default, all Pillar environments will be merged together and used.
-    localconfig:
+
-        Instead of using running minion opts, load ``localconfig`` and merge that
+    localconfig
-        with the running minion opts. This functionality is intended for using
+
-        "roots" of salt directories (with their own minion config, pillars,
+        Optionally, instead of using the minion config, load minion opts from
-        file_roots) to run highstate out of.
+        the file specified by this argument, and then merge them with the
+        options from the minion config. This functionality allows for specific
+        states to be run with their own custom minion configuration, including
+        different pillars, file_roots, etc.
 
     mock:
         The mock option allows for the state run to execute without actually

salt/states/grains.py

@@ -226,27 +226,36 @@ def list_absent(name, value, delimiter=DEFAULT_TARGET_DELIM):
            'changes': {},
            'result': True,
            'comment': ''}
+    comments = []
     grain = __salt__['grains.get'](name, None)
     if grain:
         if isinstance(grain, list):
-            if value not in grain:
+            if not isinstance(value, list):
-                ret['comment'] = 'Value {1} is absent from grain {0}' \
+                value = [value]
-                                 .format(name, value)
+            for val in value:
-                return ret
+                if val not in grain:
-            if __opts__['test']:
+                    comments.append('Value {1} is absent from '
-                ret['result'] = None
+                                      'grain {0}'.format(name, val))
-                ret['comment'] = 'Value {1} in grain {0} is set to ' \
+                elif __opts__['test']:
-                                 'be deleted'.format(name, value)
+                    ret['result'] = None
-                ret['changes'] = {'deleted': value}
+                    comments.append('Value {1} in grain {0} is set '
-                return ret
+                                     'to be deleted'.format(name, val))
-            __salt__['grains.remove'](name, value)
+                    if 'deleted' not in ret['changes'].keys():
-            ret['comment'] = 'Value {1} was deleted from grain {0}'\
+                        ret['changes'] = {'deleted': []}
-                .format(name, value)
+                    ret['changes']['deleted'].append(val)
-            ret['changes'] = {'deleted': value}
+                elif val in grain:
+                    __salt__['grains.remove'](name, val)
+                    comments.append('Value {1} was deleted from '
+                                     'grain {0}'.format(name, val))
+                    if 'deleted' not in ret['changes'].keys():
+                        ret['changes'] = {'deleted': []}
+                    ret['changes']['deleted'].append(val)
+            ret['comment'] = '\n'.join(comments)
+            return ret
         else:
             ret['result'] = False
             ret['comment'] = 'Grain {0} is not a valid list'\
-                .format(name)
+                             .format(name)
     else:
         ret['comment'] = 'Grain {0} does not exist'.format(name)
     return ret

tests/integration/modules/sysmod.py

@@ -72,6 +72,7 @@ class SysModuleTest(integration.ModuleCase):
                 'nspawn.stop',
                 'nspawn.restart',
                 'lowpkg.bin_pkg_info',
+                'state.apply',
         )
 
         for fun in docs: