The client.keys file is one of the most critical files on a Wazuh manager.

It serves as the authentication database that allows Wazuh agents to establish trusted communication with the manager. Every registered agent has an entry in this file containing its unique identity and cryptographic authentication key.

Without it, the manager cannot verify incoming agent connections.

When the Wazuh client.keys file is empty, administrators often discover the problem only after agents begin disconnecting or fail to register altogether.

Existing agents that were previously working may suddenly appear as disconnected in the Wazuh Dashboard, while new agents cannot complete the enrollment process.

Depending on how the file became empty, whether through accidental deletion, corruption, failed upgrades, or cluster synchronization issues, the outage can affect hundreds or even thousands of monitored endpoints.

Common symptoms include:

• Agents showing a Disconnected status.
• Registration attempts failing with authentication errors.
• Empty or nearly empty output when viewing the client.keys file.
• Errors appearing in the Wazuh manager logs during agent enrollment.
• Automatic agent deployment tools suddenly failing.

Fortunately, an empty client.keys file does not always mean every agent must be reinstalled. In many cases, the file can be restored from backups, reconstructed from cluster nodes, or rebuilt through controlled agent re-registration.

In this guide, you’ll learn:

• What the client.keys file does inside Wazuh.
• Why an empty file immediately breaks agent authentication.
• How to diagnose the root cause safely.
• Multiple recovery methods depending on your environment.
• Best practices to prevent this issue from happening again.

Related Guides:

How to Upgrade a Wazuh Agent

 Wazuh Agent Not Connecting to Manager? 12 Proven Fixes

Understanding the Wazuh client.keys File

What Is client.keys?

The client.keys file is the Wazuh manager’s central database of registered agents.

Every endpoint that communicates with the manager must have a corresponding record in this file.

During agent enrollment, the manager generates a unique cryptographic key that is stored both on the manager and on the agent itself.

Whenever an agent connects, the manager compares the incoming authentication information against the entries stored in client.keys.

If a matching entry exists and the authentication key is valid, communication proceeds normally. Otherwise, the connection is rejected.

Without this file, the manager has no trusted record of its agents.

According to the official Wazuh documentation, agent registration relies on the manager maintaining authentication information that uniquely identifies every enrolled endpoint.

Purpose of the File

The client.keys file performs several essential security functions:

• Maintains trusted agent identities
• Stores cryptographic authentication keys
• Prevents unauthorized systems from impersonating agents
• Maps each agent to a unique identifier
• Allows the manager to authenticate incoming connections

Rather than relying solely on IP addresses or hostnames, Wazuh uses shared authentication keys to ensure secure communication between the manager and every monitored endpoint.

Stores Agent IDs, Names, IPs, and Authentication Keys

Each registered agent has a single entry that includes:

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

Together, these fields uniquely identify an endpoint within the Wazuh deployment.

Used by the Wazuh Manager During Agent Authentication

Every time an agent connects:

1. The agent sends its identity.
2. The manager searches client.keys.
3. The authentication key is verified.
4. Secure communication begins.

If the manager cannot locate a matching record, or if the file is empty, the authentication process immediately fails.

This design follows a shared-key authentication model that prevents unauthorized devices from joining the deployment.

Where Is client.keys Located?

The exact location depends on how Wazuh is deployed.

Default Linux Installation Path

For standard installations, the file is typically located at:

/var/ossec/etc/client.keys

This is where most administrators will find the authentication database.

Docker Deployments

In Docker environments, the file resides inside the Wazuh Manager container.

If persistent storage (volumes or bind mounts) is configured correctly, the file survives container restarts. Otherwise, recreating containers without persistent storage may result in losing the file.

Related Guide: Fix Wazuh Docker Compose Deployment

Cluster Deployments

In clustered environments, the master node maintains the authoritative version of client.keys.

Worker nodes receive synchronized copies from the master. If synchronization fails or the master loses its copy, authentication problems may spread throughout the cluster.

Cluster synchronization should always be verified before manually editing the file.

Related Guide: How to Build a Wazuh Indexer Cluster

Permission Requirements

Because client.keys contains sensitive authentication credentials, it should only be readable by the Wazuh service account and privileged administrators.

Typical ownership:

root:wazuh

Typical permissions:

640

Incorrect permissions may prevent the Wazuh manager from reading the file during startup.

The Wazuh documentation recommends protecting authentication materials and configuration files with appropriate filesystem permissions.

What Information Does client.keys Contain?

Each line in the file represents one registered Wazuh agent.

Agent ID

Every agent receives a unique numeric identifier.

Example:

001

The manager uses this value internally to distinguish one endpoint from another.

Agent Name

The hostname or assigned agent name appears next.

Example:

webserver01

This is typically what appears in the Wazuh Dashboard.

IP Address

The third field specifies the permitted source IP.

It may contain:

192.168.1.15

or

any

Using any allows the agent to authenticate regardless of its IP address, which is common for laptops, cloud instances, and DHCP environments.

Shared Authentication Key

The final field contains a long cryptographic authentication key generated during enrollment.

Example:

7f8e9c3e3ad8d91...

This key is the most important component of the record. If the manager’s copy and the agent’s copy do not match, authentication fails.

Example Entry Explained

A typical entry looks like:

001 webserver01 any d1e65b91f2f35c7f0cf8d66c...

Breaking it down:

Every registered endpoint has exactly one corresponding record.

Security experts consistently recommend treating shared authentication keys as sensitive credentials because anyone possessing both the identity information and matching key could potentially impersonate an agent if additional security controls are absent.

What Happens When client.keys Is Empty?

An empty client.keys file effectively removes the manager’s knowledge of every registered agent.

Although agents continue attempting to connect, the manager has no authentication records available to verify them.

The result is widespread authentication failures across the deployment.

Existing Agents Cannot Authenticate

Previously enrolled agents still possess their local authentication keys.

However, the manager no longer has matching records.

When agents attempt to reconnect:

• Authentication fails.
• Secure communication is rejected.
• The manager treats the agents as unknown devices.

No alerts or inventory updates are received until authentication is restored.

New Agents Cannot Register

New agent enrollment also depends on updating the client.keys file.

If the file is empty because of corruption or another underlying issue, registration processes may fail before new entries can be written.

Administrators often observe:

• Enrollment timeouts
• Registration failures
• Duplicate agent errors
• Authentication rejected messages

Related Guides:

• Fix Authd Registration Failures: Wazuh Agent Password Mismatched Guide
• Resolving Duplicate Name or IP Errors in Wazuh Agent Registration

Agents Appear as Disconnected

One of the first visible symptoms is a rapidly growing list of disconnected agents in the Wazuh Dashboard.

Agents continue attempting communication, but because authentication never succeeds:

• Heartbeats stop updating.
• Last-seen timestamps become stale.
• Dashboards report disconnected endpoints.
• Monitoring coverage decreases dramatically.

This symptom is frequently mistaken for networking problems when the actual issue is missing authentication records.

Authentication Errors in Manager Logs

The Wazuh manager logs usually provide the earliest indication that authentication is failing.

Administrators may encounter messages indicating:

• Invalid authentication keys
• Unknown agent IDs
• Authentication rejected
• Agent registration failures

Reviewing the manager logs should be one of the first troubleshooting steps before attempting recovery.

The official Wazuh documentation recommends examining manager logs whenever enrollment or authentication issues occur.

Automatic Enrollment Stops Working

Organizations using automated provisioning tools such as configuration management systems, cloud-init scripts, or golden VM images often rely on unattended Wazuh enrollment.

If client.keys is empty:

• New servers cannot enroll automatically.
• Auto-scaling groups produce unmanaged instances.
• Cloud workloads launch without security monitoring.
• Compliance coverage can quickly degrade.

For large enterprise environments, this issue can silently leave newly deployed systems unmonitored until the authentication database is restored.

Common Reasons the client.keys File Becomes Empty

An empty client.keys file is almost never a normal operating condition.

In most cases, it results from human error, storage problems, failed maintenance, or deployment mistakes.

Identifying the root cause is just as important as restoring the file because the same issue can happen again if the underlying problem isn’t addressed.

Below are the most common reasons administrators discover an empty client.keys file.

Accidental File Deletion

The most common cause is simple human error.

Administrators performing maintenance may accidentally delete or truncate the file while cleaning directories, removing old configurations, or executing shell commands.

Examples include:

rm /var/ossec/etc/client.keys

or even more dangerous:

> /var/ossec/etc/client.keys

The second command leaves the file intact but empties all of its contents.

This often happens during troubleshooting sessions when administrators mistake client.keys for a temporary file.

File Overwritten During Manual Editing

Some administrators manually edit client.keys when troubleshooting registration problems or removing duplicate agents.

Using text editors incorrectly can unintentionally overwrite the entire file.

Examples include:

• Saving an empty buffer
• Using shell redirection incorrectly
• Copying incomplete content
• Editing the wrong file in multiple terminal sessions

Since every registered agent is stored in a single file, even one mistaken save operation can remove every registered endpoint.

Whenever possible, use Wazuh’s agent management tools instead of manually modifying client.keys.

Related Guide: Resolving Duplicate Name or IP Errors in Wazuh Agent Registration

Failed Backup Restoration

Restoring from backups can sometimes introduce the problem instead of fixing it.

Examples include:

• Restoring the wrong backup
• Restoring an incomplete backup
• Backup software excluding the file
• Partial filesystem restores
• Interrupted restore operations

Administrators often assume a restore completed successfully without verifying that client.keys actually contains agent entries afterward.

Always inspect the restored file before restarting the manager.

Disk Corruption or Filesystem Errors

Storage failures can damage or truncate critical files.

Potential causes include:

• Sudden power loss
• Filesystem corruption
• SSD failures
• RAID controller problems
• Unexpected kernel crashes

If filesystem corruption occurs, client.keys may become:

• Empty
• Partially truncated
• Contain corrupted data
• Become unreadable

Linux system logs frequently provide early warning signs of underlying storage problems.

The Linux kernel documentation recommends investigating filesystem errors immediately because repeated corruption usually indicates hardware or storage issues rather than application bugs.

Permission or Ownership Problems

Sometimes the file isn’t actually empty, it simply cannot be read.

Incorrect ownership or permissions can prevent the Wazuh manager from accessing it.

Common problems include:

• Incorrect owner
• Wrong group
• Permissions set too restrictively
• SELinux or AppArmor restrictions

For example:

---------- client.keys

or

600 owned by the wrong user

may prevent successful access.

Always verify both the contents and the permissions before assuming the file has been lost.

Incorrect Automation Scripts

Automation is excellent for consistency but can also multiply mistakes.

Poorly written deployment scripts may accidentally:

• Replace the file with a blank template
• Copy an empty version
• Remove agent registrations
• Reset configuration during upgrades

Examples include:

cp empty_client.keys /var/ossec/etc/client.keys

or

echo "" > client.keys

A single automation bug can affect hundreds of Wazuh managers simultaneously.

Configuration Management Mistakes (Ansible, Puppet, Chef, etc.)

Infrastructure-as-Code tools can unintentionally overwrite authentication databases if they are configured incorrectly.

Common mistakes include:

• Treating client.keys as a managed configuration file
• Deploying a blank template
• Synchronizing an outdated version
• Enforcing an empty state across all servers

Configuration management systems should generally avoid managing dynamically generated authentication files.

Instead, these files should be backed up and preserved separately.

Container or Volume Misconfiguration

Containerized Wazuh deployments frequently encounter this problem when persistent storage is not configured properly.

Typical scenarios include:

• Container recreated without persistent volumes
• Volume mounted incorrectly
• Wrong bind mount path
• Persistent volume accidentally deleted

When the container starts, it creates a fresh installation that contains an empty client.keys file.

This is one of the most common causes in Docker-based deployments.

Related Guide: Fix Wazuh Docker Compose Deployment

Cluster Synchronization Issues

In clustered environments, the master node maintains the authoritative copy of client.keys.

Problems may occur if:

• Synchronization fails
• The master becomes corrupted
• Workers receive incomplete updates
• Network interruptions occur during synchronization

If synchronization propagates an empty file, multiple managers can lose authentication data simultaneously.

Always determine which cluster node still has a valid copy before attempting recovery.

Manager Reinstallation Without Restoring Agent Keys

A fresh Wazuh manager installation creates a new environment.

If administrators reinstall the manager but forget to restore client.keys, every previously enrolled agent becomes unknown.

Although agents still possess their authentication keys locally, the manager has no corresponding records.

This situation commonly occurs during:

• Operating system rebuilds
• Disaster recovery
• Migration to new hardware
• Cloud instance replacement

Before reinstalling a manager, always back up:

• client.keys
• Configuration files
• Custom rules
• Custom decoders
• SSL certificates

Related Guide: How to Upgrade a Wazuh Agent

How to Verify That client.keys Is Empty

Before attempting recovery, confirm that the client.keys file is actually empty.

Authentication failures can also be caused by permission problems, corruption, or configuration issues that merely appear similar.

A systematic verification process helps avoid unnecessary re-registration of agents.

Check the File Contents

The quickest verification method is viewing the file directly.

cat /var/ossec/etc/client.keys

or

less /var/ossec/etc/client.keys

A healthy file should contain one line for every registered agent.

If the command produces no output, the file is empty.

If only a handful of entries appear when hundreds are expected, the file may have been partially overwritten.

Verify File Size

Checking the file size provides another quick indicator.

ls -lh /var/ossec/etc/client.keys

Example:

-rw-r----- 1 root wazuh 0 Jul 5 14:18 client.keys

A file size of 0 bytes confirms that all contents have been removed.

For additional verification:

stat /var/ossec/etc/client.keys

This also displays modification timestamps, which can help identify when the file became empty.

Confirm File Permissions

Verify ownership and permissions.

ls -l /var/ossec/etc/client.keys

Typical output resembles:

-rw-r----- 1 root wazuh

If permissions appear incorrect, the manager may simply be unable to read the file rather than the file actually being empty.

Correct permissions also help protect authentication keys from unauthorized access.

Compare Against Previous Backups

If backups are available, compare the current file against an earlier version.

Useful commands include:

diff client.keys backup/client.keys

or

wc -l client.keys

Comparing line counts immediately shows whether agent registrations have disappeared.

A backup containing hundreds of entries while the live file contains none clearly indicates data loss.

Verify Manager Logs

The Wazuh manager usually records authentication failures shortly after the file becomes empty.

The official Wazuh documentation recommends reviewing manager logs when troubleshooting agent registration and authentication issues.

Useful logs include:

/var/ossec/logs/ossec.log

This is the primary log for manager activity.

Look for messages involving:

• Authentication failures
• Unknown agents
• Registration errors
• Invalid keys
• Enrollment problems

Example:

grep -i "agent" /var/ossec/logs/ossec.log

System Logs

System logs may reveal the root cause if storage, permissions, or services failed.

Useful locations include:

/var/log/syslog

or

/var/log/messages

Review entries around the time the client.keys file was modified.

Authentication-Related Messages

Search specifically for authentication failures.

For example:

grep -Ei "auth|key|client.keys|agent" /var/ossec/logs/ossec.log

Repeated authentication failures across many agents strongly suggest the manager has lost access to its authentication database rather than multiple simultaneous network issues.

How to Restore the client.keys File

The appropriate recovery method depends on whether a usable copy of client.keys still exists.

If backups or snapshots are available, restoration is typically straightforward.

If no copy remains, the authentication database must be rebuilt by re-registering agents.

Always create a backup of the current state, even if the file is empty, before making changes.

Method 1: Restore From a Backup

Restoring from a verified backup is the fastest and least disruptive recovery method because agents retain their original authentication keys.

Locate the Latest Backup

Search for recent backups of the file.

Common locations include:

• Backup servers
• Snapshot repositories
• Disaster recovery storage
• Manual configuration backups

Verify that the backup contains the expected number of agent entries before restoring it.

Restore Permissions

Copy the backup into place:

cp client.keys.backup /var/ossec/etc/client.keys

Restore ownership:

chown root:wazuh /var/ossec/etc/client.keys

Restore permissions:

chmod 640 /var/ossec/etc/client.keys

Incorrect permissions may prevent the manager from loading the restored file.

Restart the Manager

Reload the authentication database by restarting the manager:

systemctl restart wazuh-manager

Confirm the service starts successfully:

systemctl status wazuh-manager

Verify Agent Connectivity

After the restart:

• Check connected agents in the dashboard.
• Confirm agents begin checking in.
• Review ossec.log for successful authentication messages.
• Verify that alerts resume normally.

If connectivity returns without re-registering agents, the restoration was successful.

Method 2: Recover Using Version Control or Snapshots

If traditional backups are unavailable, infrastructure snapshots may still contain a valid copy of client.keys.

Possible recovery sources include:

Filesystem Snapshots

Filesystems such as ZFS, Btrfs, and LVM snapshots can preserve earlier versions of configuration files.

Mount the snapshot and compare its client.keys file before restoring it.

VM Snapshots

Hypervisor snapshots (VMware, Hyper-V, Proxmox, KVM, etc.) often contain a complete copy of the Wazuh manager filesystem.

Rather than reverting the entire VM, extract only the required file whenever possible.

Backup Software

Enterprise backup platforms frequently allow individual file recovery.

Examples include:

• Veeam
• Commvault
• Rubrik
• Bacula

Restoring a single file minimizes downtime and avoids reverting unrelated system changes.

Method 3: Rebuild client.keys by Re-registering Agents

If no valid copy of client.keys exists, the only reliable recovery option is to rebuild it by enrolling agents again.

Although this process can be time-consuming in large environments, it generates fresh authentication keys and restores secure communication.

When Rebuilding Is Necessary

Re-registration is required when:

• No usable backup exists.
• All snapshots are unavailable or corrupted.
• The file has been permanently lost.
• Authentication keys cannot be recovered.

Remove Stale Entries

Before enrolling agents again, remove any obsolete or partially recreated entries to avoid duplicate registration conflicts.

If necessary, clean the manager’s agent database using the appropriate Wazuh management tools rather than manually editing client.keys.

Related Guide: Resolving Duplicate Name or IP Errors in Wazuh Agent Registration

Generate New Authentication Keys

Each agent receives a newly generated shared authentication key during registration.

These keys replace the old trust relationship and populate a new client.keys file automatically.

The Wazuh documentation recommends using the built-in agent enrollment mechanisms instead of manually generating or copying authentication keys.

Register Agents Again

Re-enroll each endpoint using your preferred registration method:

• agent-auth
• Enrollment password
• Centralized deployment tools
• Automated provisioning workflows

Large environments should automate this process to reduce manual effort and minimize downtime.

Related Guides:

• How to Install a Wazuh Agent on Windows Server
• How to Add Linux Endpoints to Wazuh

Restart Services

After enrollment is complete:

1. Restart the Wazuh manager if necessary.
2. Restart agents that do not reconnect automatically.
3. Verify successful authentication in the dashboard.
4. Confirm that alerts and heartbeats are flowing normally.

Once all agents have checked in successfully, the rebuilt client.keys file once again serves as the authoritative authentication database for your Wazuh deployment.

Restoring Individual Agents

If only a handful of agents are affected, or if you’re rebuilding the authentication database after losing client.keys, you can restore connectivity by re-registering individual endpoints.

Wazuh provides several enrollment methods that accommodate everything from a single server to thousands of managed devices.

Choose the approach that best fits your environment and deployment scale.

Using manage_agents

manage_agents is the traditional command-line utility for managing agent registrations directly on the Wazuh manager.

It allows administrators to:

• Add new agents
• Remove existing agents
• List registered agents
• Export authentication keys
• Import agent keys

Start the utility with:

/var/ossec/bin/manage_agents

Follow the interactive prompts to create a new agent entry.

After the agent is added, export the generated authentication key and import it on the endpoint if you’re using manual enrollment.

This method is well suited for:

• Small environments
• Testing
• Recovering a few individual agents
• Troubleshooting registration issues

The official Wazuh documentation describes manage_agents as one of the supported methods for manually managing agent registrations.

Using agent-auth

agent-auth automates the exchange of authentication keys between an agent and the Wazuh manager.

Instead of manually copying keys, the agent securely requests registration from the manager.

A typical command looks like:

/var/ossec/bin/agent-auth -m <MANAGER_IP>

After successful enrollment:

• A new entry is added to client.keys.
• The agent stores its authentication key locally.
• Secure communication begins immediately after the agent service starts.

agent-auth is typically the preferred method for restoring individual Linux agents because it minimizes manual work.

If enrollment fails, verify:

• Manager connectivity
• Registration service availability
• Firewall rules
• Enrollment passwords (if configured)

Related Guide: Fix Authd Registration Failures: Wazuh Agent Password Mismatched Guide

Using Automated Enrollment

Many organizations automate Wazuh enrollment during server provisioning.

Examples include:

• Cloud-init
• Terraform
• Ansible
• Puppet
• Chef
• Microsoft Endpoint Configuration Manager (SCCM)
• Golden VM images

If client.keys has been restored successfully, newly deployed systems should begin registering automatically again.

If automatic enrollment continues to fail:

• Verify enrollment credentials.
• Confirm the registration service is running.
• Check automation logs.
• Test enrollment manually before redeploying automation.

Infrastructure automation should always include validation steps to ensure agents successfully appear in the Wazuh manager after deployment.

Registering Hundreds of Agents Efficiently

Large environments should avoid manually registering every endpoint.

Instead, use centralized deployment mechanisms such as:

• Configuration management tools
• Automated provisioning pipelines
• Remote management platforms
• Bulk deployment scripts

A recommended workflow is:

1. Restore or rebuild the manager.
2. Enable the registration service.
3. Redeploy enrollment automation.
4. Allow agents to register automatically.
5. Monitor registration progress in the dashboard.
6. Investigate only the endpoints that fail to reconnect.

This approach significantly reduces recovery time compared to manually processing every endpoint.

Verifying Successful Recovery

Restoring the client.keys file is only the first step.

You should verify that agents are authenticating successfully, sending events, and appearing correctly in the Wazuh Dashboard before considering the recovery complete.

Perform the following validation checks.

Check Agent Status

Begin by reviewing the list of registered agents in the Wazuh Dashboard.

Healthy agents should display a status of:

• Active
• Connected
• Recently checked in

The number of connected agents should closely match your expected inventory.

If a large percentage of agents remain disconnected, further troubleshooting is required.

Confirm Authentication Success

Successful authentication should occur without repeated registration attempts or authentication failures.

You can also verify that the manager recognizes registered agents using the Wazuh management tools.

Healthy authentication typically results in:

• Stable agent IDs
• Successful heartbeat updates
• No repeated enrollment attempts
• No authentication errors in logs

Agents should establish trust only once rather than continuously requesting new authentication keys.

Review Manager Logs

The manager logs provide the clearest confirmation that authentication is functioning correctly.

Review:

/var/ossec/logs/ossec.log

Look for indications that:

• Agents authenticated successfully.
• Connections remain stable.
• No invalid key errors appear.
• Registration completed without failures.

Conversely, repeated authentication failures after restoring client.keys suggest that the manager and agent are using different shared keys.

The official Wazuh documentation recommends checking manager logs whenever authentication or enrollment issues are suspected.

Verify Security Events Are Arriving

Successful authentication alone does not guarantee that monitoring has resumed.

Confirm that agents are actively sending:

• System logs
• Security events
• File Integrity Monitoring (FIM) alerts
• Vulnerability detection results
• Syslog events (if applicable)

Generate a simple test event on a monitored endpoint and verify that it appears in the Wazuh Dashboard.

If authentication succeeds but no events arrive, the issue may involve log collection rather than agent registration.

Validate Agent Inventory

Finally, compare the current list of registered agents against your expected inventory.

Verify that:

• Every server appears only once.
• Hostnames are correct.
• Agent IDs are unique.
• No duplicate registrations exist.
• No critical systems are missing.

Maintaining an accurate inventory helps ensure that no endpoints were overlooked during the recovery process.

Troubleshooting Restoration Problems

Even after restoring client.keys, some agents may still fail to reconnect.

In these situations, additional issues beyond the authentication database are preventing successful communication.

The following problems are among the most common.

Agents Still Show Disconnected

If agents remain disconnected after restoring client.keys, verify the basics first.

Check:

• Network connectivity
• DNS resolution
• Firewall rules
• Manager availability
• Agent service status

Also confirm that the restored client.keys file actually contains entries for the affected agents.

If an agent’s entry is missing, it must be re-registered.

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

Duplicate Agent IDs

Restoring an outdated backup while newer agents already exist can create duplicate IDs or conflicting registrations.

Symptoms include:

• Registration failures
• Duplicate hostname errors
• Agents replacing one another
• Unexpected inventory changes

Remove obsolete registrations before attempting to enroll the affected agents again.

Related Guide: Resolving Duplicate Name or IP Errors in Wazuh Agent Registration

Invalid Authentication Keys

A restored client.keys file may not match the keys currently stored on agents.

This commonly occurs when:

• Agents were reinstalled.
• The manager was restored from an old backup.
• Partial backups were used.
• Authentication keys changed after the backup was created.

When the manager and agent use different shared keys, re-registration is required to establish a new trust relationship.

Manager Rejects Agent Connections

If the manager refuses connection requests entirely, verify:

• The manager service is running.
• The enrollment service is enabled (if using automatic registration).
• Firewall ports are open.
• SSL/TLS configuration is correct.
• Authentication settings have not changed.

Review ossec.log for the exact rejection reason before making configuration changes.

File Permissions Keep Resetting

If ownership or permissions repeatedly change after being corrected, another process is likely modifying the file.

Possible causes include:

• Configuration management software
• Automation scripts
• Startup scripts
• Container initialization processes
• Security hardening policies

Determine which process owns the file before manually correcting permissions again.

Related Guide: Fix Wazuh Docker Compose Deployment

Cluster Nodes Have Different client.keys Files

In clustered deployments, every node should ultimately use the synchronized copy maintained by the cluster.

If nodes contain different versions of client.keys:

• Verify cluster synchronization.
• Identify the authoritative node.
• Resolve synchronization failures.
• Allow replication to complete before registering additional agents.

Manually editing different copies on multiple nodes can make synchronization conflicts even more difficult to resolve.

Agents Continuously Re-register

An agent should enroll only once.

Repeated registration attempts often indicate:

• Authentication keys do not match.
• Agent configuration is incorrect.
• Local authentication files were deleted.
• Automated provisioning scripts are forcing repeated enrollment.

Review both the agent logs and manager logs to determine why the trust relationship is not being preserved across reconnects.

Authentication Works but No Events Arrive

Successful authentication confirms only that the agent can connect to the manager, it does not guarantee that telemetry is being collected.

If agents appear connected but dashboards remain empty, investigate:

• Logcollector configuration
• File permissions
• Event log subscriptions
• File Integrity Monitoring configurationLog forwarding settings
• Custom decoder or rule issues

Generate a known security event and verify whether it reaches the manager.

If authentication succeeds but event collection fails, focus your troubleshooting on data collection rather than enrollment.

Related Guides:

• Fix Wazuh Logcollector Dropped Messages
• How to Configure File Integrity Monitoring (FIM) in Wazuh
• How to Monitor Linux Event Logs Using Wazuh
• How to Monitor Windows Event Logs Using Wazuh

Preventing Future client.keys Data Loss

Losing the client.keys file can disrupt monitoring across your entire Wazuh deployment.

Fortunately, most incidents are preventable with proper operational practices.

By combining regular backups, secure configuration management, and proactive monitoring, you can greatly reduce the likelihood of future authentication failures.

The following recommendations are considered best practices for maintaining a reliable Wazuh environment.

Schedule Regular Backups

The simplest way to recover from a lost client.keys file is to have a recent backup.

Your backup strategy should include:

• client.keys
• ossec.conf
• Custom rules
• Custom decoders
• SSL/TLS certificates
• Other critical Wazuh configuration files

Automate backups and verify them regularly instead of relying on manual copies.

Whenever possible:

• Store multiple backup versions.
• Encrypt backup archives.
• Keep copies in separate physical or cloud locations.
• Periodically test restoration procedures.

Following the widely adopted 3-2-1 backup strategy, three copies of data, stored on two different media types, with one copy kept offsite, helps protect against accidental deletion, hardware failure, and ransomware.

Protect the File with Proper Permissions

Because client.keys contains authentication credentials for every enrolled agent, it should be accessible only to authorized users and the Wazuh manager.

Recommended practices include:

• Restrict write access.
• Verify file ownership regularly.
• Limit administrator access.
• Audit permission changes.
• Protect backups with the same security controls.

Proper permissions reduce the risk of accidental modification as well as unauthorized access.

Use Configuration Management Carefully

Infrastructure-as-Code tools are extremely useful but should not blindly overwrite dynamically generated files like client.keys.

When using tools such as:

• Ansible
• Puppet
• Chef
• SaltStack

avoid treating client.keys as a static configuration file.

Instead:

• Exclude it from template deployment.
• Back it up separately.
• Validate playbooks before production deployment.
• Test configuration changes in a staging environment first.

Poorly designed automation can erase every registered agent within seconds.

Enable Filesystem Snapshots

Filesystem snapshots provide a fast recovery mechanism when files are accidentally modified or deleted.

Common snapshot technologies include:

• ZFS snapshots
• Btrfs snapshots
• LVM snapshots
• Cloud volume snapshots

Snapshots allow administrators to recover individual files without restoring an entire server.

For frequently changing systems, scheduled snapshots can significantly reduce recovery time.

Document Agent Enrollment Procedures

Recovery is much easier when enrollment procedures are documented.

Your documentation should include:

• Standard registration methods
• Enrollment passwords (if used)
• Automation workflows
• Recovery procedures
• Manager configuration
• Required firewall ports

Well-documented procedures allow teams to rebuild authentication quickly during emergencies.

Monitor File Integrity with Wazuh FIM

One of the best ways to detect unexpected changes to client.keys is by monitoring it with Wazuh’s File Integrity Monitoring (FIM).

Configure FIM to watch:

/var/ossec/etc/client.keys

This allows Wazuh to generate alerts whenever the file is:

• Modified
• Deleted
• Replaced
• Renamed
• Had its permissions changed

Early detection can significantly reduce downtime by allowing administrators to respond before widespread authentication failures occur.

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

Test Disaster Recovery Procedures

Backups are only valuable if they can actually be restored.

Schedule regular disaster recovery exercises that verify you can:

• Restore client.keys
• Restart the Wazuh manager
• Authenticate existing agents
• Recover monitoring functionality
• Validate agent connectivity

Organizations that routinely test disaster recovery generally experience significantly shorter recovery times during real incidents.

The National Institute of Standards and Technology (NIST) recommends regularly testing contingency and recovery plans rather than assuming backups will work when needed.

Best Practices for Managing client.keys

Proper day-to-day management of client.keys reduces both operational risk and recovery time.

These best practices help ensure that agent authentication remains reliable as your Wazuh deployment grows.

Avoid Manual Editing Whenever Possible

Although client.keys is a plain text file, manually editing it is generally discouraged.

Instead, use Wazuh’s built-in management tools to:

• Register agents
• Remove obsolete agents
• Generate authentication keys
• Manage agent identities

Manual editing increases the likelihood of:

• Syntax errors
• Duplicate IDs
• Missing authentication keys
• Accidental file truncation

Using supported management tools helps preserve file integrity.

Keep Secure Offsite Backups

Maintain multiple backup copies stored outside the primary server.

Examples include:

• Secure cloud storage
• Backup servers
• Encrypted external media
• Enterprise backup platforms

Offsite backups protect against:

• Hardware failures
• Ransomware
• Natural disasters
• Complete server loss

Ensure backup access is limited to authorized administrators because the file contains sensitive authentication credentials.

Maintain Consistent Agent Naming

Consistent naming conventions simplify administration and recovery.

For example, use descriptive names that identify:

• Environment
• Operating system
• Server role
• Geographic location

Examples:

• prod-web-01
• dc2-db-05
• aws-app-12

Consistent naming makes duplicate detection and inventory validation much easier during recovery operations.

Remove Retired Agents Regularly

Old agent registrations increase clutter and may create confusion during troubleshooting.

Establish a process for removing:

• Decommissioned servers
• Replaced virtual machines
• Obsolete workstations
• Temporary testing systems

Keeping the authentication database clean makes it easier to identify legitimate agents.

Secure Authentication Keys

The authentication keys stored in client.keys establish trust between agents and the manager.

Treat them as sensitive credentials by:

• Restricting access.
• Encrypting backups.
• Avoiding insecure file transfers.
• Rotating credentials when appropriate.
• Limiting administrative privileges.

Protecting authentication material helps prevent unauthorized systems from attempting to impersonate legitimate agents.

Verify Changes Before Restarting Services

Before restarting the Wazuh manager after modifying authentication-related files:

• Validate file permissions.
• Confirm ownership.
• Verify syntax if applicable.
• Check file size.
• Ensure expected agent entries exist.
• Create a backup of the current state.

A quick validation can prevent unnecessary downtime caused by accidental configuration mistakes.

Frequently Asked Questions (FAQ)

Question: Why is my Wazuh client.keys file empty?

The most common causes include accidental deletion, incorrect manual editing, failed backup restoration, storage corruption, configuration management errors, container volume misconfiguration, and reinstalling the Wazuh manager without restoring authentication data.

Identifying the root cause is important to prevent the issue from recurring.

Question: Can I recreate client.keys without a backup?

Yes, but not by recovering the original authentication keys.

If no backup or snapshot exists, you’ll need to rebuild the file by re-registering each agent.

During this process, Wazuh generates new shared authentication keys and creates new entries in client.keys.

Question: Will reinstalling the Wazuh manager restore client.keys?

No.

A fresh Wazuh installation creates a new environment and does not restore previously registered agents. Unless you restore a backup of client.keys, existing agents will no longer authenticate successfully and must be re-registered.

Question: Can disconnected agents reconnect automatically after restoring client.keys?

Yes, provided that:

• The restored file contains the correct agent entries.
• Authentication keys still match those stored on the agents.
• Network connectivity is working.
• The manager is running normally.

In many environments, agents reconnect automatically within a few minutes after the manager resumes normal operation.

Question: Is it safe to manually edit the client.keys file?

Manual editing is generally discouraged.

Because the file contains authentication records for every registered agent, even small mistakes can prevent agents from connecting or introduce duplicate registrations.

Whenever possible, use Wazuh’s supported agent management tools instead.

Question: How do I back up the client.keys file correctly?

A proper backup should:

• Preserve file ownership and permissions.
• Be stored securely.
• Be encrypted if possible.
• Be included in automated backup jobs.
• Be tested periodically through restoration exercises.

It’s also recommended to back up related configuration files such as ossec.conf, custom rules, custom decoders, and certificates at the same time.

Question: Can two agents share the same authentication key?

No.

Each registered Wazuh agent should have its own unique authentication key. Sharing keys between multiple agents can lead to authentication conflicts, identity problems, and security risks.

The official Wazuh enrollment process generates unique credentials for every registered endpoint.

Question: Does Wazuh regenerate client.keys automatically if it is deleted?

No.

Wazuh may recreate an empty client.keys file during installation or startup if the file is missing, but it does not automatically regenerate lost agent registrations or authentication keys.

The file must be restored from a backup or rebuilt by re-registering agents.

Conclusion

The client.keys file is the foundation of Wazuh’s agent authentication system.

Every enrolled endpoint depends on the entries in this file to establish a trusted connection with the Wazuh manager.

When the file becomes empty, existing agents lose their ability to authenticate, new agents cannot register, and monitoring coverage can quickly deteriorate.

As you’ve seen throughout this guide, an empty client.keys file is most commonly caused by accidental deletion, improper manual editing, failed backup restorations, storage issues, container volume misconfigurations, cluster synchronization problems, or reinstalling a Wazuh manager without restoring its authentication database.

Recovery depends on the resources available.

The fastest approach is restoring a recent backup of client.keys, while filesystem or virtual machine snapshots can provide alternative recovery options.

If no usable copy exists, rebuilding the file by re-registering agents is the only reliable solution for restoring secure communication.

To minimize the risk of future outages, adopt strong operational practices such as maintaining verified backups, protecting the file with appropriate permissions, using configuration management carefully, monitoring it with Wazuh File Integrity Monitoring (FIM), and regularly testing your disaster recovery procedures.

These proactive measures help ensure that agent authentication remains reliable and that your Wazuh deployment can recover quickly from unexpected failures.