Wazuh is a powerful, open-source security platform that unifies XDR and SIEM capabilities. While robust, like any complex system, users may encounter issues that require systematic troubleshooting. This article outlines common problems and provides actionable steps to diagnose and resolve them, drawing insights from official documentation and community experiences.
1. The Importance of Log Files: Your First Stop
The most crucial tool in your Wazuh troubleshooting arsenal is the `ossec.log` file, typically located at `/var/ossec/logs/ossec.log`. This file provides detailed insights into the operations of the Wazuh manager, agents, and other components. When an issue arises, always check this log first for error messages, warnings, or anomalies that can point to the root cause.
2. Common Troubleshooting Scenarios
Upgrade Issues
Upgrading Wazuh components (manager, agents, or Elasticsearch/OpenSearch dashboards) can sometimes introduce problems.
Symptom: Services failing to start after an upgrade, agents not connecting, or data processing errors.
Troubleshooting Steps:
1. Consult the Upgrade Guide: Always refer to the official Wazuh upgrade guide for your specific version. These guides contain critical pre-requisites, step-by-step instructions, and often a dedicated troubleshooting section for common upgrade-related issues.
2. Check `ossec.log`: Look for error messages immediately after the upgrade, especially those related to database schema, component startup, or configuration parsing.
3. Version Compatibility: Ensure all components (manager, agents, Filebeat, Elasticsearch/OpenSearch, Wazuh Dashboard) are compatible with each other, as outlined in the Wazuh documentation.
4. Backup and Rollback: If possible, always perform a backup before major upgrades to allow for a quick rollback if issues are unresolvable.
Agent Connectivity and Data Flow Problems
Agents are the eyes and ears of your Wazuh deployment. If agents aren’t reporting or data isn’t flowing, your visibility is compromised.
Symptom: Agents showing as “Never Connected” or “Disconnected” in the Wazuh Dashboard, no security events or logs from specific agents.
Troubleshooting Steps:
1. Agent Status: On the agent machine, check if the Wazuh agent service is running. (e.g., `systemctl status wazuh-agent` on Linux).
2. Manager IP/Hostname: Verify that the `manager_ip` or `manager_hostname` configured in the agent’s `ossec.conf` file points to the correct Wazuh manager.
3. Firewall Rules: Ensure no firewalls (on the agent, manager, or in between) are blocking communication on ports 1514 (agent-manager registration/key exchange) and 55000 (agent-manager data forwarding).
4. Network Connectivity: Test basic network connectivity from the agent to the manager (e.g., `ping manager_ip`).
5. Agent Key Issues: If an agent was reinstalled or moved, ensure its authentication key is correct on both the agent and the manager. You might need to re-register the agent.
6. Check Manager Logs: On the Wazuh manager, check `ossec.log` for messages indicating connection attempts from agents or issues processing incoming data.
By following these structured troubleshooting steps and diligently utilizing the information provided in the `ossec.log` file and official documentation, you can efficiently diagnose and resolve most Wazuh-related issues, ensuring the continued security and integrity of your monitored environment.
