How to Upgrade a Wazuh Agent

The Wazuh agent is a lightweight endpoint component that collects and forwards security telemetry—such as log data, file integrity changes, inventory information, and vulnerability signals—to the central Wazuh manager for analysis and correlation.

It is a core part of the Wazuh XDR/SIEM architecture, acting as the primary data collection layer across servers, cloud workloads, and endpoints.

Keeping the agent updated is not optional in production environments.

Updates typically include security patches, improved log parsers, performance optimizations, and compatibility fixes for newer operating systems and manager versions.

Outdated agents are a common root cause of broken data pipelines, missing alerts, and reduced detection coverage.

In security terms, this increases mean time to detect (MTTD) and weakens overall telemetry fidelity.

From an architectural standpoint, there are three primary upgrade approaches:

• Manual upgrades, where each endpoint is updated individually
• Package manager-based upgrades, common in Linux environments using apt/yum/zypper
• Centralized or automated deployments, using orchestration tools like Ansible, Puppet, or deployment policies via the Wazuh manager

For reference, vendor documentation consistently emphasizes keeping agents aligned with manager versions to avoid compatibility drift and feature mismatch.

Pre-Upgrade Checklist

Before upgrading any Wazuh agent, it is critical to validate version compatibility, system health, and configuration integrity.

Skipping these steps is one of the most common causes of failed upgrades or disconnected agents.

Verify current agent version

Knowing the installed version helps determine the correct upgrade path and whether a direct upgrade is supported.

• Linux:

/var/ossec/bin/agent_control -i

• Windows:
  Check the Wazuh Agent service panel or use the Wazuh dashboard (Agents inventory view).

Check Wazuh manager compatibility

The agent and manager must remain within supported version ranges.

Major version mismatches can lead to communication failures or partial feature support. Always confirm compatibility in the official release matrix before upgrading.

Review release notes for breaking changes

Wazuh releases may introduce:

• Rule engine changes
• Log format adjustments
• Deprecated configuration fields
• Security model updates

Skipping release notes is a frequent cause of post-upgrade alert degradation or missing telemetry.

Confirm network connectivity to Wazuh manager

Ensure the agent can still reach the manager on the required ports (commonly TCP 1514 and 1515 depending on configuration).

Connectivity issues during or after upgrade often lead to agent “disconnected” states.

Backup critical configuration files

Always back up configuration and custom logic before upgrading:

• ossec.conf
• Custom rules (/var/ossec/etc/rules/local_rules.xml)
• Custom decoders (if applicable)

This ensures rollback capability if the upgrade introduces unexpected behavior.

For additional troubleshooting context when agents fail to reconnect, see:
Wazuh Agent Not Connecting to Manager? 12 Fixes That Actually Work

Upgrade Methods Overview

There are multiple supported ways to upgrade a Wazuh agent depending on operating system, scale, and deployment strategy.

Package manager upgrade (Linux)

On Linux systems, upgrades are typically handled through native package managers:

• Debian/Ubuntu (APT):

apt-get update
apt-get install wazuh-agent

• RHEL/CentOS (YUM/DNF):

yum update wazuh-agent
# or
dnf upgrade wazuh-agent

This method is best suited for small-to-medium environments or systems managed via configuration management tools.

MSI-based upgrade (Windows)

On Windows systems, upgrades are performed using the MSI installer package provided by Wazuh.

Typical process:

• Download the latest MSI installer
• Run the installer on the endpoint
• The installer upgrades the existing agent while preserving configuration files

This method is commonly used in enterprise Windows environments or via software deployment tools such as SCCM or Intune.

For a baseline installation reference, see:
How to Install a Wazuh Agent on Windows Server

Centralized upgrade via orchestration tools

For large-scale environments, centralized upgrades are preferred to ensure consistency and reduce operational overhead.

Common approaches include:

• Ansible playbooks for rolling upgrades across Linux fleets
• Puppet/Chef for configuration-driven upgrades
• Wazuh manager-based deployment mechanisms for controlled rollout
• CI/CD-driven infrastructure pipelines in cloud-native environments

Centralized upgrades are particularly useful when managing hundreds or thousands of endpoints, ensuring version consistency and reducing configuration drift.

Expert insight (industry context)

Security engineering best practices from frameworks such as NIST emphasize maintaining up-to-date endpoint detection components to reduce exploit windows and ensure telemetry integrity.

Additionally, endpoint telemetry consistency is a key requirement in modern XDR architectures, where outdated agents can create blind spots in detection pipelines.

How to Upgrade Wazuh Agent on Linux

Linux upgrades are typically the fastest and most reliable way to update Wazuh agents, especially when using native package managers.

The exact steps depend on your Linux distribution, but the overall process is similar: update package metadata, upgrade the agent package, restart the service, and verify connectivity.

Debian/Ubuntu Systems

On Debian-based distributions such as Ubuntu, Wazuh agents can be upgraded directly through APT.

Step 1: Update repository metadata

Refresh your local package cache:

sudo apt-get update

This ensures your system is aware of the latest Wazuh package versions available in the configured repository.

Step 2: Upgrade the Wazuh agent

Run:

sudo apt-get install wazuh-agent

APT will detect that the package is already installed and upgrade it to the latest available version while preserving existing configuration files.

Step 3: Restart the agent service

After the installation completes, restart the agent:

sudo systemctl restart wazuh-agent

To confirm the service is running:

sudo systemctl status wazuh-agent

You should see the service listed as active (running).

RHEL, CentOS, and Amazon Linux

For Red Hat-based systems, upgrades are typically performed using YUM or DNF.

Step 1: Update repository metadata

For older systems:

sudo yum makecache

For newer distributions using DNF:

sudo dnf makecache

Step 2: Upgrade the Wazuh agent

Using YUM:

sudo yum update wazuh-agent

Using DNF:

sudo dnf upgrade wazuh-agent

The package manager will download and install the latest compatible agent version.

Step 3: Restart the Wazuh service

Once the upgrade finishes:

sudo systemctl restart wazuh-agent

Verify service health:

sudo systemctl status wazuh-agent

Verify the Upgrade

Regardless of your Linux distribution, always validate the upgrade before considering the process complete.

Check the installed version

You can verify the installed agent version using:

/var/ossec/bin/wazuh-control info

Or:

rpm -qa | grep wazuh-agent

For RPM-based systems.

On Debian-based systems:

dpkg -l | grep wazuh-agent

Confirm agent communication

Log in to the Wazuh dashboard and navigate to:

Agents → Agent Management

Verify that:

• The agent appears as Active
• The expected upgraded version is displayed
• The latest keepalive messages are being received
• No communication errors are present

A successful upgrade should not interrupt normal log collection or alert generation.

If the agent appears disconnected after upgrading, see:

INTERNAL LINK: Wazuh Agent Not Connecting to Manager? 12 Fixes That Actually Work

How to Upgrade Wazuh Agent on Windows

Windows upgrades are performed using the official MSI installer and generally support in-place upgrades, allowing you to retain existing configurations and agent registration information.

Step 1: Download the latest Wazuh MSI installer

Download the latest agent package from the official Wazuh releases page:

https://github.com/wazuh/wazuh/releases

Always verify that the version you download is compatible with your Wazuh manager deployment.

Step 2: Run the installer

Launch the MSI package with administrative privileges.

The installer automatically detects the existing Wazuh installation and performs an in-place upgrade.

During the process:

• Existing agent registration remains intact
• Configuration settings are preserved
• No re-enrollment is normally required

Follow the installation wizard until completion.

Step 3: Restart the Wazuh service

After the installation completes, restart the service.

Using PowerShell:

Restart-Service WazuhSvc

Or using the Windows Services console:

1. Open services.msc
2. Locate Wazuh Agent
3. Select Restart

Step 4: Validate connectivity

Open the Wazuh dashboard and verify:

• Agent status is Active
• New events are arriving
• The upgraded version is displayed
• No registration or authentication errors appear

You can also review:

C:\Program Files (x86)\ossec-agent\ossec.log

for upgrade-related messages.

For first-time deployments or installation details, see:

 How to Install a Wazuh Agent on Windows Server

Centralized or Bulk Upgrade Strategies

Manually upgrading a handful of agents is manageable, but organizations with dozens, hundreds, or thousands of endpoints should use centralized deployment methods to improve consistency and reduce administrative overhead.

Using Configuration Management Tools

Configuration management platforms allow upgrades to be executed across large environments from a central location.

Common options include:

• Ansible
• Puppet
• Chef
• Microsoft SCCM
• Microsoft Intune
• Red Hat Satellite

These tools can:

• Push new Wazuh agent versions
• Restart services automatically
• Validate installation success
• Generate deployment reports
• Roll back failed upgrades

According to the official Ansible project documentation, infrastructure automation reduces configuration drift and improves deployment consistency across large environments.

Use a Rolling Upgrade Approach

In production environments, avoid upgrading all agents simultaneously.

Instead, use a phased deployment strategy:

Phase 1: Pilot Group

Upgrade:

• Test servers
• Development systems
• Non-critical workloads

Monitor for:

• Connectivity issues
• Missing logs
• Increased CPU usage
• Unexpected alerts

Phase 2: Department or Environment Rollout

Upgrade:

• Staging systems
• Internal services
• Low-risk production systems

Validate operational stability before proceeding.

Phase 3: Full Deployment

Upgrade:

• Critical servers
• Production workloads
• High-value assets

This staged approach minimizes risk and provides an opportunity to identify issues before they affect the entire environment.

Minimize Downtime During Production Upgrades

Most Wazuh agent upgrades require only a brief service restart, but organizations should still plan upgrades carefully.

Recommended practices include:

• Schedule upgrades during maintenance windows
• Upgrade redundant systems one node at a time
• Validate manager connectivity before deployment
• Monitor agent health after each upgrade batch
• Keep previous package versions available for rollback

Security operations teams should also monitor alert volumes during and after upgrades to ensure telemetry collection remains uninterrupted.

If you are using custom detection logic, it is also a good idea to review:

How to Create Custom Detection Rules in Wazuh (With Examples)

and

How to Reduce False Positives in Wazuh

to ensure upgraded agents continue generating the expected security events and alerts.

Common Issues and Troubleshooting

Most Wazuh agent upgrades complete without incident.

However, connectivity problems, version incompatibilities, and service failures can occasionally occur.

Agent Fails to Connect After Upgrade

One of the most common post-upgrade issues is an agent that appears disconnected from the manager.

Possible Causes

Firewall or port misconfiguration

Verify that communication ports remain open between the agent and manager. Security policies or network changes may block traffic after upgrades.

Common ports include:

• TCP 1514
• TCP 1515

Depending on your deployment configuration.

Key mismatch or missing registration

The agent authentication key may become corrupted or the agent registration may no longer match the manager record.

Symptoms often include:

• Repeated authentication failures
• Registration errors in logs
• Agent stuck in disconnected status

Re-registering the agent may resolve the issue.

For a complete troubleshooting workflow, see:

Wazuh Agent Not Connecting to Manager? 12 Fixes That Actually Work

Version Mismatch Errors

Not all Wazuh versions are fully compatible with one another.

Common Causes

Agent-manager version incompatibility

Running a significantly newer agent against an older manager can result in:

• Unsupported features
• Communication failures
• Missing telemetry
• Registration problems

Manager upgrade required first

In many cases, Wazuh recommends upgrading the manager before upgrading agents.

Review the official release notes before upgrading major versions:

This helps identify compatibility requirements and migration considerations.

Service Fails to Start

Sometimes the upgrade completes successfully, but the Wazuh service fails to start afterward.

Corrupted Installation

Indicators include:

• Missing binaries
• Unexpected service termination
• Startup errors in logs

A clean reinstall may be necessary if critical files were damaged during the upgrade.

Missing Dependencies

Linux systems may encounter:

• Library dependency issues
• Repository conflicts
• Incomplete package updates

Use your package manager’s verification tools to identify missing dependencies and resolve package conflicts before restarting the service.

Configuration Errors

Custom modifications can occasionally break after version upgrades.

Examples include:

• Invalid XML syntax
• Deprecated configuration parameters
• Unsupported module settings

Review:

/var/ossec/etc/ossec.conf

and validate any customizations before restarting the service.

Organizations using custom detection content should review:

How to Create Custom Detection Rules in Wazuh (With Examples)

Best Practices for Upgrading Wazuh Agents

Following a structured upgrade process helps minimize risk and maintain continuous security visibility across your environment.

Always Test Upgrades in a Staging Environment First

Before deploying a new version to production:

• Upgrade a small test environment
• Validate custom configurations
• Review detection rules
• Confirm integrations still function correctly

Testing significantly reduces the likelihood of unexpected outages or compatibility issues.

Upgrade the Manager Before Agents When Required

Major version upgrades often require the manager to be upgraded first.

Benefits include:

• Improved compatibility
• Reduced communication errors
• Access to new agent features

Always consult official upgrade guidance before upgrading large environments.

Schedule Upgrades During Maintenance Windows

Even though agent upgrades are generally quick, maintenance windows help minimize operational impact.

Advantages include:

• Reduced risk to production systems
• Easier troubleshooting
• Better coordination with security and operations teams

For critical infrastructure, consider implementing a phased rollout strategy.

Maintain a Rollback Plan

Every upgrade should include a documented recovery process.

A rollback plan should contain:

• Previous package versions
• Configuration backups
• Re-registration procedures
• Validation steps

If an issue occurs, you can quickly restore service without prolonged monitoring gaps.

Use Centralized Management at Scale

As environments grow, manual upgrades become increasingly difficult to manage.

Centralized deployment tools help:

• Standardize upgrade procedures
• Reduce configuration drift
• Improve reporting and compliance
• Automate validation checks

Tools such as Ansible, Puppet, SCCM, and Intune can significantly reduce operational effort while improving consistency across large fleets.

Organizations managing cloud and containerized workloads should also consider validating monitoring coverage after upgrades.

Additional Resources

How to Monitor AWS CloudTrail Logs Using Wazuh

 How to Monitor Kubernetes Using Wazuh

By combining staged deployments, compatibility testing, centralized automation, and post-upgrade validation, security teams can keep Wazuh agents current while minimizing operational risk and maintaining continuous visibility across their infrastructure.