How To Install Wazuh on Debian 12

Wazuh stands as one of the most powerful open-source Security Information and Event Management (SIEM) platforms available today. This comprehensive security monitoring solution provides unified XDR and SIEM protection for endpoints and cloud workloads, making it an essential tool for organizations seeking robust cybersecurity infrastructure. Installing Wazuh on Debian 12 offers excellent stability and performance, as Debian’s reputation for reliability makes it an ideal host for critical security systems.

The platform delivers real-time threat detection, compliance monitoring, and incident response capabilities through its sophisticated architecture. Whether you’re managing a small business network or enterprise infrastructure, Wazuh provides scalable security monitoring that adapts to your needs. This guide will walk you through every step of installing Wazuh on Debian 12, from basic setup to advanced configuration options.

Understanding Wazuh Architecture and Components

Before diving into installation procedures, understanding Wazuh’s architecture ensures successful deployment and optimal performance. The platform consists of three primary central components that work together seamlessly.

Wazuh Manager serves as the central brain of the system, collecting and analyzing data from deployed Wazuh agents across your network. This component triggers alerts when threats or anomalies are detected, making it the core of your security monitoring infrastructure. The manager processes incoming data, applies rules and decoders, and generates actionable security intelligence.

Wazuh Indexer handles data storage and provides powerful search functionality for your security events. Built on OpenSearch technology, it ensures your security data remains accessible and searchable for forensic analysis and compliance reporting. The indexer scales horizontally to accommodate growing data volumes.

Wazuh Dashboard offers an intuitive web-based interface for visualizing security data, managing configurations, and monitoring system health. Through this dashboard, security teams can investigate incidents, generate reports, and maintain comprehensive oversight of their security posture.

Wazuh Agents represent lightweight monitoring software deployed across endpoints, including laptops, desktops, servers, cloud instances, and containers. These agents collect critical system and application records, inventory data, and detect anomalies at the endpoint level.

Filebeat acts as the log forwarding component, securely transmitting alerts and archived events from the Wazuh manager to the Wazuh indexer. This ensures reliable data flow throughout the architecture.

Prerequisites and System Requirements

Proper preparation ensures smooth Wazuh installation on your Debian 12 system. Meeting these requirements prevents common installation issues and optimizes performance.

Hardware Requirements vary depending on your deployment size. For small environments monitoring up to 100 agents, allocate at least 4 CPU cores, 8GB RAM, and 50GB storage. Medium deployments supporting 500 agents require 8 CPU cores, 16GB RAM, and 100GB storage. Large-scale implementations monitoring thousands of agents need 16+ CPU cores, 32GB+ RAM, and 500GB+ storage.

Operating System Preparation begins with ensuring your Debian 12 system is fully updated. Run the following commands to prepare your environment:

apt update && apt upgrade -y
apt install curl gnupg apt-transport-https -y

Network Configuration requires opening specific ports for proper communication. Wazuh manager listens on port 1514/tcp for agent communication, while the dashboard operates on port 443/tcp. Ensure your firewall allows these connections.

Root Privileges are essential for installation and configuration tasks. All installation commands require root access, so ensure you have appropriate permissions before beginning the process.

Installation Method 1: All-in-One Quick Installation

The all-in-one installation method provides the fastest way to get Wazuh running on your Debian 12 system. This approach installs all central components on a single host, making it perfect for testing environments or small deployments.

Download the Installation Script from the official Wazuh repository:

curl -sO https://packages.wazuh.com/4.9/wazuh-install.sh

Execute the All-in-One Installation with the following command:

sudo bash ./wazuh-install.sh -a

The installation script automatically handles all dependencies, configurations, and service initialization. During installation, you’ll see progress indicators showing the setup of each component. The process typically takes 10-15 minutes depending on your system specifications and internet connection speed.

Retrieve Access Credentials from the installation output. The script generates random passwords for the admin user and displays them at completion. Copy these credentials immediately and store them securely in your password manager.

Verify Installation Success by checking service status:

systemctl status wazuh-manager
systemctl status wazuh-indexer
systemctl status wazuh-dashboard

All services should show “active (running)” status. If any service fails to start, check the logs for error messages and troubleshooting guidance.

Installation Method 2: Step-by-Step Manual Installation

Manual installation provides greater control over the deployment process and allows customization of individual components. This method suits production environments requiring specific configurations.

Adding the Wazuh Repository

Install Required Dependencies first to ensure proper repository access:

apt-get install gnupg apt-transport-https

Import the GPG Key for package verification:

curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && chmod 644 /usr/share/keyrings/wazuh.gpg

Add the Repository to your sources list:

echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list

Update Package Information to reflect the new repository:

apt-get update

Installing Wazuh Manager

Install the Manager Package using APT:

apt-get install wazuh-manager

Start and Enable the Service for automatic startup:

systemctl daemon-reload
systemctl enable wazuh-manager
systemctl start wazuh-manager

Verify Manager Status to ensure proper operation:

systemctl status wazuh-manager

The manager should display “active (running)” status. Check /var/ossec/logs/ossec.log for any startup errors if the service fails to start properly.

Installing and Configuring Filebeat

Install Filebeat Service to enable log forwarding:

apt-get install filebeat

Enable and Start Filebeat with these commands:

systemctl daemon-reload
systemctl enable filebeat
systemctl start filebeat

Test Filebeat Output to verify connectivity:

filebeat test output

Successful output indicates proper configuration and connectivity to the indexer. Any connection errors require reviewing network settings and firewall configurations.

Installing Wazuh Agents on Debian 12

Deploying agents across your infrastructure enables comprehensive endpoint monitoring. Wazuh provides automated enrollment methods to simplify large-scale deployments.

Adding Repository and Installing Agent

Prepare the Target System by installing required packages:

apt install curl gnupg2 apt-transport-https

Import the GPG Key for package verification:

curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --dearmor > /etc/apt/trusted.gpg.d/wazuh.gpg

Add Wazuh Repository to the sources list:

echo "deb https://packages.wazuh.com/4.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list

Update Package Information and install the agent:

apt update

Automated Agent Enrollment

Use Environment Variables for automatic registration during installation:

WAZUH_MANAGER="192.168.1.100" apt install wazuh-agent

Replace 192.168.1.100 with your Wazuh manager’s IP address. This method automatically enrolls the agent during installation, eliminating manual registration steps.

Alternative Installation Method using deployment variables:

wget https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.7.2-1_amd64.deb && sudo WAZUH_MANAGER='192.168.1.100' dpkg -i ./wazuh-agent_4.7.2-1_amd64.deb

Start and Enable Agent Service to begin monitoring:

systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agent

Generate Installation Commands from Dashboard

Access the Dashboard enrollment wizard through the web interface. Navigate to Wazuh App > Agents > Deploy new agent and follow the guided process.

Select Operating System and configure deployment parameters through the intuitive interface. The wizard generates customized installation commands based on your selections.

Copy Generated Commands and execute them on target systems for automated agent deployment. This method ensures consistent configuration across your infrastructure.

Integration with Elastic Stack (ELK)

Integrating Wazuh with the Elastic Stack enhances visualization capabilities and provides powerful analytics tools for security data analysis.

Installing Elasticsearch

Add Elastic Repository to your system:

curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | gpg --dearmor -o /usr/share/keyrings/elastic-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/elastic-keyring.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main" | tee -a /etc/apt/sources.list.d/elastic-7.x.list

Install Elasticsearch using APT:

apt update
apt install elasticsearch=7.17.9

Configure Elasticsearch for Wazuh integration by editing /etc/elasticsearch/elasticsearch.yml:

network.host: 0.0.0.0
discovery.type: single-node
cluster.initial_master_nodes: ["node-1"]

Setting Up Logstash Integration

Install Logstash for data processing:

apt install logstash=1:7.17.9-1

Configure Logstash Pipeline for Wazuh data processing. Create configuration files in /etc/logstash/conf.d/ to define input, filter, and output sections.

Create Index Templates for proper data mapping:

sudo mkdir /etc/logstash/templates
sudo curl -o /etc/logstash/templates/wazuh.json https://packages.wazuh.com/integrations/elastic/4.x-8.x/dashboards/wz-es-4.x-8.x-template.json

The template configures field mappings and sets the refresh interval to 5 seconds for near-real-time data availability.

Post-Installation Configuration and Security

Proper configuration after installation ensures optimal performance and security for your Wazuh deployment.

Manager Configuration

Edit Manager Settings in /var/ossec/etc/ossec.conf to customize log collection rules, alerting thresholds, and integration settings. This file controls all aspects of manager behavior and should be carefully configured for your environment.

Configure Agent Groups to apply specific policies to different types of systems. Create groups for servers, workstations, and specialized systems with appropriate monitoring configurations.

Set Up Email Notifications by configuring SMTP settings in the manager configuration. This enables automatic alert delivery to security teams when critical events occur.

Security Hardening

Change Default Passwords immediately after installation. Access the dashboard and update all default credentials to strong, unique passwords that meet your organization’s security policies.

Enable SSL/TLS Encryption for all communications between components. Configure certificates for the dashboard, manager, and agent communications to ensure data protection in transit.

Implement Access Controls by creating role-based user accounts with appropriate permissions. Limit administrative access to authorized personnel only.

Disable Package Repositories after installation to prevent accidental upgrades:

sed -i "s/^deb /#deb /" /etc/apt/sources.list.d/wazuh.list
apt update

This prevents unintended updates that could disrupt your security monitoring operations.

Testing and Verification

Thorough testing ensures your Wazuh installation functions correctly and provides the expected security monitoring capabilities.

Service Status Verification

Check All Services are running properly:

systemctl status wazuh-manager wazuh-indexer wazuh-dashboard

All services should show “active (running)” status. Any failed services require investigation and resolution before proceeding.

Test Agent Connectivity from enrolled systems:

/var/ossec/bin/agent_control -lc

This command displays connected agents and their last communication time. Active agents should show recent timestamps.

Functional Testing

Generate Test Alerts by creating controlled security events on monitored systems. This verifies the complete data flow from agents through the manager to the dashboard.

Verify Dashboard Access by logging into the web interface and confirming all visualizations display data correctly. Check that agent status, alert summaries, and compliance dashboards function properly.

Test Alert Notifications by triggering test events and confirming email notifications arrive as configured. This ensures your incident response procedures will activate when real threats occur.

Troubleshooting Common Issues

Understanding common installation and configuration issues helps resolve problems quickly and maintain system reliability.

Service Startup Problems

Manager Service Failures often result from configuration file syntax errors. Check /var/ossec/logs/ossec.log for detailed error messages and validate configuration syntax.

Agent Registration Issues typically stem from network connectivity problems or incorrect manager IP addresses. Verify network connectivity using:

telnet <manager_ip> 1514

Successful connections indicate proper network configuration.

Dashboard Access Problems

“Wazuh server API seems to be down” errors indicate communication issues between dashboard and manager components. Check manager service status and API connectivity:

curl -k -X GET "https://<api_url>:55000/" -H "Authorization: Bearer $(curl -u <api_user>:<api_password> -k -X POST 'https://<api_url>:55000/security/user/authenticate?raw=true')"

Successful responses confirm API availability.

Connection Timeouts may indicate firewall restrictions or incorrect configuration. Verify all required ports are open and services are listening on correct interfaces.

Log Analysis for Troubleshooting

Check Component Logs systematically when issues arise:

# Manager logs
cat /var/ossec/logs/ossec.log | grep -i -E "error|warn"

# Filebeat logs
cat /var/log/filebeat/filebeat | grep -i -E "error|warn"

# Dashboard logs
journalctl -u wazuh-dashboard | grep -i -E "error|warn"

These logs provide detailed information about component status and any operational issues.

Performance Optimization and Maintenance

Regular maintenance ensures your Wazuh deployment continues operating efficiently as your environment grows.

Resource Monitoring

Monitor System Resources regularly to ensure adequate CPU, memory, and storage allocation. Use system monitoring tools to track resource utilization trends and plan capacity upgrades.

Database Maintenance includes regular cleanup of old indices and archived data. Configure retention policies based on compliance requirements and storage capacity.

Index Management involves monitoring Elasticsearch indices and implementing lifecycle policies for optimal performance. Configure hot, warm, and cold storage tiers based on data access patterns.

Congratulations! You have successfully installed Wazuh. Thanks for using this tutorial for installing Wazuh on your Debian 12 “Bookworm” system. For additional help or useful information, we recommend you check the official Wazuh website.