Merge pull request #27693 from jacobhammons/doc-updates

initial engines topic, updates to windows repo docs

conf/master

@@ -657,7 +657,7 @@
 #
 #
 #####         Mine settings     #####
-##########################################
+#####################################
 # Restrict mine.get access from minions. By default any minion has a full access
 # to get all mine data from master cache. In acl definion below, only pcre matches
 # are allowed.
@@ -737,7 +737,7 @@
 #log_granular_levels: {}
 
 
-#####         Node Groups           #####
+#####         Node Groups           ######
 ##########################################
 # Node groups allow for logical groupings of minion nodes. A group consists of a group
 # name and a compound target.
@@ -755,17 +755,30 @@
 
 
 #####  Windows Software Repo settings #####
-##############################################
+###########################################
 # Location of the repo on the master:
-#win_repo: '/srv/salt/win/repo'
-#
-# Location of the master's repo cache file:
-#win_repo_mastercachefile: '/srv/salt/win/repo/winrepo.p'
+#winrepo_dir_ng: '/srv/salt/win/repo-ng'
 #
 # List of git repositories to include with the local repo:
-#win_gitrepos:
+#winrepo_remotes_ng:
+#  - 'https://github.com/saltstack/salt-winrepo-ng.git'
+
+
+#####  Windows Software Repo settings - Pre 2015.8 #####
+########################################################
+# Legacy repo settings for pre-2015.8 Windows minions.
+#
+# Location of the repo on the master:
+#winrepo_dir: '/srv/salt/win/repo'
+#
+# Location of the master's repo cache file:
+#winrepo_mastercachefile: '/srv/salt/win/repo/winrepo.p'
+#
+# List of git repositories to include with the local repo:
+#winrepo_remotes:
 #  - 'https://github.com/saltstack/salt-winrepo.git'
 
+
 #####      Returner settings          ######
 ############################################
 # Which returner(s) will be used for minion's result:

doc/contents.rst

@@ -21,6 +21,7 @@ Salt Table of Contents
     topics/sdb/index
     topics/event/index
     topics/beacons/index
+    topics/engines/index
     topics/ext_processes/index
     topics/highavailability/index
     topics/topology/index

doc/ref/configuration/master.rst

@@ -2750,17 +2750,35 @@ used.
 ---------------
 
 .. versionchanged:: 2015.8.0
-    Renamed from ``win_repo`` to ``winrepo_dir``
+    Renamed from ``win_repo`` to ``winrepo_dir``.
 
 Default: ``/srv/salt/win/repo``
 
-Location on the master where the :conf_master:`winrepo_remotes` are checked
-out.
+Location on the master where the :conf_master:`winrepo_remotes` are checked out
+for pre-2015.8.0 minions. 2015.8.0 and later minions use
+:conf_master:`winrepo_remotes_ng <winrepo_remotes_ng>` instead.
 
 .. code-block:: yaml
 
     winrepo_dir: /srv/salt/win/repo
 
+.. conf_master:: winrepo_dir_ng
+
+``winrepo_dir_ng``
+---------------
+
+.. versionadded:: 2015.8.0
+    A new :ref:`ng <windows-package-manager>` repo was added.
+
+Default: ``/srv/salt/win/repo-ng``
+
+Location on the master where the :conf_master:`winrepo_remotes_ng` are checked
+out for 2015.8.0 and later minions.
+
+.. code-block:: yaml
+
+    winrepo_dir: /srv/salt/win/repo-ng
+
 .. conf_master:: winrepo_cachefile
 .. conf_master:: win_repo_mastercachefile
 
@@ -2770,6 +2788,10 @@ out.
 .. versionchanged:: 2015.8.0
     Renamed from ``win_repo_mastercachefile`` to ``winrepo_cachefile``
 
+.. note::
+    2015.8.0 and later minions do not use this setting since the cachefile
+    is now located on the minion.
+
 Default: ``winrepo.p``
 
 Path relative to :conf_master:`winrepo_dir` where the winrepo cache should be
@@ -2786,11 +2808,13 @@ created.
 -------------------
 
 .. versionchanged:: 2015.8.0
-    Renamed from ``win_gitrepos`` to ``winrepo_remotes``
+    Renamed from ``win_gitrepos`` to ``winrepo_remotes``.
 
 Default: ``['https://github.com/saltstack/salt-winrepo.git']``
 
-List of git repositories to checkout and include in the winrepo
+List of git repositories to checkout and include in the winrepo for
+pre-2015.8.0 minions. 2015.8.0 and later minions use
+:conf_master:`winrepo_remotes_ng <winrepo_remotes_ng>` instead.
 
 .. code-block:: yaml
 
@@ -2798,7 +2822,7 @@ List of git repositories to checkout and include in the winrepo
       - https://github.com/saltstack/salt-winrepo.git
 
 To specify a specific revision of the repository, prepend a commit ID to the
-URL of the the repository:
+URL of the repository:
 
 .. code-block:: yaml
 
@@ -2809,6 +2833,36 @@ Replace ``<commit_id>`` with the SHA1 hash of a commit ID. Specifying a commit
 ID is useful in that it allows one to revert back to a previous version in the
 event that an error is introduced in the latest revision of the repo.
 
+.. conf_master:: winrepo_remotes_ng
+
+``winrepo_remotes_ng``
+-------------------
+
+.. versionadded:: 2015.8.0
+    A new :ref:`ng <windows-package-manager>` repo was added.
+
+Default: ``['https://github.com/saltstack/salt-winrepo-ng.git']``
+
+List of git repositories to checkout and include in the winrepo for
+2015.8.0 and later minions.
+
+.. code-block:: yaml
+
+    winrepo_remotes_ng:
+      - https://github.com/saltstack/salt-winrepo-ng.git
+
+To specify a specific revision of the repository, prepend a commit ID to the
+URL of the repository:
+
+.. code-block:: yaml
+
+    winrepo_remotes:
+      - '<commit_id> https://github.com/saltstack/salt-winrepo-ng.git'
+
+Replace ``<commit_id>`` with the SHA1 hash of a commit ID. Specifying a commit
+ID is useful in that it allows one to revert back to a previous version in the
+event that an error is introduced in the latest revision of the repo.
+
 .. conf_master:: winrepo_branch
 
 ``winrepo_branch``

doc/ref/modules/all/index.rst

@@ -65,7 +65,6 @@ Full list of builtin execution modules
     cpan
     cron
     cyg
-    cytest
     daemontools
     darwin_pkgutil
     darwin_sysctl

doc/ref/modules/all/salt.modules.cytest.rst

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

doc/topics/engines/index.rst

@@ -0,0 +1,34 @@
+.. _engines:
+
+============
+Salt Engines
+============
+
+.. versionadded:: 2015.8.0
+
+Salt Engines are long-running, external system processes that leverage Salt.
+
+- Engines have access to Salt configuration, execution modules, and runners (``__opts__``, ``__salt__``, and ``__runners__``).
+- Engines are executed in a separate process that is monitored by Salt. If a Salt engine stops, it is restarted automatically.
+- Engines can run on the Salt master and on Salt minions.
+
+Salt engines enhance and replace the :ref:`external processes <ext-processes>` functionality.
+
+Configuration
+=============
+
+Salt engines are configured under an ``engines`` top-level section in your Salt master or Salt minion configuration. Provide a list of engines and parameters under this section.
+
+.. code-block:: yaml
+
+   engines:
+     - logstash:
+         host: log.my_network.com
+         port: 5959
+
+Salt engines must be in the Salt path, or you can add the ``engines_dir`` option in your Salt master configuration with a list of directories under which Salt attempts to find Salt engines.
+
+Writing an Engine
+=================
+
+An example Salt engine, :blob:`salt/engines/test.py`, is available in the Salt source. To develop an engine, the only requirement is that your module implement the ``start()`` function.

doc/topics/ext_processes/index.rst

@@ -1,18 +1,24 @@
-.. _ext_processes:
+.. _ext-processes:
 
 ===============================
 Running Custom Master Processes
 ===============================
 
-In addition to the processes that the Salt Master automatically spawns,
+.. note::
+  :ref:`Salt engines <engines>` are a new feature in 2015.8.0 that let you run
+  custom processes on the Salt master and on Salt minions. Salt engines provide
+  more functionality than ``ext_processes`` by accepting arguments, and by
+  providing access to Salt config, execution modules, and runners.
+
+In addition to the processes that the Salt master automatically spawns,
 it is possible to configure it to start additional custom processes.
 
 This is useful if a dedicated process is needed that should run throughout
-the life of the Salt Master. For periodic independent tasks, a
+the life of the Salt master. For periodic independent tasks, a
 :doc:`scheduled runner <../jobs/schedule.rst>` may be more appropriate.
 
 Processes started in this way will be restarted if they die and will be
-killed when the Salt Master is shut down.
+killed when the Salt master is shut down.
 
 
 Example Configuration

doc/topics/releases/2015.8.0.rst

@@ -71,6 +71,12 @@ Proxy Minion Enhancements
 
 Proxy Minions have undergone a significant overhaul in 2015.8, see :ref:`Proxy Minion Enhancements <proxy-2015.8.0>`.
 
+Engines
+=======
+
+Salt engines are long-running, external processes that leverage Salt. See :ref:`Salt Engines <engines>`.
+
+
 Core Changes
 ============