docs: returners, beacons, reactors, mine, Thorium cleanup

changelog/39959.fixed.md

@@ -0,0 +1 @@
+Added an explicit docs note to the :py:mod:`~salt.returners.rawfile_json` module clarifying that it only implements ``returner`` and ``event_return`` (so it cannot be wired in as a :conf_master:`master_job_cache` or :ref:`external-job-cache` backend), with a pointer to the upstream tracking bug. Closes the docs portion of :issue:`39959`.

changelog/47675.fixed.md

@@ -0,0 +1 @@
+Documented why calling ``mine.update`` inside :py:func:`module.run <salt.states.module.run>` silently fails to refresh the mine on the master, and listed the correct alternatives (out-of-band ``mine.update``, ``mine.send`` for a single function, or a shorter :ref:`mine_interval`) in a new "Updating the Mine From a State" section of ``doc/topics/mine/index.rst``. Closes :issue:`47675`.

changelog/58130.fixed.md

@@ -0,0 +1 @@
+Clarified the :py:func:`hashutil.github_signature <salt.modules.hashutil.github_signature>` docstring to spell out that ``challenge_hmac`` is a single positional ``<hash>=<hex>`` string (matching the ``X-Hub-Signature`` / ``X-Hub-Signature-256`` header GitHub sends) and that it must be quoted on the CLI to avoid Salt parsing ``sha1=...`` as a keyword argument. Closes the docs portion of :issue:`58130`.

changelog/61332.fixed.md

@@ -0,0 +1 @@
+Documented the ``pyroute2`` dependency on the :py:mod:`~salt.beacons.network_settings` beacon. The module docstring (and therefore the rendered ``salt.beacons.network_settings`` reference page) now lists the dependency, with onedir vs system-Python install guidance and an explicit note that the beacon refuses to load without it. Closes :issue:`61332`.

changelog/61616.fixed.md

@@ -0,0 +1 @@
+Fixed the reactor documentation in ``doc/topics/reactor/index.rst``, which incorrectly claimed that beacon-fired events arrive at the reactor wrapped under ``data['data']``. The master's ``_minion_event`` handler unwraps each beacon event before firing it on the bus, so reactors see the beacon payload directly at ``data['id']``. The docs now distinguish that path from events produced by ``event.send`` / ``event.fire_master`` (which do show up under ``data['data']``) and ship worked snippets for both. New tests in ``tests/pytests/unit/beacons/test_documented_configs.py`` pin both data dict shapes. Closes :issue:`61616`.

changelog/61921.fixed.md

@@ -0,0 +1 @@
+Added three worked Thorium examples (load-average spike reaction, nginx-flap detection, and runner-triggering on a custom event tag) to ``doc/topics/thorium/index.rst``. Each example exercises only Thorium module functions that ship in ``salt/thorium/`` and is pinned by a new unit test in ``tests/pytests/unit/thorium/test_documented_examples.py`` that parses the SLS and verifies every referenced ``<module>.<function>`` exists. Closes :issue:`61921`.

changelog/62017.fixed.md

@@ -0,0 +1 @@
+Documented the four returner contexts (``--return``, :conf_master:`master_job_cache`, :conf_master:`ext_job_cache`, :conf_master:`event_return`) in ``doc/ref/returners/index.rst`` with a per-context table of which side runs the returner, which config file the keys live in, and which returner functions are required for each context. Closes :issue:`62017` and :issue:`63367`.

changelog/63693.fixed.md

@@ -0,0 +1 @@
+Replaced the broken inotify install instructions in ``doc/topics/beacons/index.rst`` and the :py:mod:`~salt.beacons.inotify` module docstring. The legacy ``salt myminion pkg.install python-inotify`` command fails on every current platform because the PyPI distribution is named ``pyinotify`` (no ``python-`` prefix) and distro packages now ship ``python3-pyinotify``. The docs now show the correct ``pip.install pyinotify`` invocation for onedir packaged installs (default in 3006+) and the correct distro-package or pip path for system-Python installs. Closes :issue:`63693` and :issue:`65019`.

doc/ref/returners/index.rst

@@ -44,6 +44,119 @@ It is also possible to specify multiple returners:
 In this scenario all three returners will be called and the data from the
 test.version command will be sent out to the three named returners.
 
+.. _returner-contexts:
+
+Returner Contexts and Configuration Keys
+========================================
+
+Salt invokes returners in four distinct contexts. Each context targets a
+different function in the returner module and reads configuration from a
+different place. Knowing which context you want is the difference between
+returner data appearing where you expect it and silent drops.
+
+``--return`` / ``--return_config`` / ``--return_kwargs`` (per-job, minion-side)
+    Set on the ``salt`` CLI. The master tells each targeted minion to load
+    the named returner *on the minion* and call its ``returner(ret)``
+    function with the job's return dict.
+
+    * ``--return <name>`` selects the returner.
+    * ``--return_config <profile>`` selects a configuration profile prefix.
+      A returner that supports profiles reads ``profile.foo`` keys
+      instead of plain ``foo`` keys when this is set (for example,
+      ``alternative.mysql.host`` vs ``mysql.host``).
+    * ``--return_kwargs '{"key": "value"}'`` passes per-call keyword
+      arguments that the returner's ``returner()`` function may consume
+      (look for ``ret.get("ret_kwargs")`` or similar in the returner
+      source). Not all returners honor it.
+
+    Because the returner runs on the minion, its **configuration must be
+    on the minion**.
+
+:conf_master:`master_job_cache` (post-job, master-side)
+    A single returner the master invokes to record every completed job's
+    load and return. The master calls the returner's ``prep_jid``,
+    ``save_load``, ``get_load``, and ``returner`` functions. The returner
+    runs *on the master*, so its configuration must be in the master
+    config. Only returners that implement ``prep_jid`` / ``save_load`` /
+    ``get_load`` are eligible. See :ref:`external-job-cache` for the
+    eligibility list (the same set of functions is required).
+
+:conf_master:`ext_job_cache` (post-job, minion-side)
+    The same idea as ``master_job_cache``, but the returner is loaded and
+    run on the minion. Use this when minions can reach the storage
+    backend directly and you would rather not funnel everything through
+    the master. The returner must implement the same set of cache
+    functions, and its configuration must be on the **minion**. See
+    :ref:`external-job-cache`.
+
+:conf_master:`event_return` (event bus, master-side)
+    A list of returners the master invokes for every event it sees on
+    the event bus, calling each returner's ``event_return(events)``
+    function. Returners without an ``event_return`` are skipped silently.
+    Configuration must be on the **master**.
+
+Where to put which key (quick reference):
+
++----------------------------+----------+-----------------------+
+| Context                    | Side     | Config file           |
++============================+==========+=======================+
+| ``--return``               | minion   | ``/etc/salt/minion``  |
++----------------------------+----------+-----------------------+
+| ``master_job_cache``       | master   | ``/etc/salt/master``  |
++----------------------------+----------+-----------------------+
+| ``ext_job_cache``          | minion   | ``/etc/salt/minion``  |
++----------------------------+----------+-----------------------+
+| ``event_return``           | master   | ``/etc/salt/master``  |
++----------------------------+----------+-----------------------+
+
+To check whether a given returner supports a given context, look for the
+following function names in its source:
+
++----------------------+--------------------------------------------------+
+| Function             | Required for                                     |
++======================+==================================================+
+| ``returner``         | ``--return`` and (implicitly) any cache context  |
++----------------------+--------------------------------------------------+
+| ``prep_jid``,        | ``master_job_cache`` and ``ext_job_cache``       |
+| ``save_load``,       |                                                  |
+| ``get_load``         |                                                  |
++----------------------+--------------------------------------------------+
+| ``get_jid``,         | ``ext_job_cache``                                |
+| ``get_fun``,         |                                                  |
+| ``get_jids``,        |                                                  |
+| ``get_minions``      |                                                  |
++----------------------+--------------------------------------------------+
+| ``event_return``     | ``event_return``                                 |
++----------------------+--------------------------------------------------+
+
+See :issue:`62017` and :issue:`63367` for the discussion that motivated
+this section.
+
+Returner Configuration Profiles
+-------------------------------
+
+Many returners accept an "alternative" configuration profile so the same
+minion can target two backends. The convention is:
+
+.. code-block:: yaml
+
+    # default keys
+    mysql.host: db.example.com
+
+    # profile named "audit"
+    audit.mysql.host: audit-db.example.com
+
+To use the ``audit`` profile from the CLI:
+
+.. code-block:: bash
+
+    salt '*' test.version --return mysql --return_config audit
+
+Returners implement profile lookup via
+:py:func:`salt.returners.get_returner_options`, which falls back to the
+default key when a profile-prefixed key is absent. See the
+:py:mod:`mysql <salt.returners.mysql>` returner for an example.
+
 Writing a Returner
 ==================
 

doc/topics/beacons/index.rst

@@ -152,8 +152,34 @@ beacon to monitor a file for changes, and then restores the file to its
 original contents if a change was made.
 
 .. note::
-    The inotify beacon requires Pyinotify on the minion, install it using
-    ``salt myminion pkg.install python-inotify``.
+    The inotify beacon requires `pyinotify
+    <https://pypi.org/project/pyinotify/>`_ on the minion. The
+    correct install method depends on how Salt was installed:
+
+    * **onedir packages** (``salt-pkg-install``, ``rpm``, ``deb`` from
+      the official 3006+ packages): pyinotify must live inside Salt's
+      bundled Python environment. Use :py:func:`pip.install
+      <salt.modules.pip.install>`, which targets the onedir's pip:
+
+      .. code-block:: bash
+
+          salt myminion pip.install pyinotify
+
+    * **System python install** (``pip install salt`` in a venv, or
+      legacy system-python packages): install ``pyinotify`` into the
+      same interpreter the minion runs under. If your distribution
+      packages it (Debian/Ubuntu ship ``python3-pyinotify``), use:
+
+      .. code-block:: bash
+
+          salt myminion pkg.install python3-pyinotify
+
+      Otherwise use ``pip.install pyinotify``.
+
+    The legacy instruction ``pkg.install python-inotify`` is wrong on
+    every current platform; the PyPI distribution is named ``pyinotify``
+    (no ``python-`` prefix) and distro packages now ship the python3
+    variant. See :issue:`63693` and :issue:`65019`.
 
 Create Watched File
 -------------------

doc/topics/mine/index.rst

@@ -148,6 +148,61 @@ config:
 
     mine_interval: 60
 
+.. _mine_updating_in_states:
+
+Updating the Mine From a State
+==============================
+
+Two execution-module functions are available to refresh mine data on a
+running minion:
+
+* :py:func:`mine.update <salt.modules.mine.update>` re-runs every entry in
+  ``mine_functions`` and pushes the result up to the master.
+* :py:func:`mine.send <salt.modules.mine.send>` re-runs a single named
+  function and pushes only that one.
+
+Both work cleanly from the command line:
+
+.. code-block:: bash
+
+    salt-call mine.update
+    salt-call mine.send network.ip_addrs eth0
+
+.. warning::
+
+    Calling ``mine.update`` from inside a state via
+    :py:func:`module.run <salt.states.module.run>` is a footgun. With the
+    classic ``module.run`` signature, ``mine.update`` will appear to
+    succeed in the state output but the mine on the master will not be
+    updated (see :issue:`47675`). The state runtime executes the function
+    in a context where the mine push is silently dropped.
+
+    Use one of these instead:
+
+    1. **Run the mine refresh out of band**, with
+       :py:func:`mine.update <salt.modules.mine.update>` from a scheduler
+       entry, a reactor, an orchestration runner, or a direct
+       ``salt '*' mine.update`` from the master.
+
+    2. **Use** :py:func:`mine.send <salt.modules.mine.send>` for a single
+       function instead of refreshing every entry:
+
+       .. code-block:: yaml
+
+           refresh_ip_mine:
+             module.run:
+               - name: mine.send
+               - m_name: network.ip_addrs
+               - interface: eth0
+
+    3. **Shorten the** :ref:`mine_interval` and let the scheduler refresh
+       the mine on its own.
+
+    Salt's :ref:`mine_interval` always refreshes the mine correctly, so
+    when timing is not critical (most use cases), option 3 is the
+    simplest. For event-driven refreshes, prefer option 1 with a reactor
+    invoking ``salt '*' mine.update`` from the master.
+
 Mine in Salt-SSH
 ================
 

doc/topics/reactor/index.rst

@@ -422,18 +422,46 @@ For example:
 Beacons and Reactors
 ====================
 
-An event initiated by a beacon, when it arrives at the master will be wrapped
-inside a second event, such that the data object containing the beacon
-information will be ``data['data']``, rather than ``data``.
+The shape of the ``data`` template variable inside a reactor SLS depends on
+how the originating event was produced. Two paths exist, and they are not
+the same:
+
+Beacon events
+    A beacon returns a list of dicts from its ``beacon()`` function. The
+    minion sends those dicts to the master with the key ``events``, and the
+    master unwraps each event and fires its inner ``data`` payload on the
+    event bus (see :py:meth:`~salt.daemons.masterapi.LocalFuncs._minion_event`
+    and :py:meth:`~salt.minion.MinionBase._fire_master`). The reactor then
+    receives that payload as ``data`` directly. To access fields, reference
+    them on ``data`` itself:
+
+    .. code-block:: yaml
+
+        revert-file:
+          local.state.apply:
+            - tgt: {{ data['id'] }}
+            - arg:
+              - maintain_important_file
+
+    The minion id is at ``data['id']`` (the beacons subsystem injects it
+    automatically). Any extra fields the beacon set in its returned dict
+    are also at the top level of ``data``.
+
+Events from ``event.send`` / ``event.fire_master``
+    These functions send a single load with ``tag``, ``data``, ``cmd``,
+    and ``id`` keys. The master fires that whole load on the event bus, so
+    the user payload ends up nested under ``data``:
 
-For example, to access the ``id`` field of the beacon event in a reactor file,
-you will need to reference ``{{ data['data']['id'] }}`` rather than ``{{
-data['id'] }}`` as for events initiated directly on the event bus.
+    .. code-block:: bash
+
+        salt '*' event.send foo '{key: value}'
 
-Similarly, the data dictionary attached to the event would be located in
-``{{ data['data']['data'] }}`` instead of ``{{ data['data'] }}``.
+    In a reactor watching tag ``foo``, ``data['data']['key']`` equals
+    ``value`` and ``data['id']`` is the originating minion's id.
 
-See the :ref:`beacon documentation <beacon-example>` for examples.
+In short: for beacons, use ``{{ data['key'] }}``; for ``event.send``, use
+``{{ data['data']['key'] }}``. The :ref:`beacon documentation
+<beacon-example>` includes a worked beacon + reactor + state example.
 
 Manually Firing an Event
 ========================