# wazuh-4-to-5-migration

Companion files for the lesson **Migrating Wazuh 4.x to 5: The Runbook**.

Lesson: https://maheshtata.com/wazuh/wazuh-4-to-5-migration/

Tested against: Wazuh 5.0 (beta5 documentation, September 2026), Ubuntu 24.04.
Wazuh 5.0 had not reached general availability when these files were written.
Re-verify against the GA migration guide before using them on a production estate.

## Files

| File | What it is |
|---|---|
| `migration-checklist.md` | The runbook as a tick-list, phase 0 to phase 8, with the verification step for each phase. Print it or paste it into a change ticket. |
| `import-client-keys.sh` | Imports 4.x agent registrations into a 5.x manager through `POST /agents/insert`, preserving agent ID, name, IP and key. Wraps the documented import loop with batching, token refresh, a dry-run mode and a per-entry result log. |

## Using the import script

```bash
chmod +x import-client-keys.sh

# Parse only, no API calls. Confirms the file is readable and counts the entries.
./import-client-keys.sh --keys ./client.keys --manager 10.0.0.10 --dry-run

# Real import. The password is read from the environment or prompted for,
# never passed on the command line.
export WAZUH_API_PASSWORD='...'
./import-client-keys.sh --keys ./client.keys --manager 10.0.0.10 --user wazuh --batch 200
```

Results are written to `import-client-keys.log`, one line per entry:

- `OK` for an accepted import
- `SKIP` for a removed entry (prefixed with `!` in `client.keys`) or a malformed line
- `FAIL` with the API response recorded verbatim

An agent ID that already exists on the 5.x manager fails the import for that entry.
Delete the existing registration on the 5.x manager, then rerun; the script is safe
to rerun because the entries that already imported will report the same collision
rather than duplicating anything.

### Before you run it

- Restore the agent groups on the 5.x manager **first**. An agent that enrols declaring
  a group the manager does not have is rejected outright.
- `client.keys` contains agent authentication keys. Keep it readable only by
  administrators and delete it from the 5.x manager once the import is verified.
- The script uses `curl -k`, matching the documented examples. On a deployment with a
  private CA, replace `-k` with `--cacert /path/to/root-ca.pem` in the two `curl` calls.

## Sources

Everything here follows the official migration documentation. Nothing is inferred.

- https://documentation.wazuh.com/5.0-beta/migration-to-5x/index.html
- https://documentation.wazuh.com/5.0-beta/migration-to-5x/wazuh-indexer.html
- https://documentation.wazuh.com/5.0-beta/migration-to-5x/wazuh-manager.html
- https://documentation.wazuh.com/5.0-beta/migration-to-5x/wazuh-dashboard.html
- https://documentation.wazuh.com/5.0-beta/migration-to-5x/wazuh-agents.html
- https://github.com/wazuh/wazuh/tree/main/docs/guide/migration