Quick Reference¶

A cheat sheet for experienced operators. All commands ready to copy.

Wazuh Upgrade (Ubuntu AIO)¶

Resources¶

	Link
Checklist	CHECKLIST_WAZUH_UPGRADE_AIO
Upgrade Form	Open Web Tool
Runbook	RUNBOOK_WAZUH_UPGRADE_AIO_UBUNTU
Change Note Template	CHANGE_NOTE_TEMPLATE
Customer Info	CUSTOMERS

Metadata for change ticket (copy-paste template)¶

operator: "UNSET"
customer: "UNSET"
infrastructure: "UNSET"
change_ticket: "UNSET"
maintenance_window_start: "UNSET"      # Europe/Zurich
maintenance_window_end: "UNSET"        # Europe/Zurich
target_version: "UNSET"
current_version: "UNSET"
snapshot_id: "UNSET"
system: "Ubuntu AIO (APT)"
runbook_ref: "../runbooks/RUNBOOK_WAZUH_UPGRADE_AIO_UBUNTU.md"

📋 Health Snapshot (Pre/Post Upgrade)¶

Pre-Snapshot (before upgrade)¶

date -Is
echo "=== DISK ==="
df -h | grep -v tmpfs
echo "=== MEMORY ==="
free -h
echo "=== SERVICES ==="
systemctl status wazuh-indexer wazuh-manager wazuh-dashboard filebeat
echo "=== VERSIONS ==="
dpkg -l | grep -E 'wazuh-(indexer|manager|dashboard)|filebeat'
echo "=== CLUSTER HEALTH ==="
curl -sk -u admin:admin https://127.0.0.1:9200/_cluster/health?pretty

Post-Snapshot (after upgrade)¶

# Run exactly the same command as above again
# Compare & document

🔍 Diagnostic commands (troubleshooting)¶

Service status check¶

systemctl status wazuh-indexer wazuh-manager wazuh-dashboard filebeat -l

Last 50 errors in the journal¶

journalctl -u wazuh-indexer -n 50 --no-pager -p err
journalctl -u wazuh-manager -n 50 --no-pager -p err
journalctl -u wazuh-dashboard -n 50 --no-pager -p err
journalctl -u filebeat -n 50 --no-pager -p err

Cluster Health (Indexer)¶

curl -sk -u admin:admin https://127.0.0.1:9200/_cluster/health?pretty
curl -sk -u admin:admin https://127.0.0.1:9200/_cat/shards?v

Manager API Health¶

curl -sk -u admin:admin https://127.0.0.1:55000/api/v1/manager/info

Disk Space¶

df -h
du -sh /var/ossec/*
du -sh /var/lib/wazuh/*

🔄 Common process steps¶

1. Stop services (for upgrade)¶

systemctl stop filebeat
systemctl stop wazuh-dashboard
systemctl stop wazuh-manager
systemctl stop wazuh-indexer

2. Update package list¶

apt update

3. Perform upgrade (all components)¶

apt install --only-upgrade wazuh-indexer wazuh-manager wazuh-dashboard filebeat

4. Start services (after upgrade)¶

systemctl start wazuh-indexer
systemctl start wazuh-manager
systemctl start wazuh-dashboard
systemctl start filebeat

5. Verify status¶

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

👥 Agent group management¶

File locations¶

Web form:               webforms/agent-groups.html
Runbook:                runbooks/RUNBOOK_WAZUH_AGENT_GROUP_MANAGEMENT.md

Important files¶

merged.mg - Consolidated configuration Path: /var/ossec/etc/shared/<agent-id>/merged.mg - Generated by the Wazuh Manager - Contains the consolidated configuration of all groups assigned to an agent - Automatically updated and sent to the agent on every change - Viewable via the dashboard, but not editable

ar.conf - Active Response commands Path: /var/ossec/etc/shared/<group-name>/ar.conf - List of commands for Active Response - Scripts/programs for maintenance and troubleshooting - Service restart instructions (Wazuh, OSSEC) - Viewable via the dashboard, but not editable

Basic commands¶

# Create group
/var/ossec/bin/agent_groups -a -g <group-name>

# List all groups
/var/ossec/bin/agent_groups -l

# Specific group with details
/var/ossec/bin/agent_groups -l -g <group-name>

# Add agent to group(s)
/var/ossec/bin/agent_groups -a -i <agent-id> -g <group-name>

# Add agent to multiple groups
/var/ossec/bin/agent_groups -a -i <agent-id> -g <group1>,<group2>,<group3>

# Remove agent from group
/var/ossec/bin/agent_groups -r -i <agent-id> -g <group-name>

# Remove agent from all groups
/var/ossec/bin/agent_groups -r -i <agent-id>

# All agents with group membership
/var/ossec/bin/manage_agents -l

Examples¶

# Create Linux server group
/var/ossec/bin/agent_groups -a -g linux-servers

# Add agent to group
/var/ossec/bin/agent_groups -a -i 001 -g linux-servers

# Add agent to multiple groups (multi-groups)
/var/ossec/bin/agent_groups -a -i 002 -g linux-servers,web-servers,prod

# Delete group (3 steps)
/var/ossec/bin/agent_groups -r -g old-servers
rm -rf /var/ossec/etc/shared/old-servers
systemctl restart wazuh-manager

Group configuration¶

# Create/edit agent.conf
vi /var/ossec/etc/shared/<group-name>/agent.conf

# Create/edit ar.conf (optional)
vi /var/ossec/etc/shared/<group-name>/ar.conf

# Validate configuration
/var/ossec/bin/wazuh-logtest-config

# Reload manager
systemctl restart wazuh-manager

Health Checks¶

# Check group directories
ls -la /var/ossec/etc/shared/

# Find configuration files
find /var/ossec/etc/shared/ -name "agent.conf" -o -name "ar.conf" -o -name "merged.mg"

# Manager logs for group events
grep -i "group" /var/ossec/logs/ossec.log | tail -n 50

# Agent connection status
/var/ossec/bin/agent_control -l

# Force agent synchronisation
/var/ossec/bin/agent_control -R <agent-id>

Best Practices¶

# Backup before making changes
tar -czf /backup/wazuh-groups-$(date +%F).tar.gz /var/ossec/etc/shared/

# Naming convention
# <environment>-<function>-<location>
# Example: prod-web-servers, dev-db-servers

# Use multi-groups
# Base + Function + Environment
/var/ossec/bin/agent_groups -a -i 001 -g linux-base,web-servers,prod

📁 Catalog entries¶

Quickly find new infrastructure¶

grep -A 10 "customer: \"DeepCloud AG\"" Catalog/CUSTOMERS.md

Template for new customer (copy-paste)¶

---
customer: "UNSET"
infrastructure: "UNSET"
environment: "prod|test|dev"
wazuh_type: "Ubuntu AIO (APT)"
hosts:
  - role: "wazuh-aio"
    fqdn: "wazuh01.example.tld"
    mgmt_ip: "10.10.10.10"
urls:
  dashboard: "https://wazuh01.example.tld"
  api: "https://wazuh01.example.tld:55000"
  indexer: "https://wazuh01.example.tld:9200"
ports_expected:
  - "1514/tcp"
  - "1515/tcp"
  - "55000/tcp"
  - "5601/tcp"
  - "9200/tcp"
secrets_ref:
  admin_user: "vault://path/to/secret"
  admin_password: "vault://path/to/secret"
change_policy: "Within business hours (08:00 - 17:00 CET)"
contact_email: "team@example.tld"
---

🚨 No-Go Gates (STOP if any condition is met!)¶

Gate	Check
Disk > 90%	`df -h` → Free up space before upgrade
Services not running	`systemctl status ...` → Start/debug
No backup	Create VM snapshot OR tar backup
Outside maintenance window	Reschedule to planned time
Manager < Agent version	Upgrade Manager FIRST

📝 Git workflow (quick)¶

Submit a change¶

# Feature branch
git checkout -b fix/upgrade-command

# Edit file...

# Commit
git add runbooks/RUNBOOK_*.md
git commit -m "fix: Update command for service restart (Wazuh 4.12)"
git push origin fix/upgrade-command

# → Create pull request in the web

Review a change¶

# Check out feature branch
git fetch origin fix/upgrade-command
git checkout -b review/fix-upgrade-command origin/fix/upgrade-command

# Review & test...

# Merge (after approval)
git checkout main
git merge --ff-only review/fix-upgrade-command

🔐 Secrets management¶

Correct:

secrets_ref:
  password: "vault://deepcloud/wazuh/admin_password"

WRONG (NEVER!):

secrets_ref:
  password: "MySecretPassword123!"  # ❌ DO NOT!

All credentials must be referenced via the secret store!

📞 Support links¶

Resource	URL
Wazuh Upgrade Guide	https://documentation.wazuh.com/current/upgrade-guide/
Wazuh Official Docs	https://documentation.wazuh.com/
Project Repo	/Users/i.stricker/docker/dev/Ta-SIEMPlus
Contributing Guide	GitHub

💡 Pro tips¶

Tip 1: Chain multiple commands in series with &&¶

systemctl stop filebeat && systemctl stop wazuh-dashboard && echo "Stopped successfully"

Tip 2: Save a health check to a file¶

date -Is > /tmp/pre-upgrade-health.txt
systemctl status wazuh-* >> /tmp/pre-upgrade-health.txt
dpkg -l | grep wazuh >> /tmp/pre-upgrade-health.txt
cat /tmp/pre-upgrade-health.txt  # Post later in the ticket

Tip 3: Quickly search the catalog¶

grep -n "infrastructure:" Catalog/CUSTOMERS.md | grep DeepInfra

Tip 4: Open checklist locally¶

# Mac:
open checklists/CHECKLIST_WAZUH_UPGRADE_AIO.md

# Linux:
xdg-open checklists/CHECKLIST_WAZUH_UPGRADE_AIO.md

# Windows (PowerShell):
start checklists\CHECKLIST_WAZUH_UPGRADE_AIO.md

Need more details? → Getting Started

Submit a change? → CONTRIBUTING.md

Project overview? → Project Overview