Wazuh agent upgrades

The Wazuh server can manage agent configuration and upgrades remotely, so most of a large agent fleet can be moved to a new version without logging in to each endpoint. The Wazuh documentation describes two remote routes for this work: upgrades delivered as WPK packages and triggered through the Wazuh API, and the agent_upgrade mechanism. Your team should treat the remote route as the default for agents that accept it and reserve local upgrades for hosts that cannot be reached. Before you plan either route, confirm the exact commands, package names, parameters and supported version combinations in the documentation for your target release. Do not copy request bodies or command lines from older runbooks, because the package naming and parameters can change between releases.

Start with a connectivity check. A remote upgrade only reaches agents that are online, can talk to the Wazuh server and are reporting their status. Pull the agent list from the API or the dashboard and group agents by status, then investigate every disconnected or never-connected host before scheduling a wave. Hosts that have been offline for a long period often need a local visit, so record them separately. Also confirm that the agents in each wave run the version the upgrade path expects. An agent that is far behind may need an intermediate step that the documentation lists for that release.

Next, check agent group membership. Agent groups are the practical unit for scoping a remote run, because they let you target a set of endpoints that share a role, operating system or change window. Verify that each group contains only the agents you intend to upgrade, that the group's shared configuration is the one you expect, and that no host is in two groups with conflicting settings. Write down which group goes first, which goes last, and which hosts are excluded, such as critical production systems that need a separate approval. Keep the group list in your change record so the rollback owner knows exactly what was touched.

If you run the Wazuh server as a cluster, check cluster health before starting any remote run. Confirm that every cluster node is up, that the nodes agree on the state of the cluster, and that no node is in the middle of its own maintenance. Agents connect to the cluster, and a degraded node can leave some agents without a path back to the manager during the upgrade, which makes their status harder to read. Check the server's logs and the cluster status output from the documentation for your release, and confirm that the central components are at the version your agent upgrade expects. Plan the remote run for a window in which the cluster is stable, not during its own upgrade.

Finally, decide how you will judge each wave before moving to the next one. After each batch, compare the reported agent versions with the target, check that agents have reconnected, and review the server logs for upgrade errors. Keep a short list of failure signals to act on, such as agents that stay disconnected, agents that report the old version after the run, or agents that report errors in the upgrade log. Confirm with your vendor documentation which upgrade states and error messages appear for your release, rather than assuming them. Stop the wave when the failure rate or the unknown state count exceeds the threshold your change owner has agreed.

Local upgrades are the fallback when the Wazuh server cannot deliver the upgrade to an agent. The usual triggers are hosts that cannot reach the server for remote delivery, air-gapped or offline segments where the Wazuh offline installation guidance applies, and endpoints where the remote route fails after the agent has been upgraded centrally. Before any host is moved to a local route, record the reason for it. That record decides which hosts can wait for a later remote window and which need a local visit or console session, and it keeps the exception list short enough to review.

Local upgrades differ by operating system. Linux, Windows, macOS, Solaris, AIX and HP-UX each have their own package formats, install commands, service handling and privilege requirements. The steps, package names and privilege model must come from the Wazuh documentation for that platform and the exact target agent version. Do not reuse a procedure from an older release, from another operating system or from a community guide. Confirm the page for each platform before scheduling work, and note any difference in how the agent configuration is preserved or how the service is restarted, because those differences determine what the engineer must check on each host.

Group the hosts by operating system, current agent version and access path before any work starts. Within each group, pilot one host, confirm that the agent reconnects to the server, that the server reports the new version, and that the agent still collects the logs and inventory your rules depend on. Test the documented rollback on that pilot as well, especially on Solaris, AIX and HP-UX hosts where fewer engineers have hands-on experience. Only then move the rest of the group. A pilot per platform and version is the cheapest way to find a package or privilege problem before it repeats across many hosts.

Cost in a local route is driven by the number of hosts, not by the central upgrade. Each host needs an engineer or an approved process to touch it, a change window, and access that may mean a physical visit, a console session or a transfer of packages through an approved media path into an offline network. Costs rise with the number of distinct operating systems and target versions, with the number of hosts that need a pilot or rollback test, and with access constraints. Costs also recur, because each later agent release repeats the work on the same hosts. When requesting a quote, ask for the host count by operating system, the access method for each group, the number of target versions, the change windows and the per-host verification evidence.

Keep a per-host record after each local upgrade. The record should show the operating system, the agent version before and after, the package used and its checksum, the date, the engineer who made the change and the server check that confirmed the agent reconnected. This record is the evidence a reviewer will ask for when the fleet is audited, and it is also the starting point for the next round, because it shows which hosts are still on an old version and why.

Plan for four failure modes before the first wave starts: agents that fail to download or apply the package, agents that upgrade but stop reporting, hosts that go offline mid-rollout, and fleets left on mixed versions for weeks. The first two are the most dangerous because they can look like success. An upgrade task may show as finished while the agent is still on the old binary, or the agent may show the new version while its events stop reaching the Wazuh server. Your change plan should name the signal that proves each agent is healthy, not only the signal that the task ran.

Track every agent in the agent inventory with three values: the version it reports, the time it was last seen, and the upgrade outcome recorded for the wave. That gives you three states to work from: upgraded and reporting, upgraded but silent, and not yet upgraded. Export a snapshot before each wave and after it closes so changes can be traced later. Confirm which fields your Wazuh version exposes through the API and the dashboard before you rely on them. Stale inventory also matters for vulnerability detection, which correlates the software inventory agents report, so an agent that never reports its new state can leave findings based on out-of-date data.

Each failure needs one of three responses. Retry when the cause is transient, such as an interrupted download, a host that was offline, or a package lock held by another process. Fix the host when the cause is local, such as low disk space, a missing dependency, a permission or policy block from endhost security tooling, or clock drift. Roll back only when an upgraded agent stops reporting after the host is confirmed healthy, and only if the previous package is still available and has been tested for that operating system. Record the decision, the reason and the retry count against each host, and cap retries in the plan so a broken package does not keep cycling through the fleet.

Set acceptable failure rates in your own change plan, separately for each wave and each operating system family, and state the action you will take when a wave exceeds them, usually pausing the wave and investigating. Do not copy thresholds from this page or from another organization's plan. The right numbers depend on fleet size, how critical the monitored hosts are, the length of your change window and how many people can work the failures at once. Ask your partner or the Wazuh documentation to confirm which agent and server version combinations are supported during the transition, because that answer shapes how long a wave can safely pause.

A mixed-version fleet needs a documented end date and a named owner. Without both, stragglers accumulate: hosts that were excluded for a reason, machines that are offline for long periods, and systems nobody claims. Each mixed-version gap also makes troubleshooting harder, because a rule or feature may behave differently on an old agent than on a new one. Record every exception with its reason, the affected hosts and a review date. The owner should report the count of agents below target at each review, decide which stragglers are fixed, retired or excepted, and close the programme only when the inventory shows the agreed target version across the fleet.