Wazuh agents

Wazuh 4.x manager

1. Download the wazuh-migrate-identity.py tool:

   # curl -fsSLO https://raw.githubusercontent.com/wazuh/wazuh/5.0.0/tools/migration/wazuh-migrate-identity.py
   # chmod +x wazuh-migrate-identity.py
   

2. Stop the Wazuh 4.x manager. The tool doesn't export the data while the Wazuh manager is running:

   # systemctl stop wazuh-manager
   

3. Preview the export. Add --with-password to migrate the enrollment password, and --with-rbac to migrate the Wazuh manager API users, roles, and policies:

   # ./wazuh-migrate-identity.py export --with-password --with-rbac --dry-run /root/wazuh-4x-bundle
   

   The command output looks similar to this:

     agents   3
     groups   2 (dbservers, webservers)
   
   DRY RUN: nothing was written.
   WARNING: group 'webservers' holds files other than agent.conf (blocked-ips). They are recorded but not migrated: 5.0 compiles whatever is in a group folder and pushes it to its agents, and a 4.x list or rootcheck file has no meaning there.
   

   Review any warning about files in a group folder other than agent.conf. The tool doesn't migrate them. Recreate the files you need on the Wazuh 5.x manager.

   Warning

   The --with-rbac option replaces the Wazuh 5.x manager API users, roles, and policies with the Wazuh 4.x ones, including the passwords of the wazuh and wazuh-internal-client users. Use it only to keep custom Wazuh manager API users, roles, or policies. If you use it, reset both passwords to the values in /etc/wazuh-manager/export/credentials.env after the import, as described in the Wazuh 5.x manager steps. Otherwise, the Wazuh dashboard can't connect to the Wazuh manager API.

4. Export the Wazuh agent registrations:

   # ./wazuh-migrate-identity.py export --with-password --with-rbac /root/wazuh-4x-bundle
   

5. Start the Wazuh 4.x manager:

   # systemctl start wazuh-manager
   

6. Copy the /root/wazuh-4x-bundle/ directory to the same path on the Wazuh 5.x manager using a secure method, such as scp. The bundle contains agent keys and password hashes, and only root can read it. Run the copy as root or with sudo.

Wazuh 5.x manager

Perform the following steps with the Wazuh 5.x manager running.

1. Download the wazuh-migrate-identity.py tool:

   # curl -fsSLO https://raw.githubusercontent.com/wazuh/wazuh/5.0.0/tools/migration/wazuh-migrate-identity.py
   # chmod +x wazuh-migrate-identity.py
   

2. Preview the import. Use the same options as for the export:

   # ./wazuh-migrate-identity.py import --with-password --with-rbac --dry-run /root/wazuh-4x-bundle
   

3. Import the agent registrations:

   # ./wazuh-migrate-identity.py import --with-password --with-rbac /root/wazuh-4x-bundle
   

4. If you used --with-rbac, restart the Wazuh manager to apply the migrated Wazuh manager API users. After the restart, the wazuh and wazuh-internal-client users have their Wazuh 4.x passwords. The wazuh-internal-client user is the Wazuh 4.x wazuh-wui user, renamed. Set both users back to the passwords in /etc/wazuh-manager/export/credentials.env. Otherwise, the Wazuh dashboard can't connect to the Wazuh manager API:

   # systemctl restart wazuh-manager
   # C=/etc/wazuh-manager/export/credentials.env
   # API=$(grep '^WAZUH_MANAGER_API_PASSWORD=' $C | cut -d= -f2-)
   # WUI=$(grep '^WAZUH_MANAGER_WUI_PASSWORD=' $C | cut -d= -f2-)
   # printf '{"wazuh": "%s", "wazuh-internal-client": "%s"}' "$API" "$WUI" | /var/wazuh-manager/bin/rbac_control change-password --passwords-file -
   

5. Verify the migration. The output shows The target matches the bundle. when every agent and group is present:

   # ./wazuh-migrate-identity.py check /root/wazuh-4x-bundle
   

   The command output looks similar to this:

     api      password taken from /etc/wazuh-manager/export/credentials.env (WAZUH_MANAGER_API_PASSWORD)
   agents    3 of 3 present
   groups    2 of 2 present
   rbac.db   schema version 1
   
   The target matches the bundle.
   

   The Wazuh agents appear as never_connected until they reconnect to the Wazuh 5.x manager. Continue with Reconnect the Wazuh agents. After you validate the migration, delete the /root/wazuh-4x-bundle/ directory from both Wazuh managers.

Wazuh 4.x manager

1. Stop the Wazuh 4.x manager so that the agent database doesn't change while you copy it:

   # systemctl stop wazuh-manager
   

2. Back up the agent keys, the agent registry, and the custom agent groups. The archive excludes the default group, because the Wazuh 5.x manager provides its own:

   # mkdir -p /root/wazuh-4x-backup
   # cp /var/ossec/etc/client.keys /var/ossec/queue/db/global.db /root/wazuh-4x-backup/
   # cd /var/ossec/etc && tar -czf /root/wazuh-4x-backup/groups.tar.gz --exclude='shared/default' --exclude='*/merged.mg' shared/*/
   

   If you customized shared/default/agent.conf, merge its settings into the Wazuh 5.x default group manually.

   If the Wazuh 4.x manager requires an enrollment password, also back up the password file. Wazuh 4.x agents that enroll again, for example after you rebuild an endpoint, use this password:

   # cp /var/ossec/etc/authd.pass /root/wazuh-4x-backup/
   

3. Start the Wazuh 4.x manager:

   # systemctl start wazuh-manager
   

4. Copy the /root/wazuh-4x-backup/ directory to the same path on the Wazuh 5.x manager using a secure method, such as scp. The backup files are readable only by root. Run the copy as root or with sudo.

Wazuh 5.x manager

1. Stop the Wazuh 5.x manager:

   # systemctl stop wazuh-manager
   

2. Restore the agent keys with the ownership and permissions that Wazuh 5.x requires:

   # install -m 660 -o wazuh-manager -g wazuh-manager /root/wazuh-4x-backup/client.keys /etc/wazuh-manager/client.keys
   

3. Copy the agent registrations and group memberships from the Wazuh 4.x database into the Wazuh 5.x database. Wazuh 5.x uses a different database schema, so you can't replace the database file:

   Note

   The command requires the sqlite3 tool. If it isn't installed, install it: dnf install -y sqlite on RPM-based systems, or apt-get install -y sqlite3 on Debian-based systems.

   # sqlite3 /var/wazuh-manager/queue/db/global.db <<'SQL'
   ATTACH '/root/wazuh-4x-backup/global.db' AS old;
   INSERT OR REPLACE INTO agent
     (id, name, ip, register_ip, internal_key, os_name, os_version, os_major, os_minor, os_type, os_platform, os_arch,
      version, date_add, last_keepalive, `group`, group_hash, group_sync_status, sync_status, connection_status,
      disconnection_time, status_code)
   SELECT id, name, ip, register_ip, internal_key, os_name, os_version, os_major, os_minor,
          CASE WHEN lower(os_platform) = 'windows' THEN 'windows'
               WHEN lower(os_platform) = 'darwin' THEN 'macos'
               WHEN os_platform IS NULL THEN NULL ELSE 'linux' END,
          os_platform, os_arch, version, date_add, last_keepalive, `group`, group_hash, group_sync_status, sync_status,
          'disconnected', 0, status_code
   FROM old.agent WHERE id > 0;
   INSERT OR IGNORE INTO `group` (name) SELECT name FROM old.`group`;
   INSERT OR REPLACE INTO belongs (id_agent, id_group, priority)
   SELECT b.id_agent, g5.id, b.priority
   FROM old.belongs b JOIN old.`group` g4 ON g4.id = b.id_group JOIN `group` g5 ON g5.name = g4.name
   WHERE b.id_agent > 0;
   SQL
   # chown wazuh-manager:wazuh-manager /var/wazuh-manager/queue/db/global.db
   

4. Restore the custom agent groups:

   # tar -xzf /root/wazuh-4x-backup/groups.tar.gz -C /etc/wazuh-manager/
   # chown -R wazuh-manager:wazuh-manager /etc/wazuh-manager/shared/
   

   Review the restored agent.conf files and update or remove any settings that Wazuh 5.x doesn't support.

   If you backed up the enrollment password, restore it. Otherwise, the Wazuh 5.x manager generates a new password, and Wazuh 4.x agents that enroll again with the old one fail:

   # install -m 640 -o wazuh-manager -g wazuh-manager /root/wazuh-4x-backup/authd.pass /etc/wazuh-manager/authd.pass
   

5. Start the Wazuh 5.x manager:

   # systemctl start wazuh-manager
   

6. Verify that the agents keep their Wazuh 4.x IDs, groups, and registration dates:

   # TOKEN=$(curl -sk -u wazuh:<PASSWORD> -X POST "https://localhost:55000/security/user/authenticate?raw=true")
   # curl -sk "https://localhost:55000/agents?select=id,name,group,dateAdd" -H "Authorization: Bearer $TOKEN"
   

   Replace <PASSWORD> with the WAZUH_MANAGER_API_PASSWORD value from /etc/wazuh-manager/export/credentials.env.

   To print only the value, run grep '^WAZUH_MANAGER_API_PASSWORD=' /etc/wazuh-manager/export/credentials.env | cut -d= -f2- on the Wazuh 5.x manager.

   The agents appear as disconnected until they reconnect to the Wazuh 5.x manager.

   After you reconnect the agents and validate the migration, delete the /root/wazuh-4x-backup/ directory from both Wazuh managers. It contains the agent keys.