Merge pull request #30215 from jacobhammons/doc-issues

Assorted doc bug fixes

conf/minion

@@ -565,7 +565,7 @@
 #log_granular_levels: {}
 
 # To diagnose issues with minions disconnecting or missing returns, ZeroMQ
-# supports the use of monitor sockets # to log connection events. This
+# supports the use of monitor sockets to log connection events. This
 # feature requires ZeroMQ 4.0 or higher.
 #
 # To enable ZeroMQ monitor sockets, set 'zmq_monitor' to 'True' and log at a
@@ -577,7 +577,7 @@
 # 'value': 27, 'description': 'EVENT_DISCONNECTED'}
 #
 # All events logged will include the string 'ZeroMQ event'. A connection event
-# should be logged on the as the minion starts up and initially connects to the
+# should be logged as the minion starts up and initially connects to the
 # master. If not, check for debug log level and that the necessary version of
 # ZeroMQ is installed.
 #

doc/index.rst

@@ -74,6 +74,17 @@ projects to quickly set up a Salt demo environment:
 - https://github.com/UtahDave/salt-vagrant-demo
 - https://github.com/UtahDave/salt-vagrant-lxc
 
+Example Formulas
+================
+
+A Github repo that contains a number of community-maintained formulas is
+available at https://github.com/saltstack-formulas. Contributions are welcome!
+
+A Github repo that contains formulas to install a number of Windows
+applications is available at https://github.com/saltstack/salt-winrepo-ng. Note
+that Salt makes this repo :ref:`available <windows-package-manager>` to your
+Windows minions, and contributions are welcome!
+
 Salt in depth
 =============
 

doc/ref/configuration/master.rst

@@ -2667,7 +2667,6 @@ Default: ``{}``
 This can be used to control logging levels more specifically. See also
 :conf_log:`log_granular_levels`.
 
-
 Node Groups
 ===========
 

doc/ref/configuration/minion.rst

@@ -1186,6 +1186,31 @@ Default: ``{}``
 This can be used to control logging levels more specifically. See also
 :conf_log:`log_granular_levels`.
 
+.. conf_minion:: zmq_monitor
+
+``zmq_monitor``
+---------------
+
+Default: ``False``
+
+To diagnose issues with minions disconnecting or missing returns, ZeroMQ
+supports the use of monitor sockets to log connection events. This
+feature requires ZeroMQ 4.0 or higher.
+
+To enable ZeroMQ monitor sockets, set 'zmq_monitor' to 'True' and log at a
+debug level or higher.
+
+A sample log event is as follows:
+
+.. code-block:: yaml
+
+    [DEBUG   ] ZeroMQ event: {'endpoint': 'tcp://127.0.0.1:4505', 'event': 512,
+    'value': 27, 'description': 'EVENT_DISCONNECTED'}
+
+All events logged will include the string ``ZeroMQ event``. A connection event
+should be logged as the minion starts up and initially connects to the
+master. If not, check for debug log level and that the necessary version of
+ZeroMQ is installed.
 
 .. conf_minion:: failhard
 

doc/ref/peer.rst

@@ -67,6 +67,9 @@ allow minions ending with foo.org access to the publisher.
         - ps.*
         - pkg.*
 
+.. note::
+    Minions are matched using regular expressions when configuring ``peer``.
+
 Peer Runner Communication
 =========================
 
@@ -93,6 +96,9 @@ to the manage and jobs runner functions.
         - manage.*
         - jobs.*
 
+.. note::
+    Minions are matched using regular expressions when configuring ``peer_run``.
+
 Using Peer Communication
 ========================
 
@@ -117,4 +123,4 @@ To match minions using other matchers, use ``expr_form``:
 
 .. code-block:: bash
 
-    # salt-call publish.publish 'webserv* and not G@os:Ubuntu' test.ping expr_form='compound'
+    # salt-call publish.publish 'webserv* and not G@os:Ubuntu' test.ping expr_form='compound'

doc/ref/states/requisites.rst

@@ -455,6 +455,12 @@ under certain conditions. The use of unless or onlyif options help make states
 even more stateful. The check_cmds option helps ensure that the result of a
 state is evaluated correctly.
 
+Reload
+------
+
+``reload_modules`` is a boolean option that forces salt to reload its modules
+after a state finishes. See :ref:`Reloading Modules <reloading-modules>`.
+
 Unless
 ------
 

doc/topics/cloud/salt.rst

@@ -312,3 +312,9 @@ the master or a minion), create a client object and issue a command against it:
     client = salt.cloud.CloudClient('/etc/salt/cloud')
     nodes = client.query()
     pprint.pprint(nodes)
+
+Reactor
+-------
+Examples of using the reactor with Salt Cloud are available in the
+:formula_url:`ec2-autoscale-reactor <ec2-autoscale-reactor>` and
+:formula_url:`salt-cloud-reactor <salt-cloud-reactor>` formulas.

doc/topics/eauth/access_control.rst

@@ -54,4 +54,9 @@ other minions based on standard targets.
 
 The above allows for all minions to be hit by test.ping by dave, and adds a
 few functions that dave can execute on other minions. It also allows steve
-unrestricted access to salt commands.
+unrestricted access to salt commands.
+
+.. note::
+    Minions are matched using regular expressions when configuring
+    ``client_acl`` and ``external_auth``.
+

doc/topics/troubleshooting/master.rst

@@ -184,15 +184,13 @@ 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
 do not return output.
 
-.. note::
-    A number of timing issues were resolved in the 2014.1 release of Salt.
-    Upgrading to at least this version is strongly recommended if timeouts
-    persist.
-
 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``
 configuration file.
 
+Having keys accepted for Salt minions that no longer exist or are not reachable
+also increases the possibility of timeouts, since the Salt master waits for
+those systems to return command results.
 
 Passing the -c Option to Salt Returns a Permissions Error
 =========================================================

salt/modules/cron.py

@@ -1,6 +1,11 @@
 # -*- coding: utf-8 -*-
 '''
 Work with cron
+
+.. note::
+    Salt does not escape cron metacharacters automatically. You should
+    backslash-escape percent characters and any other metacharacters that might
+    be interpreted incorrectly by the shell.
 '''
 from __future__ import absolute_import
 

salt/modules/state.py

@@ -768,15 +768,17 @@ def top(topfn,
         saltenv=None,
         **kwargs):
     '''
-    Execute a specific top file instead of the default
+    Execute a specific top file instead of the default. This is useful to apply
+    configurations from a different environment (for example, dev or prod), without
+    modifying the default top file.
 
     CLI Example:
 
     .. code-block:: bash
 
         salt '*' state.top reverse_top.sls
-        salt '*' state.top reverse_top.sls exclude=sls_to_exclude
-        salt '*' state.top reverse_top.sls exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"
+        salt '*' state.top prod_top.sls exclude=sls_to_exclude
+        salt '*' state.top dev_top.sls exclude="[{'id': 'id_to_exclude'}, {'sls': 'sls_to_exclude'}]"
     '''
     conflict = _check_queue(queue, kwargs)
     if conflict is not None:

salt/modules/tomcat.py

@@ -5,10 +5,13 @@ Support for Tomcat
 This module uses the manager webapp to manage Apache tomcat webapps.
 If the manager webapp is not configured some of the functions won't work.
 
-.. note::
-
-    The config format was changed in 2014.7.0, but backwards compatibility for
-    the old-style config will be in the 2014.7.1 release.
+:configuration:
+    - Java bin path should be in default path
+    - If ipv6 is enabled make sure you permit manager access to ipv6 interface
+      "0:0:0:0:0:0:0:1"
+    - If you are using tomcat.tar.gz it has to be installed or symlinked under
+      ``/opt``, preferrably using name tomcat
+    - "tomcat.signal start/stop" works but it does not use the startup scripts
 
 The following grains/pillar should be set: