Wazuh is one of the most widely deployed open-source security platforms for threat detection, endpoint visibility, log management, compliance monitoring, and incident response.

While installing a single agent is relatively straightforward, deploying hundreds or thousands of agents across Windows, Linux, macOS, cloud workloads, and containers requires careful planning.

A successful Wazuh Agent Deployment strategy ensures every endpoint is monitored consistently, securely, and with minimal administrative effort.

Poor deployment practices often lead to disconnected agents, duplicate registrations, inconsistent configurations, missing telemetry, and increased operational overhead.

Whether you’re deploying Wazuh in a small business with a few servers or an enterprise managing thousands of endpoints across multiple regions, having a standardized deployment process is essential.

This guide walks through everything you need to know: from understanding how Wazuh agents work to choosing the right deployment model, securing communications, automating installations, troubleshooting common deployment issues, and following deployment best practices.

What Is the Wazuh Agent?

The Wazuh Agent is lightweight endpoint software installed on monitored systems.

It continuously collects security telemetry, system information, and logs before securely transmitting that data to a Wazuh Manager for analysis.

Instead of relying solely on centralized logging, Wazuh performs much of its data collection directly on each endpoint.

This provides deeper visibility into operating system events, file changes, running processes, vulnerabilities, configuration compliance, and security incidents.

Agents can be installed on:

• Windows desktops and servers
• Linux servers and workstations
• macOS devices
• Cloud virtual machines
• Virtual machines
• Container hosts
• Edge devices

Once deployed, agents continuously communicate with the Wazuh Manager, allowing organizations to detect threats in near real time.

Related Guide: How to Install a Wazuh Agent on Windows Server

Why Proper Agent Deployment Is Critical

Installing a few agents manually is manageable.

Deploying hundreds or thousands without a deployment strategy quickly becomes difficult.

Improper deployments commonly result in:

• Duplicate agent registrations
• Missing or inactive agents
• Authentication failures
• Inconsistent configurations
• Lost encryption keys
• Unmonitored systems
• Increased administrative workload

A structured deployment process ensures every endpoint:

• Registers successfully
• Uses secure authentication
• Receives standardized configurations
• Reports health consistently
• Can be updated automatically

According to the Center for Internet Security (CIS), maintaining continuous visibility of enterprise assets is a foundational security control because organizations cannot protect systems they cannot accurately inventory.

Benefits of a Well-Managed Deployment

A standardized deployment strategy provides benefits far beyond simply installing software.

These include:

• Faster onboarding of new endpoints
• Consistent security monitoring
• Reduced configuration drift
• Easier troubleshooting
• Simplified upgrades
• Centralized policy management
• Improved compliance reporting
• Lower operational costs
• Better scalability for growing environments

Organizations also spend significantly less time manually configuring agents after deployment when automation and centralized configuration are used together.

You can see our How to Configure Wazuh Agent Centralized Configuration guide for more detailed instructions.

What This Guide Covers

This guide provides a complete walkthrough of Wazuh Agent Deployment, including:

• Understanding the Wazuh Agent architecture
• Deployment models
• Agent registration
• Authentication methods
• Secure communication
• Manual deployment
• Automated deployment
• Cloud deployments
• Container deployments
• Agent grouping
• Centralized configuration
• Security best practices
• Common deployment problems
• Scaling deployments for enterprise environments

You’ll also find links to detailed tutorials covering advanced deployment scenarios and troubleshooting.

Who Should Read This Guide

This guide is designed for:

• Security engineers
• SOC analysts
• System administrators
• DevOps engineers
• Cloud engineers
• Infrastructure architects
• MSPs managing customer environments
• Anyone deploying Wazuh for the first time

Whether you’re deploying 20 agents or 20,000, the principles covered here will help you build a secure, scalable, and maintainable deployment strategy.

Understanding the Wazuh Agent

The official Wazuh architecture describes the agent as the primary component responsible for endpoint monitoring and secure communication with the manager.

Core Purpose

The primary purpose of the Wazuh Agent is to provide continuous endpoint visibility.

It accomplishes this by:

• Collecting operating system logs
• Monitoring file changes
• Detecting security events
• Identifying vulnerabilities
• Performing compliance checks
• Gathering hardware and software inventory
• Executing Active Response actions
• Reporting security telemetry to the manager

Without agents, the Wazuh platform loses much of its endpoint detection and response (EDR) capabilities.

How It Communicates with the Wazuh Manager

Each agent establishes an encrypted communication channel with the Wazuh Manager.

During operation, the agent:

1. Registers with the manager.
2. Receives authentication credentials.
3. Establishes encrypted communications.
4. Sends collected security events.
5. Receives configuration updates.
6. Executes approved Active Response commands when instructed.

Communication occurs continuously, allowing the manager to monitor endpoint health and receive new security data in near real time.

Supported Operating Systems

Wazuh supports deployment across a broad range of operating systems, including:

• Windows Server
• Windows 10 and Windows 11
• Ubuntu
• Debian
• CentOS
• Red Hat Enterprise Linux
• Rocky Linux
• AlmaLinux
• Amazon Linux
• Oracle Linux
• SUSE Linux Enterprise
• macOS

This broad compatibility makes Wazuh suitable for hybrid enterprise environments.

Components Included with the Agent

A Wazuh Agent includes multiple integrated monitoring modules, such as:

• Logcollector
• Syscheck (File Integrity Monitoring)
• Rootcheck
• Security Configuration Assessment (SCA)
• Vulnerability Detection support
• Inventory collection
• Active Response client
• Secure communications module

Each module contributes different security telemetry while operating as part of a single lightweight agent.

How the Wazuh Agent Works

Rather than performing one monitoring task, the Wazuh Agent continuously runs several specialized modules simultaneously.

Event Collection

The agent continuously collects operating system events from multiple sources.

Examples include:

• Windows Event Logs
• Linux system logs
• macOS Unified Logs
• Application logs
• Authentication logs
• Service logs
• Audit logs

Collected events are normalized before being transmitted securely to the manager.

Related Guides

• How to Monitor Windows Event Logs Using Wazuh
• How to Monitor Linux Event Logs Using Wazuh

Log Monitoring

The Logcollector module monitors configured log files for security events.

Common monitored logs include:

• Apache
• Nginx
• SSH
• Syslog
• Firewall logs
• Application logs
• Custom log files

As new log entries appear, they’re immediately forwarded to the Wazuh Manager for analysis.

See our How to Configure ossec.conf for Log Monitoring in Wazuh for more detailed instructions.

File Integrity Monitoring (FIM)

The Syscheck module tracks changes to critical files and directories.

It detects:

• File modifications
• New files
• Deleted files
• Permission changes
• Ownership changes
• Registry modifications (Windows)

These changes can indicate malware, ransomware, or unauthorized administrator activity.

Related Guide: How to Configure File Integrity Monitoring (FIM) in Wazuh

Vulnerability Detection

The agent collects operating system package information that enables Wazuh’s Vulnerability Detection module to identify known CVEs affecting installed software.

Organizations can quickly identify vulnerable systems requiring updates or remediation.

Related Guide: Wazuh Vulnerability Detection Not Working? Here’s How to Fix It

Security Configuration Assessment (SCA)

SCA evaluates systems against security baselines and compliance frameworks.

Examples include:

• CIS Benchmarks
• PCI DSS
• NIST recommendations
• Internal security standards

Results help administrators identify configuration weaknesses before attackers do.

The CIS Benchmarks are widely recognized as practical, consensus-based hardening guides used across enterprise environments.

Inventory Collection

The agent continuously inventories endpoint information, including:

• Installed software
• Running services
• Open ports
• Network interfaces
• Hardware information
• Operating system version

This inventory assists with asset management and vulnerability assessments.

Active Response

When configured, the Wazuh Manager can instruct agents to automatically respond to detected threats.

Examples include:

• Blocking malicious IP addresses
• Disabling compromised accounts
• Killing malicious processes
• Removing firewall rules
• Executing custom scripts

Automated responses reduce attacker dwell time and accelerate incident containment.

Related Guide: How to Configure Wazuh Active Response

Wazuh Agent Deployment Architecture

Understanding how Wazuh agents communicate with the manager helps administrators design secure, scalable deployments that remain reliable as environments grow.

The deployment architecture includes agent registration, authentication, encrypted communications, and several deployment models suited to different infrastructures.

Agent-to-Manager Communication

The Wazuh Manager serves as the central coordination point for every deployed agent.

Each agent establishes a trusted relationship with the manager before sending security telemetry.

After registration, communication becomes continuous, allowing the manager to receive endpoint events, distribute configuration updates, and coordinate Active Response actions.

This architecture supports deployments ranging from a handful of endpoints to tens of thousands of systems.

Registration Process

Before an agent can send data, it must first register with the Wazuh Manager.

During registration:

1. The agent requests enrollment.
2. The manager validates the request.
3. A unique agent ID is assigned.
4. Cryptographic keys are exchanged.
5. The agent is added to the deployment.

Large organizations typically automate this registration process to reduce manual effort and prevent configuration inconsistencies.

See our Step-by-Step Guide to Wazuh Agent Auto-Enrollment on detailed instructions on enrollment.

Authentication

Authentication ensures that only trusted endpoints join the deployment.

Common authentication methods include:

• Manual registration
• Authentication daemon (authd)
• Enrollment passwords
• Auto-enrollment
• Pre-generated agent keys

Strong authentication prevents rogue devices from registering with the manager.

Secure Communication

Once authenticated, every communication session between the agent and manager is protected.

This secure channel ensures:

• Confidentiality
• Integrity
• Endpoint authentication
• Protection against man-in-the-middle attacks
• Secure configuration delivery

Secure communications are particularly important when agents operate across the public Internet or multiple cloud providers.

Encryption

Wazuh encrypts communications between agents and managers using industry-standard cryptographic mechanisms, ensuring that logs, alerts, inventory data, and configuration updates cannot be easily intercepted or modified in transit.

The official Wazuh documentation recommends maintaining secure key management and protecting agent credentials throughout the deployment lifecycle.

Ports Used

Typical ports used during deployment include:

Firewall rules should allow only the required traffic between agents and managers while blocking unnecessary network access.

Deployment Models

There is no single deployment approach that fits every organization.

The best model depends on infrastructure size, operating systems, automation capabilities, and operational requirements.

Manual Deployment

Manual deployment works well for:

• Small environments
• Testing labs
• Proof-of-concept deployments
• Individual servers

Administrators manually install the agent, register it, configure it, and verify connectivity.

Although simple, this approach becomes difficult to manage as the number of endpoints increases.

Automated Deployment

Automation is the preferred deployment method for medium and large environments.

Common automation platforms include:

• Ansible
• SCCM
• Microsoft Intune
• Group Policy
• Puppet
• Chef
• SaltStack
• Terraform
• Cloud-init

Automated deployments improve consistency, reduce human error, and significantly accelerate onboarding.

See our How to Automate Bulk Wazuh Agent Deployment with Ansible and SCCM guide on more detailed instructions on automated deployments.

Cloud Deployment

Cloud deployments install agents on virtual machines hosted in providers such as:

• AWS
• Microsoft Azure
• Google Cloud Platform
• Oracle Cloud
• DigitalOcean

Organizations often combine cloud-init, Terraform, auto-scaling groups, or virtual machine images to automatically deploy agents as new instances are created.

Virtual Machine Deployment

Many organizations deploy Wazuh agents as part of standardized virtual machine templates.

This approach ensures every newly provisioned VM already includes:

• The Wazuh Agent
• Required configurations
• Enrollment settings
• Monitoring policies
• Security baselines

Golden images help maintain consistency across large virtualized environments.

Container Deployment

While Wazuh agents are typically installed on container hosts rather than individual ephemeral containers, some environments deploy agents alongside containerized workloads when persistent monitoring is required.

Container-focused deployments should account for:

• Dynamic workloads
• Short-lived containers
• Orchestrators such as Kubernetes
• Shared host resources

Related Guide: How to Monitor Kubernetes Using Wazuh

Hybrid Deployments

Most enterprise deployments combine multiple deployment models.

For example, an organization may simultaneously monitor:

• On-premises Windows servers
• Linux web servers
• Azure virtual machines
• AWS EC2 instances
• Kubernetes clusters
• Remote employee laptops
• Branch office systems

A hybrid deployment strategy allows all of these endpoints to report to a centralized Wazuh deployment while using deployment methods tailored to each environment.

Prerequisites Before Deployment

Preparing your environment before deploying Wazuh agents significantly reduces installation failures, registration issues, and post-deployment troubleshooting.

Before installing agents, verify that your Wazuh Manager is properly configured, network communication is available, authentication services are operational, and endpoints meet the necessary software and security requirements.

Taking the time to validate these prerequisites helps ensure a smooth deployment, whether you’re installing a handful of agents or rolling out thousands across multiple locations.

Wazuh Manager Requirements

The Wazuh Manager acts as the central communication point for every deployed agent.

A properly configured manager is essential for successful enrollment, secure communications, and ongoing monitoring.

Before deploying agents, confirm that the manager is healthy and capable of accepting new registrations.

Manager Version Compatibility

Always verify that your Wazuh agents are compatible with the version of the Wazuh Manager you’re running.

While Wazuh supports communication between certain agent and manager versions, deploying matching versions is considered a best practice because it minimizes compatibility issues and ensures access to the latest features, bug fixes, and security updates.

Before large-scale deployments:

• Verify the manager version.
• Download the matching agent version.
• Review release notes before upgrading.
• Test compatibility in a staging environment.

The official Wazuh documentation provides compatibility guidance and upgrade recommendations.

Network Connectivity

Each agent must be able to communicate reliably with the Wazuh Manager throughout its lifecycle.

Before deployment, verify:

• DNS resolution (if using hostnames)
• Stable network connectivity
• Proper routing
• VPN connectivity for remote endpoints
• Load balancer configuration (if applicable)
• Low packet loss between agents and managers

Simple connectivity tests such as ping, traceroute, nc, or telnet can help identify networking issues before installation.

Agent Authentication Service

If you plan to use automatic enrollment, ensure the Wazuh authentication daemon (authd) is enabled and listening for incoming registration requests.

Verify:

• The service is running.
• Port 1515 is reachable.
• Enrollment passwords are configured if required.
• Authentication policies match your deployment plan.

Organizations deploying thousands of endpoints typically rely on automated enrollment rather than manually importing agent keys.

Firewall Rules

Firewall rules are among the most common causes of deployment failures.

Ensure firewalls allow communication between agents and the Wazuh Manager on the required ports.

Typical requirements include:

Restrict access to trusted networks whenever possible instead of exposing these services publicly.

Endpoint Requirements

Every endpoint should meet the minimum software and hardware requirements before installation.

Linux

Supported Linux distributions include:

• Ubuntu
• Debian
• Rocky Linux
• AlmaLinux
• CentOS
• Red Hat Enterprise Linux
• Amazon Linux
• Oracle Linux
• SUSE Linux Enterprise

Before installation, verify:

• Root or sudo access
• Supported architecture
• Internet or repository access
• Required package manager
• Available disk space
• Accurate system time

Windows

Supported Windows systems include both desktop and server editions.

Before deployment:

• Ensure Administrator privileges are available.
• Confirm Windows Installer (MSI) is functioning.
• Verify Microsoft Defender or antivirus exclusions if necessary.
• Confirm Windows Firewall permits communication.
• Apply pending Windows updates before deployment when practical.

macOS

When deploying to macOS devices, administrators should verify:

• Supported macOS version
• Administrative privileges
• Full Disk Access availability
• Network connectivity
• Required system permissions

Apple’s security model requires explicit user approval for several monitoring capabilities, making macOS deployments slightly different from Linux and Windows.

Security Requirements

Secure deployments protect both the Wazuh infrastructure and monitored endpoints.

Several security controls should be validated before agents begin communicating with the manager.

Certificates

If your deployment uses TLS certificates or reverse proxies, ensure certificates are:

• Valid
• Trusted
• Not expired
• Properly configured
• Issued by an approved certificate authority when appropriate

Certificate validation failures can prevent agents or administrators from securely communicating with Wazuh services.

Authentication Keys

Each Wazuh agent receives a unique authentication key during registration.

These keys should be treated as sensitive credentials.

Best practices include:

• Never sharing keys between agents.
• Regenerating compromised keys.
• Removing keys for decommissioned endpoints.
• Protecting backups containing agent keys.

Proper key management helps prevent unauthorized systems from impersonating legitimate agents.

Least Privilege

Deploy agents using the minimum privileges necessary for the required monitoring tasks.

Whenever possible:

• Limit administrative access.
• Restrict filesystem permissions.
• Use Linux capabilities instead of full root privileges where appropriate.
• Review service permissions regularly.

Following the principle of least privilege reduces the impact of compromised systems and aligns with modern security best practices.

See our How to Configure Wazuh Agent Non Root Privileges on Linux Systems guide for more detailed instructions on non root privileges.

Time Synchronization

Accurate system clocks are essential for reliable security monitoring.

Unsynchronized time can lead to:

• Incorrect alert timestamps
• Authentication problems
• Correlation failures
• Certificate validation issues
• Difficult incident investigations

Synchronize managers and endpoints using a reliable time source such as NTP or Chrony before deployment.

Installing the Wazuh Agent

Once your infrastructure is prepared, the next step is installing the Wazuh Agent on each endpoint.

The installation process varies slightly between Linux, Windows, and macOS, but the overall workflow remains consistent: install the software, configure the manager connection, register the agent, and verify successful communication.

Linux Installation

Linux deployments are commonly performed using official Wazuh repositories, making installation and future updates much easier.

Repository Installation

Using the official Wazuh repository allows package managers to automatically receive future updates.

The general process involves:

1. Adding the Wazuh repository.
2. Importing the repository signing key.
3. Refreshing package indexes.
4. Installing the agent package.

Using official repositories helps ensure package authenticity and simplifies lifecycle management.

Package Installation

Depending on the Linux distribution, installation may use:

• apt
• dnf
• yum
• zypper

After installation, verify:

• Package installation completed successfully.
• Service files exist.
• Configuration files were created.
• Required dependencies are installed.

Initial Configuration

Before starting the agent, configure:

• Wazuh Manager address
• Agent name
• Enrollment method
• Authentication settings
• Optional agent groups

After configuration:

• Start the agent service.
• Verify successful registration.
• Confirm the endpoint appears in the Wazuh Dashboard.

Related Guide: How to Configure Wazuh Agent Non Root Privileges on Linux Systems

Windows Installation

Windows agents are typically installed using the official MSI installer.

Deployments may be interactive for individual systems or silent for enterprise rollouts.

MSI Installer

For small deployments, administrators can launch the MSI package and follow the installation wizard.

Typical configuration options include:

• Manager address
• Agent name
• Enrollment settings
• Installation directory

Once installed, the Wazuh Agent service is registered with Windows.

Silent Installation

Enterprise deployments usually rely on unattended installations.

Silent installations are commonly integrated with:

• Microsoft Intune
• SCCM
• Group Policy
• PowerShell
• RMM platforms

This approach enables administrators to deploy agents across hundreds or thousands of Windows systems with minimal user interaction.

See our guide onTroubleshooting Wazuh Silent Install Failures any errors occur.

Service Configuration

After installation, confirm that:

• The Wazuh Agent service is running.
• Automatic startup is enabled.
• The service account has the required permissions.
• The agent successfully connects to the manager.

If Windows security logs are not being collected correctly, review local permissions and event log access.

Related Guide: Fix Wazuh Agent Access Denied Errors on Windows Security Logs

macOS Installation

Deploying the Wazuh Agent on macOS follows a process similar to Linux but requires additional operating system permissions because of Apple’s security protections.

Installing the Agent

Administrators can install the official Wazuh package using supported deployment methods such as:

• Manual installation
• Mobile Device Management (MDM)
• Enterprise software deployment platforms

After installation:

• Configure the manager address.
• Register the agent.
• Start the service.
• Verify connectivity.

Granting Required Permissions

macOS requires explicit approval for several security-sensitive monitoring capabilities.

Depending on the features enabled, administrators may need to grant:

• Full Disk Access
• Accessibility permissions
• System extensions
• Privacy permissions

Failure to approve these permissions may prevent log collection or File Integrity Monitoring from functioning correctly.

See our Resolving macOS Wazuh Agent Failures: Missing Full Disk Access Fix guide for  macOS Wazuh agent failures.

Registering Agents with the Wazuh Manager

Installing the agent is only the first step.

Before an endpoint begins reporting security data, it must successfully register with the Wazuh Manager and establish a trusted communication relationship.

Organizations can choose between manual registration and automated enrollment depending on the size and complexity of their environment.

Manual Registration

Manual registration is appropriate for:

• Small environments
• Test labs
• Proof-of-concept deployments
• Individual server installations

It provides administrators with direct control over the enrollment process but becomes impractical at scale.

agent-auth

The agent-auth utility allows agents to securely authenticate with the Wazuh Manager and obtain their unique authentication credentials.

During execution, the tool:

• Contacts the manager.
• Requests enrollment.
• Receives authentication keys.
• Stores credentials locally.
• Completes the registration process.

This approach eliminates the need to manually copy key files between systems.

Managing Keys

Every registered agent receives a unique authentication key that identifies it to the manager.

Administrators should:

• Remove keys for retired systems.
• Rotate compromised keys.
• Maintain secure backups.
• Avoid reusing keys across multiple endpoints.

Improper key management can lead to duplicate registrations or unauthorized agent connections.

See our Why Is client.keys File Empty? Restoring Lost Wazuh Agents guide on key management issues.

Verification

After registration, verify that:

• The agent appears in the dashboard.
• Status is Active.
• Recent events are being received.
• The correct operating system is detected.
• Assigned groups are accurate.

Testing immediately after registration helps identify issues before the endpoint enters production.

Auto Enrollment

Large organizations almost always automate agent enrollment to simplify deployment and reduce administrative overhead.

Auto-enrollment enables newly installed agents to register automatically with minimal administrator intervention.

Authentication Daemon

The Wazuh authentication daemon (authd) processes enrollment requests from new agents.

Administrators should verify:

• The daemon is enabled.
• Enrollment policies are configured.
• Required firewall ports are open.
• Logging is enabled for troubleshooting.

Enrollment Password

Many deployments require agents to provide an enrollment password before registration is accepted.

This additional authentication layer helps prevent unauthorized devices from joining the environment.

Best practices include:

• Using strong passwords.
• Rotating passwords periodically.
• Avoiding hard-coded credentials in deployment scripts.
• Storing secrets securely.

Security Keys

After successful enrollment, each agent receives a unique security key that authenticates future communications with the manager.

Protect these keys just as you would any other authentication credential, and revoke them promptly if an endpoint is compromised or decommissioned.

Group Assignment

Agent groups simplify configuration management by allowing administrators to apply shared settings to collections of endpoints.

Groups may be organized by:

• Operating system
• Department
• Geographic location
• Environment (development, staging, production)
• Business unit
• Server role

Centralized group management makes large deployments significantly easier to administer.

Related Guide: Step-by-Step Guide to Wazuh Agent Auto-Enrollment

Managing Agent Authentication Keys

Authentication keys are one of the most important components of a secure Wazuh deployment.

Every agent must possess a unique key that establishes its identity and allows it to communicate securely with the Wazuh Manager.

Proper key management helps prevent unauthorized registrations, duplicate agents, and communication failures.

Whether you’re deploying a few systems or thousands of endpoints, understanding how Wazuh generates, stores, and manages authentication keys is essential for maintaining a healthy deployment.

Understanding client.keys

The client.keys file is the Wazuh Manager’s database of registered agents and their authentication credentials.

Every time an agent is enrolled, the manager records its information in this file.

Each entry typically contains:

• Agent ID
• Agent name
• IP address (or any)
• Unique authentication key

The manager references this information whenever an agent connects, ensuring that only trusted endpoints can communicate with the deployment.

Because this file controls agent authentication, it should be protected from unauthorized access and included in secure backup procedures.

Purpose

The primary purpose of client.keys is to establish trust between the Wazuh Manager and every enrolled endpoint.

It allows the manager to:

• Authenticate connecting agents.
• Identify each endpoint uniquely.
• Prevent unauthorized registrations.
• Validate encrypted communications.
• Maintain secure agent identities.

Without valid authentication keys, agents cannot successfully communicate with the manager.

Key Generation

Authentication keys are generated during the agent enrollment process.

Depending on your deployment method, keys may be created through:

• Manual registration
• agent-auth
• Authentication daemon (authd)
• Auto-enrollment
• Management API workflows

Each enrolled endpoint should receive its own unique key.

Reusing keys across multiple systems can lead to registration conflicts and inaccurate inventory information.

Security Considerations

Authentication keys should be treated like sensitive credentials.

Security best practices include:

• Store keys securely.
• Never publish keys in repositories or documentation.
• Avoid sharing keys between systems.
• Rotate keys if compromise is suspected.
• Remove keys for retired or decommissioned agents.
• Protect backups containing client.keys.

Organizations with mature security programs often include agent key management as part of their broader credential lifecycle processes.

Common Key Problems

Although authentication keys are relatively simple, several issues commonly occur during deployments, particularly in environments with frequent provisioning and decommissioning of systems.

Empty client.keys

An empty client.keys file usually indicates that no agents are currently registered or that the file has been accidentally deleted, overwritten, or corrupted.

Common causes include:

• Failed migrations
• Accidental file deletion
• Restore failures
• Incorrect permissions
• Misconfigured enrollment

This issue prevents existing agents from authenticating with the manager until valid keys are restored or regenerated.

See our Why Is client.keys File Empty? Restoring Lost Wazuh Agents guide to resolve key issues.

Duplicate Agents

Duplicate registrations often occur when:

• System images are cloned after enrollment.
• Authentication keys are reused.
• Existing agents are reinstalled without cleanup.
• Hostnames are duplicated.
• Virtual machines are restored from snapshots.

These duplicates can cause inaccurate reporting and make endpoint management more difficult.

Lost Keys

Authentication keys may be lost because of:

• Server failures
• Backup restoration errors
• Manual deletion
• Corrupted storage
• Migration mistakes

If a valid key is unavailable, the affected endpoint must typically be re-enrolled before secure communication can resume.

Regenerating Keys

When keys are lost or compromised, administrators can generate new credentials by:

1. Removing the existing agent registration.
2. Creating a new registration.
3. Re-enrolling the endpoint.
4. Verifying successful communication.

After regeneration, administrators should confirm that the old authentication key is no longer accepted.

Configuring the Wazuh Agent

After installation and registration, the next step is configuring the agent.

Proper configuration determines what information the endpoint collects, how frequently it communicates with the manager, which logs are monitored, and how security policies are applied.

Wazuh supports both local configuration on individual agents and centralized configuration managed from the Wazuh Manager, allowing organizations to balance flexibility with operational efficiency.

Local Configuration

Local configuration is stored directly on each endpoint and is ideal for settings that are unique to a particular system.

Configuration changes take effect on that individual agent without affecting others.

ossec.conf Overview

The primary local configuration file is ossec.conf.

This XML-based file controls many aspects of agent behavior, including:

• Manager connection settings
• Log monitoring
• File Integrity Monitoring
• Active Response
• Security Configuration Assessment
• Inventory collection
• Module configuration

Administrators should validate the syntax after making changes to avoid configuration errors.

Local Monitoring

Individual agents can be configured to monitor resources that are unique to that endpoint, such as:

• Custom application logs
• Database logs
• Proprietary software
• Local scripts
• Specialized security tools
• Organization-specific directories

Local monitoring provides flexibility without affecting the rest of the deployment.

Agent Settings

Common agent settings include:

• Manager address
• Communication intervals
• Log collection paths
• Buffer sizes
• Scan schedules
• Inventory frequency
• File Integrity Monitoring paths
• Active Response options

Carefully tuning these settings helps balance visibility with system performance.

See our How to Configure ossec.conf for Log Monitoring in Wazuh guide on more detailed instructions on how to configure ossec.conf.

Centralized Configuration

Managing hundreds or thousands of agents individually is inefficient.

Centralized configuration enables administrators to define shared settings once and distribute them automatically to groups of endpoints.

This approach simplifies administration, improves consistency, and reduces configuration drift.

agent.conf Overview

The agent.conf file allows administrators to centrally manage agent settings from the Wazuh Manager.

Common centrally managed configurations include:

• Log monitoring
• File Integrity Monitoring
• SCA policies
• Rootcheck settings
• Inventory collection
• Active Response
• Custom module configurations

Changes are automatically delivered to applicable agents during their regular synchronization process.

Agent Groups

Groups allow administrators to organize endpoints with similar monitoring requirements.

Examples include:

• Linux servers
• Windows workstations
• Web servers
• Database servers
• Domain controllers
• Cloud instances
• Development environments

Each group can receive its own configuration policies without affecting unrelated systems.

Shared Configurations

Shared configurations help standardize monitoring across large environments.

Examples include:

• Standard log sources
• Common File Integrity Monitoring rules
• Compliance policies
• Vulnerability scanning schedules
• Active Response actions
• Inventory collection intervals

This consistency makes deployments easier to maintain and audit.

Configuration Inheritance

A single endpoint may inherit multiple configuration settings depending on its assigned group and deployment architecture.

A well-designed group hierarchy allows organizations to:

• Reuse common settings.
• Minimize duplicate configurations.
• Simplify policy updates.
• Scale deployments efficiently.

When multiple configuration sources apply, administrators should carefully test the resulting configuration to ensure it behaves as expected.

Related Guide: How to Configure Wazuh Agent Centralized Configuration

Configuring Log Monitoring

Log monitoring is one of the core functions of the Wazuh Agent.

By continuously collecting operating system and application logs, the agent enables real-time threat detection, incident investigation, compliance reporting, and security monitoring.

The specific log sources available vary depending on the operating system, but the overall workflow remains the same: collect events locally, normalize the data, securely transmit it to the Wazuh Manager, and correlate it with detection rules.

Linux Log Monitoring

Linux systems generate security events from multiple logging services and applications. Wazuh can monitor both standard system logs and custom log files.

Syslog

Traditional Linux distributions commonly store events using Syslog.

Common monitored files include:

• /var/log/syslog
• /var/log/messages
• /var/log/auth.log
• /var/log/secure

These logs contain authentication events, service activity, kernel messages, and system errors that are valuable for security monitoring.

Journald

Many modern Linux distributions use systemd-journald instead of traditional Syslog.

Monitoring Journald provides visibility into:

• Service startup failures
• Authentication events
• Kernel messages
• System services
• Hardware events
• Boot logs

Administrators should configure the agent appropriately based on the logging framework used by each distribution.

Custom Logs

Organizations often need to monitor proprietary applications in addition to operating system logs.

Examples include:

• Web applications
• ERP platforms
• Financial systems
• Internal APIs
• Custom security tools
• Business applications

Custom log monitoring is configured by defining additional log sources in the agent configuration.

Audit Logs

Linux audit logs provide detailed records of security-sensitive operating system activity.

Examples include:

• Privileged command execution
• User authentication
• File access
• Permission changes
• Process creation
• SELinux events

These logs are particularly valuable for compliance reporting and forensic investigations.

Related Guide: How to Monitor Linux Event Logs Using Wazuh

Windows Event Logs

Windows stores operating system events within the Windows Event Log framework.

The Wazuh Agent can collect events from multiple event channels simultaneously.

Security Logs

Security logs contain many of the most important security events, including:

• Successful logins
• Failed login attempts
• Privilege escalation
• Account lockouts
• User creation
• Group membership changes
• Audit policy events

These logs are frequently used for threat detection and compliance reporting.

System Logs

System logs capture operating system activity such as:

• Driver failures
• Service startup events
• Hardware issues
• Operating system errors
• Kernel events
• Boot information

Monitoring these events helps identify operational issues that may impact security.

Application Logs

Application logs provide visibility into software installed on Windows systems.

Examples include:

• Microsoft SQL Server
• IIS
• Exchange Server
• Third-party applications
• Custom enterprise software

Collecting these logs enables broader detection coverage beyond the operating system itself.

macOS Logs

macOS uses a different logging architecture than Linux and Windows while still providing valuable security telemetry.

The Wazuh Agent can monitor both traditional log files and Apple’s modern logging framework.

Unified Logging

Apple’s Unified Logging framework consolidates operating system and application events into a centralized logging system.

These logs include:

• Application activity
• Authentication events
• System services
• Network events
• Security-related messages

Monitoring Unified Logging provides comprehensive visibility into macOS endpoint activity.

System Logs

In addition to Unified Logging, administrators may monitor traditional macOS system logs for:

• Boot events
• Service failures
• Daemon activity
• Application errors
• Security-related messages

Combining multiple log sources provides more complete endpoint visibility and improves the effectiveness of Wazuh’s detection capabilities.

Large-Scale Wazuh Agent Deployment

As Wazuh deployments grow beyond a few dozen endpoints, manual installation and configuration become increasingly difficult to manage.

Large-scale deployments require automation to ensure consistency, reduce administrative overhead, and accelerate onboarding of new systems.

Whether you’re managing hundreds of workstations, thousands of cloud instances, or a globally distributed enterprise, automated deployment allows every endpoint to be installed, configured, enrolled, and monitored using repeatable processes.

Organizations that invest in deployment automation also find it easier to maintain standardized configurations, perform upgrades, and recover from infrastructure changes.

Why Automation Matters

Automation transforms Wazuh deployment from a manual task into a repeatable operational process.

Instead of configuring each endpoint individually, administrators can define deployment logic once and apply it consistently across the entire environment.

Automation also integrates well with modern Infrastructure as Code (IaC), configuration management, and endpoint management platforms.

Consistency

One of the biggest advantages of automation is consistency.

Automated deployments ensure every agent:

• Uses the same installation package.
• Connects to the correct manager.
• Registers using approved methods.
• Receives standardized configurations.
• Belongs to the correct agent groups.
• Starts with the required monitoring policies.

Consistency minimizes configuration drift and simplifies long-term administration.

Speed

Automation dramatically reduces deployment time.

For example:

• Hundreds of endpoints can be deployed simultaneously.
• New virtual machines can enroll automatically during provisioning.
• Remote systems can be onboarded without administrator intervention.
• Cloud instances can register immediately after startup.

What might take weeks manually can often be completed in hours using automation.

Reduced Errors

Manual deployments are prone to mistakes such as:

• Incorrect manager addresses
• Typographical errors
• Duplicate agent names
• Missing configuration settings
• Forgotten enrollment steps
• Inconsistent monitoring policies

Automated workflows eliminate many of these human errors while improving deployment reliability.

According to the National Institute of Standards and Technology (NIST), standardized and automated system configuration management helps reduce operational risk, improve consistency, and strengthen organizational security.

Deployment Tools

Several automation platforms can be used to deploy Wazuh agents depending on your infrastructure and operating systems.

Ansible

Ansible is one of the most popular deployment tools for Linux and hybrid environments.

Common automation tasks include:

• Installing packages
• Editing configuration files
• Registering agents
• Assigning agent groups
• Starting services
• Performing upgrades

Its agentless architecture makes it especially attractive for managing Linux servers at scale.

SCCM

Microsoft System Center Configuration Manager (SCCM), now part of Microsoft Configuration Manager, enables enterprise-scale deployment of Wazuh agents across Windows environments.

Administrators can use SCCM to:

• Distribute MSI packages
• Perform silent installations
• Schedule deployments
• Monitor installation status
• Deploy updates
• Remove outdated agents

Microsoft Intune

Organizations managing remote or hybrid workforces often use Microsoft Intune.

Intune supports:

• Cloud-based deployments
• Remote installations
• Device compliance policies
• Automated updates
• Endpoint lifecycle management

This makes it well suited for laptops that rarely connect directly to corporate networks.

Group Policy

For traditional Active Directory environments, Group Policy can deploy Wazuh agents during computer startup or user logon.

While less flexible than modern endpoint management platforms, it remains a practical solution for many Windows networks.

Puppet

Puppet enables declarative configuration management for large infrastructures.

Administrators can define the desired state of:

• Installed packages
• Configuration files
• Services
• Enrollment settings

Puppet automatically enforces these configurations over time.

Chef

Chef uses Infrastructure as Code principles to automate deployments across physical, virtual, and cloud environments.

Also, Chef recipes can:

• Install agents
• Configure enrollment
• Apply monitoring policies
• Perform upgrades
• Maintain configuration consistency

SaltStack

SaltStack provides fast, event-driven automation suitable for very large deployments.

Its architecture allows administrators to deploy and manage thousands of Wazuh agents efficiently while responding to infrastructure changes in near real time.

Terraform

Terraform is commonly used to provision infrastructure in cloud environments.

Combined with cloud-init or configuration management tools, Terraform can automatically:

• Create virtual machines
• Install Wazuh agents
• Register endpoints
• Assign groups
• Configure monitoring

This enables fully automated infrastructure provisioning from code.

Kubernetes

Although Wazuh agents are typically installed on Kubernetes worker nodes rather than individual containers, Kubernetes automation can simplify deployments within containerized environments.

Administrators may use:

• DaemonSets
• Node initialization scripts
• Infrastructure automation
• Configuration management integrations

This ensures consistent monitoring across every cluster node.

Cloud-init

Cloud-init allows Linux virtual machines to configure themselves automatically during first boot.

Organizations commonly use cloud-init to:

• Install the Wazuh Agent
• Configure manager addresses
• Register endpoints
• Join agent groups
• Start services automatically

This approach is particularly effective for auto-scaling cloud environments where instances are created and destroyed dynamically.

Related Guide: How to Automate Bulk Wazuh Agent Deployment with Ansible and SCCM

Running Wazuh Agents Without Root Privileges

Traditionally, Linux monitoring agents have required root privileges to access system resources.

However, many organizations now seek to reduce privileged access wherever possible by running security software with only the permissions required for its intended functions.

Wazuh supports non-root deployments for many monitoring scenarios through Linux capabilities and carefully assigned permissions.

While certain advanced features may still require elevated privileges, adopting a least-privilege model can significantly improve the security of your environment.

Benefits

Running Wazuh agents with reduced privileges aligns with modern security practices and regulatory recommendations.

Rather than granting unrestricted root access, administrators can provide only the capabilities needed for specific monitoring tasks.

Improved Security

Reducing privileged access lowers the potential impact of a compromised agent.

If an attacker gains control of a non-root process, their ability to modify the operating system or access sensitive resources is significantly more limited than if the process were running as root.

This follows the widely accepted Principle of Least Privilege (PoLP), a core security concept recommended by organizations such as NIST and CIS.

Reduced Attack Surface

Every privileged process increases the attack surface of a system.

Running the Wazuh Agent with limited permissions helps:

• Restrict unauthorized system access.
• Limit privilege escalation opportunities.
• Reduce exposure to software vulnerabilities.
• Strengthen defense-in-depth strategies.

Compliance

Many compliance frameworks encourage minimizing privileged access wherever feasible.

Examples include:

• CIS Controls
• PCI DSS
• ISO/IEC 27001
• NIST Cybersecurity Framework

Using least-privileged monitoring agents can support broader organizational compliance objectives by reducing unnecessary administrative permissions.

Linux Capabilities

Linux capabilities allow administrators to grant specific privileges without providing full root access.

Depending on the enabled modules, the Wazuh Agent may require capabilities that permit operations such as:

• Reading protected log files.
• Monitoring network activity.
• Accessing audit information.
• Inspecting specific system resources.

This granular permission model provides greater flexibility than running the entire service as the root user.

Required Permissions

The permissions required depend on which Wazuh modules are enabled.

Features that may require elevated access include:

• File Integrity Monitoring on protected directories
• Audit log collection
• Active Response execution
• Certain inventory functions
• Security Configuration Assessment checks

Administrators should evaluate which capabilities are necessary for their specific deployment rather than granting excessive permissions by default.

Limitations

Although non-root deployments improve security, some limitations should be considered.

Certain monitoring features may be restricted if the agent lacks sufficient permissions, such as:

• Access to protected system files
• Monitoring privileged application logs
• Executing administrative Active Response actions
• Collecting specific kernel or audit events

Before adopting a non-root deployment, thoroughly test all required monitoring functions.

Best Practices

For secure non-root deployments:

• Grant only the capabilities required.
• Avoid running the entire service as root when unnecessary.
• Regularly audit assigned permissions.
• Protect configuration files from unauthorized modification.
• Test monitoring functionality after permission changes.
• Document any exceptions requiring elevated privileges.

Related Guides: How to Configure Wazuh Agent Non Root Privileges on Linux Systems

Managing Wazuh Agents After Deployment

Deploying agents is only the beginning of their lifecycle.

Ongoing management ensures endpoints remain secure, healthy, and aligned with organizational policies as operating systems, applications, and the Wazuh platform evolve.

Effective post-deployment management includes regular updates, group administration, health monitoring, and inventory tracking.

Updating Agents

Keeping agents up to date ensures they receive the latest security fixes, performance improvements, compatibility updates, and new features.

Administrators should establish a routine update process rather than allowing endpoints to remain on outdated versions for extended periods.

Rolling Upgrades

Large environments should avoid upgrading every agent simultaneously.

Rolling upgrades allow administrators to:

1. Upgrade a small pilot group.
2. Validate functionality.
3. Monitor performance.
4. Expand deployment gradually.
5. Complete organization-wide upgrades.

This phased approach minimizes operational risk and simplifies troubleshooting if issues arise.

Version Compatibility

Before upgrading agents, verify compatibility with the existing Wazuh Manager.

Best practices include:

• Reviewing release notes.
• Testing upgrades in staging.
• Updating managers before agents when recommended.
• Maintaining consistent software versions whenever possible.

Careful version management helps prevent communication and feature compatibility issues.

Rollback Strategies

Despite thorough testing, software upgrades occasionally introduce unexpected issues.

Every upgrade plan should include a rollback strategy that defines:

• Previous package versions
• Backup procedures
• Configuration restoration
• Validation steps
• Recovery timelines

A documented rollback process reduces downtime if an upgrade fails.

Assigning Agent Groups

Agent groups simplify administration by allowing common configurations to be applied to multiple endpoints simultaneously.

Rather than configuring each system individually, administrators manage policies at the group level.

Static Groups

Static groups are assigned manually and remain unchanged until an administrator modifies them.

Examples include:

• Production servers
• Domain controllers
• Database servers
• Web servers
• Executive workstations

Static assignments work well for infrastructure with stable roles.

Dynamic Groups

Some organizations automate group assignments based on provisioning workflows or infrastructure metadata.

Dynamic grouping can be based on:

• Operating system
• Cloud provider
• Geographic region
• Business unit
• Environment (development, staging, production)
• Server role

Automated group management helps maintain consistency in rapidly changing environments.

Monitoring Agent Health

Routine health monitoring ensures every endpoint continues reporting as expected after deployment.

Administrators should regularly review agent status within the Wazuh Dashboard and investigate systems that stop communicating or experience abnormal behavior.

Connection Status

The connection status indicates whether an agent is actively communicating with the Wazuh Manager.

Administrators should investigate agents that appear:

• Disconnected
• Never connected
• Pending registration
• Frequently reconnecting

Early detection of connectivity problems helps prevent monitoring gaps.

Last Keepalive

Agents periodically send keepalive messages to confirm they are online.

Monitoring the last keepalive timestamp helps identify:

• Offline endpoints
• Network interruptions
• Agent service failures
• Systems requiring maintenance

Event Throughput

Monitoring event volume provides insight into agent activity.

Unexpected changes may indicate:

• Log collection failures
• Configuration problems
• Service interruptions
• Reduced endpoint activity
• Excessive logging
• Performance bottlenecks

Tracking throughput over time also helps identify capacity planning requirements.

Agent Inventory

The Wazuh Agent continuously reports inventory information that helps administrators maintain visibility across their environment.

Typical inventory data includes:

• Operating system version
• Installed software
• Hardware details
• Network interfaces
• Running services
• Agent version
• Host information

Regularly reviewing inventory data helps identify outdated software, unsupported operating systems, and systems that may require remediation or upgrades.

Wazuh Agent Deployment Best Practices

A successful Wazuh deployment requires more than simply installing agents and connecting them to the manager.

Long-term reliability depends on how well agents are configured, maintained, monitored, and secured throughout their lifecycle.

Following deployment best practices helps organizations avoid common problems such as disconnected agents, inconsistent configurations, authentication failures, and incomplete security visibility.

Standardize Configurations

Standardized configurations ensure every Wazuh Agent operates consistently across your environment.

Instead of manually configuring each endpoint, define common policies for:

• Log monitoring
• File Integrity Monitoring
• Security Configuration Assessment
• Inventory collection
• Active Response
• Agent communication settings

Standardization reduces configuration drift and makes troubleshooting significantly easier.

For large deployments, use centralized configuration management whenever possible.

Related Guide: How to Configure Wazuh Agent Centralized Configuration

Use Centralized Management

Managing thousands of agents individually is inefficient and increases the risk of configuration errors.

Centralized management allows administrators to:

• Apply policies across multiple endpoints.
• Manage agent groups.
• Push configuration updates.
• Maintain consistent monitoring standards.
• Reduce administrative overhead.

Using agent groups and centralized configurations makes large Wazuh environments easier to scale.

Automate Registration

Manual agent registration works well for small environments but becomes impractical at enterprise scale.

Automation improves deployment efficiency by allowing new endpoints to:

• Register automatically.
• Receive authentication keys.
• Join appropriate groups.
• Begin reporting immediately.

Common automation approaches include:

• Authentication daemon (authd)
• Enrollment passwords
• Infrastructure automation tools
• Cloud-init scripts
• Endpoint management platforms

Related Guide: Step-by-Step Guide to Wazuh Agent Auto-Enrollment

Secure Authentication Keys

Authentication keys provide the identity mechanism between agents and the Wazuh Manager.

Protect these credentials by:

• Restricting access to key files.
• Avoiding key reuse.
• Removing unused registrations.
• Rotating compromised keys.
• Securing deployment scripts containing enrollment information.

Compromised authentication keys could allow unauthorized systems to impersonate legitimate agents.

Related Guide: Why Is client.keys File Empty? Restoring Lost Wazuh Agents

Use Least Privilege

Running every security component with maximum privileges increases risk.

Where possible:

• Avoid unnecessary root access.
• Use Linux capabilities.
• Restrict service permissions.
• Review access requirements regularly.

A least-privilege approach reduces the potential impact if an endpoint or agent process becomes compromised.

Related Guides: How to Configure Wazuh Agent Non Root Privileges on Linux Systems

Monitor Agent Health

Agent deployment does not end after installation.

Continuously monitor:

• Connection status
• Last keepalive timestamps
• Agent versions
• Event activity
• Configuration synchronization
• Inventory updates

Inactive or disconnected agents create monitoring blind spots that attackers may exploit.

Test Before Production

Before deploying agents across an enterprise environment:

1. Deploy to a test group.
2. Validate communication.
3. Confirm log collection.
4. Test detection rules.
5. Review performance impact.
6. Verify configurations.

A staged rollout helps identify problems before they affect critical systems.

Keep Agents Updated

Outdated agents may contain:

• Security vulnerabilities
• Performance issues
• Compatibility problems
• Missing features

Maintain a regular update process that includes:

• Version tracking
• Testing
• Scheduled upgrades
• Rollback procedures

For large environments, rolling upgrades reduce operational risk.

Document Deployment Procedures

Well-documented deployment processes improve reliability and reduce troubleshooting time.

Documentation should include:

• Installation steps
• Registration procedures
• Authentication methods
• Configuration standards
• Required firewall rules
• Upgrade procedures
• Troubleshooting steps
• Ownership responsibilities

Clear documentation also helps new administrators understand how the environment operates.

Frequently Asked Questions (FAQ)

Question: What is a Wazuh Agent?

A Wazuh Agent is lightweight software installed on monitored endpoints that collects security telemetry and sends it securely to the Wazuh Manager.

The agent monitors:

• Operating system events
• Log files
• File changes
• Vulnerabilities
• Security configurations
• Hardware and software inventory

It is the primary component responsible for endpoint visibility in a Wazuh deployment.

Question: How do I deploy Wazuh Agents to hundreds of endpoints?

For large environments, use automated deployment methods instead of manually installing agents.

Common approaches include:

• Ansible
• SCCM
• Microsoft Intune
• Group Policy
• Puppet
• Chef
• SaltStack
• Terraform
• Cloud-init

Automation allows administrators to install, configure, register, and maintain agents consistently.

Related Guide: How to Automate Bulk Wazuh Agent Deployment with Ansible and SCCM

Question: Can I automate Wazuh Agent deployment?

Yes. Wazuh Agent deployment can be fully automated.

Automation workflows can handle:

• Package installation
• Configuration generation
• Agent enrollment
• Group assignment
• Service startup
• Verification

This is the recommended approach for medium and large environments.

Question: What is the difference between ossec.conf and agent.conf?

ossec.conf is the local configuration file stored directly on each agent.

It controls settings such as:

• Manager connection
• Local log monitoring
• Agent modules
• Endpoint-specific settings

agent.conf is managed centrally from the Wazuh Manager and distributes shared configurations to groups of agents.

The main difference is:

• ossec.conf: Local endpoint configuration.
• agent.conf: Centralized configuration management.

Related Guides:

• How to Configure ossec.conf for Log Monitoring in Wazuh
• How to Configure Wazuh Agent Centralized Configuration

Question: How does Wazuh Agent Auto-Enrollment work?

Auto-enrollment allows newly installed agents to automatically register with the Wazuh Manager.

The process typically involves:

1. Agent installation.
2. Enrollment request.
3. Authentication validation.
4. Key generation.
5. Agent registration.
6. Configuration synchronization.

This eliminates manual key management and simplifies large deployments.

Related Guide: Step-by-Step Guide to Wazuh Agent Auto-Enrollment

Question: Can the Wazuh Agent run without root privileges?

Yes, Wazuh Agents can run with reduced privileges in certain Linux environments.

However, available functionality depends on the permissions granted.

Some features may require additional privileges, including:

• Protected file monitoring
• Audit collection
• Active Response actions
• Certain system-level checks

Administrators should carefully test non-root deployments before production use.

Related Guide: How to Configure Wazuh Agent Non Root Privileges on Linux Systems

Question: Why is my Wazuh Agent not connecting to the manager?

Common causes include:

• Incorrect manager address
• Firewall restrictions
• Authentication failures
• Invalid keys
• Service not running
• DNS problems
• Version compatibility issues

Start troubleshooting by checking:

• Agent service status.
• Network connectivity.
• Authentication logs.
• Manager logs.
• Agent registration status.

Related Guide: Wazuh Agent Not Connecting to Manager? 12 Proven Fixes

Question: What should I do if client.keys is empty?

An empty client.keys file usually means the manager has lost its registered agent authentication information.

Possible solutions include:

• Restoring from backup.
• Re-registering agents.
• Regenerating authentication keys.
• Verifying file permissions.

Related Guide: Why Is client.keys File Empty? Restoring Lost Wazuh Agents

Question: How do I update thousands of Wazuh Agents?

Large-scale upgrades should use automated deployment systems.

Recommended approaches include:

• SCCM
• Intune
• Ansible
• Puppet
• Chef
• Automated package repositories

Best practices include:

• Testing upgrades first.
• Performing rolling upgrades.
• Monitoring agent health.
• Maintaining rollback procedures.

Question: Can Wazuh Agents monitor custom log files?

Yes. Wazuh Agents can monitor custom application logs by adding additional log sources to the agent configuration.

Examples include:

• Custom applications
• Database logs
• Security tools
• Web applications
• Proprietary software

Custom monitoring is configured through ossec.conf or centralized configuration.

Related Guide: How to Configure ossec.conf for Log Monitoring in Wazuh

Question: Does Wazuh support Windows, Linux, and macOS?

Yes. Wazuh supports major operating systems including:

• Windows Server
• Windows desktop systems
• Linux distributions
• macOS

This allows organizations to monitor mixed environments from a single security platform.

Related Wazuh Agent Guides

The following guides provide deeper technical instructions for specific Wazuh Agent deployment scenarios, troubleshooting problems, and advanced configurations.

1. Wazuh Agent Installation and Troubleshooting Guides

• How to Unmask and Restart a Blocked Wazuh-Agent Service on Linux
• Fix Wazuh Agent Access Denied Errors on Windows Security Logs
• Troubleshooting Wazuh Silent Install Failures
• Why Is client.keys File Empty? Restoring Lost Wazuh Agents
• Resolving macOS Wazuh Agent Failures: Missing Full Disk Access Fix

2. Wazuh Agent Monitoring Guides

•  How to Monitor Linux Event Logs Using Wazuh
• How to Configure ossec.conf for Log Monitoring in Wazuh
• How to Configure Wazuh Agent Centralized Configuration

3. Wazuh Agent Automation Guides

• How to Automate Bulk Wazuh Agent Deployment with Ansible and SCCM
• Step-by-Step Guide to Wazuh Agent Auto-Enrollment

4. Wazuh Agent Security Guides

•  How to Configure Wazuh Agent Non Root Privileges on Linux Systems

Conclusion

A successful Wazuh Agent Deployment requires more than installing software on endpoints.

Organizations must build a complete lifecycle management process that covers planning, installation, registration, configuration, monitoring, updating, and troubleshooting.

The most effective deployments follow three core principles:

• Secure: Protect authentication keys, limit privileges, and secure communications.
• Automated: Use deployment tools to reduce manual work and improve consistency.
• Centralized: Manage configurations, groups, and policies from the Wazuh Manager.

By implementing standardized deployment procedures, organizations can scale Wazuh across thousands of endpoints while maintaining reliable security visibility.

The supporting guides in this cluster provide deeper implementation details for specific deployment scenarios, troubleshooting challenges, and advanced configurations.

As your environment grows, continue improving your deployment process through automation, documentation, testing, and continuous monitoring.

A well-managed Wazuh Agent deployment becomes a foundation for effective threat detection, compliance monitoring, and incident response.