Document FIM maintenance mode for patch windows.

docs/faq/syscheck.rst

@@ -154,11 +154,40 @@ and create a rule to alert when an appropriate log is created.
 How do I stop syscheck alerts during system updates?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There is no easy way to do this, but there are work-arounds.
-Stop the OSSEC processes on the manager, and run ``/var/ossec/bin/syscheck_control -u AGENT_ID``.
-This will clear the syscheck database for the agent,
-and the next time syscheck runs it will create a new baseline.
-Next, start the OSSEC processes on the manager.
-Once the system update is complete, run a syscheck scan on that agent.
-The database will be populated with new values, and should not trigger "file modified" alarms.
+Use **FIM maintenance mode** on the manager so syscheck updates the integrity
+database for that agent without generating alerts. The manager and other agents
+keep running.
+
+**Canonical workflow** (preferred)::
+
+    # /var/ossec/bin/agent_control -M enable -u AGENT_ID
+    # … apply OS patches / package updates …
+    # /var/ossec/bin/agent_control -M end -u AGENT_ID
+
+``-M end`` marks the agent for pending end, restarts syscheck/rootcheck, and
+**clears maintenance automatically** when the agent reports
+``syscheck-db-completed``. That avoids disabling mid-scan or forgetting a scan
+and getting a flood afterward.
+
+While maintenance is enabled:
+
+* File modifications and new files update the syscheck DB as the new baseline
+  and do **not** alert.
+* Silent accepts are appended to ``logs/fim_maintenance.log`` on the manager.
+* ``agent_control -l`` shows ``Maint`` (or ``Maint(pending-end)``) for agents
+  in this mode.
+* Leaving maintenance on for more than 24 hours produces a periodic manager
+  WARN — keep windows short. Maintenance trusts FIM events (including malicious
+  ones) for that agent.
+
+**Emergency:** ``agent_control -M disable -u AGENT_ID`` clears the flag
+immediately without waiting for a scan. Prefer ``end`` for routine patching.
+
+Check detail with ``agent_control -M status -u AGENT_ID`` or
+``agent_control -i AGENT_ID``.
+
+The older workaround (stop the manager and run ``syscheck_control -u``) is no
+longer necessary for patch windows. Clearing the database with
+``syscheck_control -u`` remains available if you intentionally want a full
+rebuild.
 

docs/programs/agent_control.rst

@@ -6,6 +6,8 @@ agent_control
 
 The agent_control tool allows you to query and get information from any agent you have configured 
 on your server and it also allows you to restart (run now) the syscheck/rootcheck scan on any agent.
+It can also enable **FIM maintenance mode** so integrity updates during OS patching are absorbed
+quietly into the syscheck database (see :option:`agent_control -M`).
 
 Enabling `active response <../manual/ar/index.html>`_ will be necessary to start scans remotely and possibly other functions.
 
@@ -54,6 +56,29 @@ agent_control argument options
     <agent_id> that will perform the requested action. 
 
 
+.. option:: -M <action>
+
+    Per-agent FIM maintenance mode. ``<action>`` is one of ``enable``,
+    ``disable``, ``status``, or ``end``. Must be used with
+    :option:`agent_control -u`.
+
+    While enabled, the manager updates that agent's syscheck integrity database
+    from incoming scans **without** generating file-modified or file-added
+    alerts. Silent accepts are logged to ``logs/fim_maintenance.log``.
+    ``agent_control -l`` marks agents with ``Maint`` or ``Maint(pending-end)``.
+
+    **Preferred patch workflow**::
+
+        # /var/ossec/bin/agent_control -M enable -u 002
+        # … apply OS patches …
+        # /var/ossec/bin/agent_control -M end -u 002
+
+    ``end`` restarts syscheck and clears maintenance when the baseline scan
+    completes. Use ``disable`` only for an immediate emergency clear (it does
+    not wait for a scan). Keep maintenance windows short; the manager warns if
+    an agent stays in maintenance longer than 24 hours.
+
+
 agent_control example usage
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~