From a457330151a3794bb3accaa7b1f59c02f78cdfa1 Mon Sep 17 00:00:00 2001
From: "Scott R. Shinn" <scott@atomicorp.com>
Date: Sun, 28 Jun 2026 13:26:34 -0400
Subject: [PATCH] Expand manager backup and migration guide (#154)

Add step-by-step backup, restore, and verification procedures and
link from the installation section. Also addresses backup guidance
in #80.

Closes #154

Assisted-By: Auto
---
 docs/manual/installation/index.rst   |  3 +-
 docs/manual/notes/manager_backup.rst | 93 ++++++++++++++++++++++------
 2 files changed, 76 insertions(+), 20 deletions(-)

diff --git a/docs/manual/installation/index.rst b/docs/manual/installation/index.rst
index 11ffe26e..1ce4571a 100644
--- a/docs/manual/installation/index.rst
+++ b/docs/manual/installation/index.rst
@@ -22,5 +22,4 @@ The best installation tutorial is available in the `OSSEC book <http://www.amazo
     upgrade-migration
     systemd-deployment
 
-
-
+See also :ref:`manager_backup` for backing up or migrating a manager to new hardware.
diff --git a/docs/manual/notes/manager_backup.rst b/docs/manual/notes/manager_backup.rst
index a48c59d7..8ef88ebe 100644
--- a/docs/manual/notes/manager_backup.rst
+++ b/docs/manual/notes/manager_backup.rst
@@ -1,36 +1,93 @@
-Migrating/backing up the manager
---------------------------------
+.. _manager_backup:
 
-If you need to migrate the manager to another system (or just want to backup the current setup), these are the files you need:
+Manager backup and migration
+============================
 
-These are the two locations where the keys are saved for all the agents.
+Use this guide to back up an OSSEC manager or migrate it to new hardware.
+For **version upgrades** (for example 3.8 to 4.x), see :ref:`upgrade-migration`
+instead — crypto and agent compatibility differ from a like-for-like host move.
+
+When to use this guide
+----------------------
+
+* **Backup** — periodic snapshot before major changes
+* **Hardware migration** — move the manager to a new server at the **same OSSEC version**
+* **Disaster recovery** — restore from backup after failure
+
+Pre-migration checklist
+-----------------------
+
+1. Record the installed OSSEC version: ``/var/ossec/bin/ossec-control info``
+2. Note the agent count: ``/var/ossec/bin/agent_control -l``
+3. Stop OSSEC cleanly: ``/var/ossec/bin/ossec-control stop``
+4. Ensure no package upgrade is pending on the destination unless you also follow
+   :ref:`upgrade-migration`
+
+Files to copy
+-------------
+
+Agent keys and registration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: console
 
-  /var/ossec/etc/client.keys
-  /var/ossec/queue/rids/ 
+   /var/ossec/etc/client.keys
+   /var/ossec/queue/rids/
 
-These are the configuration files you may want to keep 
+Configuration and rules
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: console
 
-  /var/ossec/etc/*.conf
-  /var/ossec/rules
-  /var/ossec/etc/*.xml
-  /var/ossec/etc/shared/agent.conf
+   /var/ossec/etc/ossec.conf
+   /var/ossec/etc/internal_options.conf
+   /var/ossec/etc/local_internal_options.conf
+   /var/ossec/etc/shared/
+   /var/ossec/rules/
+   /var/ossec/etc/decoders/
+   /var/ossec/etc/lists/
 
+Agent state databases (optional but recommended)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-These are the databases where we store data for the agents.
+Preserves FIM baselines, rootcheck state, and similar per-agent data:
 
 .. code-block:: console
 
-  /var/ossec/queue/syscheck
-  /var/ossec/queue/rootcheck
-  /var/ossec/queue/fts
-  /var/ossec/queue/agentless
+   /var/ossec/queue/syscheck/
+   /var/ossec/queue/rootcheck/
+   /var/ossec/queue/fts/
+   /var/ossec/queue/agentless/
+   /var/ossec/queue/agents/
 
-Logs stored if they are needed.
+Logs (optional)
+^^^^^^^^^^^^^^^
 
 .. code-block:: console
 
-  /var/ossec/logs
+   /var/ossec/logs/
+
+Restore procedure
+-----------------
+
+1. Install the **same OSSEC version** on the destination host (see :ref:`install`).
+2. Stop OSSEC on the destination: ``/var/ossec/bin/ossec-control stop``
+3. Copy backed-up files into ``/var/ossec/``, preserving ownership (``ossec:ossec``
+   or your platform's equivalent).
+4. If the manager IP or hostname changed, update agent ``<server-ip>`` or
+   ``<server-hostname>`` on each agent, or use DNS that resolves to the new host.
+5. Start OSSEC: ``/var/ossec/bin/ossec-control start``
+6. Verify agents reconnect: ``/var/ossec/bin/agent_control -l`` — agents should
+   show as **Active** within a few minutes.
+
+.. note::
+
+   You do not need to re-enroll agents if ``client.keys`` and ``queue/rids/`` were
+   copied intact and the manager identity is unchanged.
+
+Verification
+------------
+
+* ``/var/ossec/bin/ossec-control status`` — all required daemons running
+* ``/var/ossec/bin/agent_control -l`` — expected agents active
+* Review ``/var/ossec/logs/ossec.log`` for authentication or rule errors