Troubleshooting Common Issues in the Wazuh Docker Stack

max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

# Apply the setting immediately (takes effect without reboot)
sudo sysctl -w vm.max_map_count=262144

# Persist the setting across reboots
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf

# Verify the current value
sysctl vm.max_map_count

# Restart the Indexer container
sudo docker compose restart wazuh.indexer

# Confirm the Indexer is now healthy
sudo docker compose ps wazuh.indexer

# Confirm the Manager API is reachable and responding
curl -sk https://localhost:55000

# Check the credentials currently in wazuh.yml
grep -E 'username:|password:|url:' config/wazuh_dashboard/wazuh.yml

# Compare against what is in .env
grep -E 'API_USERNAME|API_PASSWORD' .env

sudo bash scripts/wazuh-dev.sh server up

sudo docker compose restart wazuh.dashboard
sudo docker compose logs -f wazuh.dashboard

# Test port reachability from the agent host to the Manager
nc -zv <manager-ip> 1514
nc -zv <manager-ip> 1515

# Check agent container logs for connection errors
sudo docker compose logs -f wazuh.agent

# Verify the Manager enrollment service is running
docker exec wazuh.manager /var/ossec/bin/wazuh-control status

# Check registered agents from the Manager API
TOKEN=$(curl -k -s -u "wazuh-wui:<your-password>" \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true")
curl -k -s -H "Authorization: Bearer $TOKEN" \
  https://localhost:55000/agents | python3 -m json.tool

SSL routines:ssl3_read_bytes:sslv3 alert certificate unknown
x509: certificate signed by unknown authority
TLS handshake failed

# Stop the stack
sudo docker compose down

# Remove stale certs
rm -rf config/wazuh_indexer_ssl_certs/

# Regenerate using the certs generator compose file
sudo docker compose -f generate-indexer-certs.yml run --rm generator

# Confirm certs were created
ls config/wazuh_indexer_ssl_certs/

# Restart the stack
sudo docker compose up -d

curl -k -u admin:<your-password> https://localhost:9200
# {"status":401,"error":"..."}

# Check the hash stored for admin
grep -A3 "^admin:" config/wazuh_indexer/internal_users.yml

# Check the INDEXER_PASSWORD in .env
grep INDEXER_PASSWORD .env

sudo bash scripts/wazuh-dev.sh server up

❌  Error: Character "$" it is not allowed on API_PASSWORD.

❌  Error: Character "$" it is not allowed on API_USERNAME.

# Generate a safe random password (removes $ and / characters)
openssl rand -base64 18 | tr -d '$/'

sudo bash scripts/wazuh-dev.sh server up

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

# Find the actual Docker group GID on the host
getent group docker | cut -d: -f3

# Compare to what is set in .env
grep DOCKER_GID .env

DOCKER_GID=990   # replace 990 with your actual Docker GID

sudo docker compose up -d --force-recreate wazuh.agent

# Check live memory consumption per container
docker stats --no-stream

# Check for OOM kill events on the host
sudo dmesg | grep -i "oom\|killed"

# Check Dashboard container health status
sudo docker compose ps wazuh.dashboard

# Poll the Dashboard status endpoint from the host
curl -sk https://localhost:6443/api/status | python3 -m json.tool

# Check Indexer cluster health — wait for "status": "green"
curl -k -u admin:<your-password> \
  https://localhost:9200/_cluster/health?pretty

# Watch all container health statuses in real time
watch -n 5 "sudo docker compose ps"

# Check for errors in Dashboard logs
sudo docker compose logs --tail=50 wazuh.dashboard

# Check for errors in Indexer logs
sudo docker compose logs --tail=50 wazuh.indexer

# Restart Dashboard if Indexer is healthy but Dashboard is stuck
sudo docker compose restart wazuh.dashboard