Comprehensive Guide to Automating Wazuh Deployment on Ubuntu 22.04

max seefeld

May 25, 2025 • 5 min read

Abstract

In modern security operations, rapid, repeatable, and auditable deployments are essential. This guide delivers an in-depth walkthrough for installing and configuring the full Wazuh stack—Manager, API, Agent, Filebeat, Elasticsearch, and Kibana plugin—on Ubuntu 22.04. You’ll get architecture insights, environment planning, a production-grade Bash script, post-install hardening, scaling strategies, integration tips, and troubleshooting best practices.

1. Introduction

Manual installs of security tooling are error-prone and time-consuming. By codifying every step in a single install script, you achieve:

Speed: One command spins up your entire log management and alerting platform.

Consistency: Identical setups across dev, staging, and prod eliminate configuration drift.

Auditability: Every action—from repo addition to service start—is logged in your version control.

Wazuh combines host-based intrusion detection, log analysis, and threat intelligence into a single platform. Automating its installation on Ubuntu 22.04 puts you hours ahead of manual procedures and ensures you can rebuild or scale at will.

2. Wazuh Stack Overview

Before diving into the script, understand each component:

Wazuh Manager: Core engine that parses logs, evaluates rules, and raises alerts.

Wazuh API: REST interface for querying alerts, managing agents, and feeding custom dashboards.

Wazuh Agent: Installed on endpoints to collect syslog, Windows Events, FIM (File Integrity Monitoring), and more.

Filebeat with Wazuh Module: Ships alerts into Elasticsearch, applying index templates and ingest pipelines.

Elasticsearch: Stores and indexes alert data; provides fast search across terabytes of logs.

Kibana + Wazuh Plugin: Visualizes alerts in a user-friendly UI, with dashboards for threat detection, compliance, and system health.

3. Deployment Architecture & Sizing

For production readiness, consider:

Single-Node vs. Cluster

Small environments (≤100 agents): Co-locate Wazuh Manager, Elasticsearch, and Kibana on a single VM with 8 GB RAM and 4 CPU cores.

Enterprise scale (1000+ agents): Separate Manager, Elasticsearch master/data nodes, and Kibana into dedicated VMs.

High Availability

Use Elasticsearch cross-cluster replication or an Elasticsearch cluster (3 data nodes + 3 master-eligible nodes).

Front the Manager API and Kibana behind a load balancer (HAProxy, NGINX).

Storage

SSD-backed volumes for Elasticsearch indices.

Daily snapshots of indices to object storage (S3, GCS, or on-prem NFS).

4. Environment & Prerequisites

OS: Ubuntu 22.04 LTS (minimal ISO).

Privileges: A user with sudo or root access.

Network: Open ports 1514 (UDP/TCP for agent-manager), 1515 (if using syslog), 5601 (Kibana), 9200 (Elasticsearch), 55000 (Wazuh API).

Hardware:

Manager/API: 2 CPU, 4 GB RAM (8 GB recommended)

Elasticsearch: 4 CPU, 16 GB RAM (heap: 8 GB)

Kibana: 2 CPU, 4 GB RAM

Time Sync: NTP or Chrony configured on all hosts.

Java: Elasticsearch 7.x requires no external Java install (bundled JDK).

5. Designing the Automation Script

Your install script should:

Fail fast with set -euo pipefail.

Centralize variables (repo URLs, GPG keys, version tags).

Install prerequisites (curl, apt-transport-https, etc.).

Add and validate GPG keys and apt repositories.

Install packages non-interactively.

Enable and start systemd services.

Perform initial configuration (Filebeat setup, Kibana plugin install).

Harden defaults (lock down API host, secure ports).

Output next-steps and endpoints.

Storing this script in Git lets you track changes, roll back to working versions, and apply in CI/CD pipelines.

6. Annotated Script Walk-Through

Location: install-wazuh.sh
Execution: chmod +x install-wazuh.sh && sudo ./install-wazuh.sh

6.1 Header & Safety Flags

#!/usr/bin/env bash
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive

-e: Exit on first error.

-u: Treat unset variables as errors.

-o pipefail: Fail if any pipeline stage fails.

6.2 Variable Definitions

WAZUH_REPO="https://packages.wazuh.com/4.x/apt"
ELASTIC_REPO="https://artifacts.elastic.co/packages/7.x/apt"
...

Centralizing versioned URLs and GPG key endpoints prevents “bit rot” when upstream changes.

6.3 Prerequisite Installation

Installs package transport, GPG tools, and release helpers:

apt-get update -y
apt-get install -y apt-transport-https ca-certificates curl gnupg2 lsb-release

6.4 Repository & GPG Setup

Imports keys securely over HTTPS, adds apt sources, and updates lists:

curl -fsSL "$WAZUH_GPG" | apt-key add -
echo "deb $WAZUH_REPO stable main" > /etc/apt/sources.list.d/wazuh.list

6.5 Package Installation

Installs Manager, API, Agent, Filebeat, and Kibana in one apt-get install call:

apt-get install -y wazuh-manager wazuh-api wazuh-agent filebeat kibana

6.6 Service Management

Enables auto-start and immediately launches each component:

for svc in wazuh-manager wazuh-api ...; do
  systemctl enable "$svc"
  systemctl start  "$svc"
done

6.7 Filebeat Wazuh Module

Loads Wazuh ingest pipelines, index templates, and restarts Filebeat:

filebeat modules enable wazuh
filebeat setup --index-management ...
systemctl restart filebeat

6.8 Kibana Plugin Installation

Adds the Wazuh app into Kibana’s UI:

/usr/share/kibana/bin/kibana-plugin install --allow-root "$KIBANA_PLUGIN_URL"
systemctl restart kibana

6.9 Hardening Defaults

Locks the API to 127.0.0.1 and ensures only localhost-bound access:

sed -i 's/^  host: 0.0.0.0/  host: 127.0.0.1/' /var/ossec/api/configuration/api.yml
systemctl restart wazuh-api

7. Post-Install Configuration & Hardening

Elasticsearch Tuning

Edit /etc/elasticsearch/jvm.options to set heap (-Xms8g -Xmx8g).

Configure replica count and shard allocation for performance.

Kibana

In /etc/kibana/kibana.yml, set server.host: "0.0.0.0" and secure via firewall or proxy.

Manager Rules & Decoders

Customize /var/ossec/etc/rules/ for your environment.

Use wazuh-modulesd to load additional threat feeds.

Firewall

Only allow manager ports from your trusted network.

Use ufw or iptables to restrict SSH and API endpoints.

SELinux/AppArmor

On Ubuntu, ensure AppArmor profiles permit Elasticsearch and Kibana operations.

Lock down Wazuh Manager binary paths.

8. Scaling & High Availability

Manager Clustering: As of Wazuh 4.x you can deploy multiple managers in an agent-manager cluster.

Elasticsearch Cluster: Use 3+ nodes with dedicated master, data, and ingest roles.

Load-Balanced API & Kibana: Place NGINX or HAProxy in front of multiple API/Kibana instances.

Automated Provisioning: Convert the install script into an Ansible role or Terraform provisioner for immutable infrastructure.

9. Integration & Automation

CI/CD: Hook script execution into Packer builds or Terraform null_resource triggers so new hosts spin up fully configured.

Alerting: Forward Wazuh alerts to Slack, Microsoft Teams, or PagerDuty via the API.

SIEM Correlation: Use Logstash or custom scripts to enrich Wazuh alerts with asset metadata before ingestion.

10. Operational Maintenance

Daily Health Checks: Cron job that calls /security/user/authenticate on the API and alerts if it fails.

Index Management: Automate Elasticsearch index rollover and ILM (Index Lifecycle Management).

Backups: Snapshot /var/ossec and Elasticsearch indices to remote storage nightly.

Upgrades: Pin your script to specific Wazuh and Elastic versions; test upgrades in a staging lab before production.

11. Troubleshooting & Best Practices

Log Locations:

/var/log/wazuh/wazuh.log (Manager)

/var/log/filebeat/filebeat

/var/log/kibana/kibana.log

Common Issues:

Elasticsearch not reachable: Check network.host and firewall.

Kibana Plugin mismatch: Ensure plugin version matches Kibana version.

Agent-Manager handshake failures: Verify certificates and network ports.

Performance:

Monitor JVM GC in Elasticsearch (_cat/nodes?v).

Tune Filebeat bulk size and worker counts for high-throughput ingestion.

12. Conclusion

By adopting this automated approach, you gain a robust, scalable, and secure Wazuh deployment in minutes instead of hours or days. The script and accompanying best practices ensure your security monitoring foundation is:

Repeatable: Easily rebuilt or cloned.

Auditable: Every step recorded in version control.

Hardened: Secure defaults out of the box.

Scalable: Ready for enterprise-grade clustering and integration.

Take this framework, adapt it to your topology, and integrate it into your DevSecOps pipeline. You’ll spend less time wrestling with installs and more time triaging threats, refining detection rules, and hardening your infrastructure—exactly where your focus belongs.