Merge pull request #351 from atomicturtle/docs/issue-138

Clarify active response disable options (#138)

Author: atomicturtle

docs/manual/ar/ar-unix.rst

@@ -55,7 +55,7 @@ figurations>`_.
     </active-response>
 
 
-- **disabled**: Disables the active response capabilities if set to yes. If this is set, active response will not work.
+- **disabled**: When set to ``yes``, skips this active-response binding only. See :ref:`ossec_config.active-response` and :ref:`manual-ar`.
 - **command**: Used to link the response to the command
 - **location**: Where the command should be executed. You have four options:
 

docs/manual/ar/index.rst

@@ -1,3 +1,4 @@
+.. _manual-ar:
 
 ###############
 Active Response
@@ -8,6 +9,19 @@ These triggers can be specific alerts, alert levels, or rule groups.
 
 The active response framework is also what allows an OSSEC administrator to start a syscheck scan or restart OSSEC on a remote agent.
 
+Disabling active response
+-------------------------
+
+Different configuration elements disable active response at different scopes:
+
+``<active-response>`` with ``<disabled>yes</disabled>``
+    Skips **one** command binding; other bindings still run.
+
+``<client>`` with ``<disable-active-response>yes</disable-active-response>``
+    Stops **all** active-response execution on that agent.
+
+See :ref:`ossec_config.active-response` and :ref:`ossec_config.client` for syntax.
+
 Bundled active-response scripts are documented in :ref:`manual-ar-scripts`.
 
 .. toctree::

docs/syntax/ossec_config.active-response.trst

@@ -39,10 +39,15 @@ Active-response Options
 
 - disabled 
 
-    Disables active response if set to yes. If this is not defined active response is enabled on unix systems, and disabled on Windows systems.
-    This option is available on server, local, and agent installations.
-    Setting it to ``yes`` on an agent will disable active-response for that agent only,
-    while setting it on the server will disable all active-response.
+    When set to ``yes``, **this** ``<active-response>`` binding is skipped and its
+    command is not registered. Other active-response blocks without ``disabled`` are
+    unaffected. If ``disabled`` is omitted, active response is enabled on Unix
+    systems and disabled on Windows by default.
+
+    This option is available on server, local, and agent installations. To disable
+    all active-response execution on a single agent, use
+    ``<disable-active-response>`` in the agent ``<client>`` section instead (see
+    :ref:`ossec_config.client`).
 
 - command 
 

docs/syntax/ossec_config.client.trst

@@ -50,3 +50,19 @@
 
     **Allowed:** aes, blowfish
 
+- disable-active-response
+
+    When set to ``yes``, disables **all** active-response execution on this agent.
+    The agent will not run any active-response scripts locally, regardless of
+    individual ``<active-response>`` blocks.
+
+    **Default:** no
+
+    **Allowed:** yes, no
+
+    .. note::
+
+       This is an agent-only option inside ``<client>``. To disable a single
+       active-response binding, use ``<disabled>yes</disabled>`` inside that
+       ``<active-response>`` block instead (see :ref:`ossec_config.active-response`).
+