This Wazuh tutorial takes you from an empty virtual machine to a Wazuh deployment you would be willing to put in front of a customer. Forty lessons across three levels plus four reference pages, each one written against the Wazuh 5.0 documentation and each one carrying a “tested on” line so you know exactly what it was checked against. Start at Basics if you have never installed it, Intermediate if agents are already reporting and you now need your own detection content, Expert if you are running it for other people.

Wazuh is a free and open source security platform that combines XDR and SIEM capability in one stack. A single agent on each endpoint collects logs, file integrity changes, process and package inventory, configuration assessment results and vulnerability data, then ships all of it to a central manager. The manager normalises every record into one schema and forwards it to a search and analytics tier, where detection rules run on a schedule and the results appear in a web interface. The components are licensed under GPLv2 and AGPLv3, so nothing about the detection engine, the agent count or the data volume sits behind a paid tier. That licence is the reason Wazuh shows up in so many first SOC builds, and it is also the reason so many of those builds stall: the software is free, the operating work is not.

The 5.0 architecture has four parts. The Wazuh agent runs on the endpoint. The Wazuh manager runs the normalisation engine that decodes and enriches events. The Wazuh indexer, built on OpenSearch, stores events, findings and endpoint state and now also runs detection. The Wazuh dashboard queries the indexer and administers the manager. The default ports are 1517/TCP for 5.0 agents (HTTPS), 9200/TCP for the indexer API, 55000/TCP for the manager API and 443/TCP for the dashboard, with 1514 and 1515 kept open for Wazuh 4.x agents and 1516 for manager cluster traffic. Detection happens on the indexer: scheduled detectors evaluate Sigma-format YAML rules against normalised events and emit findings, which is what 5.0 calls the records 4.x called alerts. If any of those words are new, the glossary defines them in two sentences each.

Why this guide targets Wazuh 5, and what that means if you are on 4.x

Wazuh 5.0 is the largest rewrite the project has shipped. Filebeat is gone, replaced by an indexer connector compiled into the manager. The installation directory moved from /var/ossec to /var/wazuh-manager on the server side. Rules are no longer XML with numeric levels; they are Sigma YAML with string severities, and there is no converter, so custom content is re-authored by hand. Email alerting, the syslog output and the integration daemon were removed from the manager and their jobs handed to OpenSearch Alerting and Notifications on the indexer. Active Response was inverted: an alerting action writes a request to an index and the manager polls it. Writing a tutorial against 4.x today would mean teaching an operating model that is being retired.

Being honest about release status matters more than being first. As of September 2026 Wazuh 5.0 is in beta. The most recent build is beta5, published on 1 September 2026. There is no release candidate and the project has not announced a general availability date. The installation commands in these lessons therefore point at the pre-release repository and carry the beta flags; those flags drop at GA and the lessons will be updated when they do. Wazuh 4.x continues to be maintained in parallel, and if you are running it in production today you should keep running it.

What this tutorial does for someone still on 4.x is speak both versions. Every lesson that touches something 5.0 changed carries a short “still on Wazuh 4.x?” note giving the 4.x equivalent, so the page is useful whether you are planning a migration or operating the older release. Two pages exist specifically for that audience: what actually changes in Wazuh 5, which is the change inventory organised by what it means for an operator, and the 4.x to 5 migration runbook, which covers the awkward truth that there is no in-place upgrade. You deploy 5.0 alongside 4.x, recreate groups, import client.keys through the API, repoint agents and cut over per group. The ports and paths reference puts the two versions side by side in one table, which is the page most people keep open during a migration.

What each level gets you

Basics is for someone who has heard the name and wants a working deployment. Thirteen pages take you from what Wazuh is through sizing, installing on Ubuntu, enrolling agents and reading the dashboard, and they end with the page you will actually need at two in the morning, why an agent is disconnected. At the end of Basics you have agents reporting, findings arriving, file integrity monitoring and vulnerability detection running, and you can explain what each component does. This is the Wazuh for beginners path and it is deliberately linear.

Intermediate is for the person who now owns the deployment. It is about making Wazuh see your environment rather than a generic one: writing a YAML decoder for an application nobody has written one for, authoring Sigma rules and promoting them through the draft, test and custom spaces, getting logs in from awkward sources, and routing what matters to somewhere a human will see it. At the end of Intermediate you can onboard a new log source end to end: collect it, decode it, detect on it, notify on it.

Expert is for people running Wazuh as a service or at scale: clustering, performance, multi-tenancy for MSSPs, SSO and RBAC, cutting false positives without going blind, SOAR, compliance evidence, detection engineering, hardening the platform itself and what it really costs to run. These pages assume you can already do everything in the first two levels, and they spend their words on judgement rather than syntax.

Four reference pages sit outside the sequence because you will come back to them rather than read them once: the commands cheat sheet, the ports, paths and log files reference with 4.x and 5.0 side by side, the error message index that collects every exact error string used across the lessons, and the glossary.

How to use this tutorial

Work in order within a level. The lessons assume the previous one, and the ordering is deliberate: enrolment before groups, groups before centralised configuration, decoders before rules. Across levels you can skip, but if you jump into Intermediate without a working lab you will spend your time debugging an install instead of learning the detection model.

Build a lab and keep it. A single virtual machine with 4 vCPU, 8 GiB of RAM and 50 GB of disk is enough for the whole of Basics and most of Intermediate, and it matches the quickstart sizing the project publishes for up to 25 agents. Add two small endpoints, one Linux and one Windows, so that every lesson has somewhere to run. Take a snapshot after the install lesson; you will want to roll back to it more than once.

Where a lesson uses a configuration file, a rule, a decoder, a script or a compose file, the real file is published with the lesson rather than only quoted in the page, so you can download rather than copy-paste from a browser. Each lesson lists its files at the end of the page with a zip for that lesson, and the whole set is one download at wazuh-tutorial-files.zip.

Every lesson carries a tested on line in its header, naming the Wazuh version and the operating system it was written against. Where that line is accompanied by lab pass pending, the page was written from the official 5.0-beta documentation but has not yet been executed end to end in the lab. That distinction is published rather than hidden. A page moves to verified when someone has run every command on it and the output matched. Nothing in these pages is invented terminal output: commands are shown and the successful result is described in prose, or quoted from the documentation.

One habit worth forming early. Wazuh gives you a great deal of signal on day one and almost none of it is tuned for your environment. Resist the urge to switch everything on. Scope file integrity monitoring to the directories that matter, leave Active Response off until you have a reason and a rollback plan, and treat every enabled rule as something you have agreed to triage.

Where the production notes come from

Fourteen years in offensive security, and since a partnership with the Wazuh project in 2024, a multi-tenant Wazuh SOC that I run in production for external customers. The production asides scattered through these lessons come from that: the failure modes that only show up at the third tenant, the tuning decisions that looked wrong on paper and right in practice, the things that broke during an upgrade. They are written generically, and no customer or environment is identifiable from them.

What this tutorial will not do

It is not a replacement for the official Wazuh documentation. The documentation is the authority on every option, every configuration key and every API parameter, and these lessons link to the exact page rather than restating it. What the documentation does not give you is order of operations, the failure modes, the reasons to not do something, and the difference between a setting that works in a lab and a setting that survives a year in production. That gap is what this Wazuh guide is for.

It will not tell you Wazuh 5.0 is generally available, because it is not. It will not recommend Active Response as a default. It will not give you prices, rates or sizing figures the project has not published. And it will not pretend Wazuh is the right answer for everyone: the comparison lesson has a section on when to pick something else, and the cost lesson has a section on when running your own is the expensive option.

Frequently asked questions

Is Wazuh free?

Yes. The Wazuh agent, manager, indexer and dashboard are released under GPLv2 and AGPLv3, with no licence cost, no agent-count limit and no data-volume charge. What costs money is the infrastructure it runs on and the time of the people who tune and operate it. The build versus buy lesson breaks those drivers down without quoting figures.

Is Wazuh a SIEM or an XDR?

Both, which is why the project describes itself as unified XDR and SIEM. It behaves as a SIEM in that it centralises and correlates logs from anywhere, and as an XDR in that its own agent produces endpoint telemetry, inventory and response actions rather than only consuming third-party feeds. What Wazuh is walks through the components and, just as usefully, what Wazuh is not.

How long does it take to learn Wazuh?

A working all-in-one install with agents reporting is an afternoon. Being able to onboard an unfamiliar log source, write a decoder for it and detect on it is a few weekends of deliberate practice. Running it for other people, with tenancy, tuning and on-call, is measured in months. The Basics level is the fastest route to the first of those three.

Can Wazuh replace an EDR?

It covers a lot of the same ground: process and file telemetry, inventory, configuration assessment, malware detection through integrity monitoring plus scanning, and scripted response on the endpoint. It does not ship the kernel-level behavioural prevention, memory protection or managed threat hunting that commercial EDR products lead with. Treat it as detection and visibility that can act, not as prevention, and read the Active Response lesson before you rely on it to stop anything.

What is different in Wazuh 5 compared with 4.x?

Filebeat is removed, the server paths and configuration file are renamed, agents talk HTTPS on port 1517, detection moves to the indexer with Sigma YAML rules producing findings instead of alerts, and the manager loses email, syslog output and the integration daemon in favour of OpenSearch Alerting and Notifications. There is no in-place upgrade and no rule converter. Wazuh 5: what changes and why it matters is the full inventory.

What are the minimum hardware requirements for Wazuh?

The project gives the Wazuh manager a minimum of 8 GB of RAM and 4 CPU cores, and recommends 16 GB and 8 cores; the indexer has the same figures per node. For a lab or a small estate of up to 25 agents on a single all-in-one host, the published quickstart sizing is 4 vCPU, 8 GiB of RAM and 50 GB of disk. Disk is the figure that surprises people in 5.0, because raw events are indexed as well as findings. Sizing shows the arithmetic.

Does Wazuh work on Windows?

Yes. The Wazuh agent ships as an MSI installer for Windows, supports silent installation with deployment properties, and collects Windows event channels, registry integrity, inventory and Sysmon telemetry. The central components are Linux only: Ubuntu 24.04 or 26.04, Red Hat Enterprise Linux 9 or 10, or Amazon Linux 2023. Installing the agent on Windows covers the interactive, silent, GPO and Intune routes.

Can Wazuh be used for an MSSP or multi-tenant SOC?

It can, and a lot of managed SOC offerings are built on it, but tenancy is something you design rather than switch on. The building blocks are agent groups stamped onto every document (labels did the same job on 4.x, and the 5.0 beta has not documented them yet), indexer security roles that filter by that field, per-tenant dashboard users and per-tenant notification routing. Multi-tenant Wazuh for MSSPs covers the pattern and, more importantly, the isolation failure modes.