Theseus

Appearance

Stack and services ​

Problems with a running stack.

A console page fails to load or shows errors ​

Diagnose.

bash
cd /opt/theseus
sudo ./theseus status

Look for containers that are not running, unhealthy health, or probes that are DOWN. Then:

bash
sudo ./theseus logs ageleia-backend         # the console's API
sudo ./theseus logs web                     # the gateway
Probe DOWNLook at
indexersudo ./theseus logs wazuh.indexer; see the next section
manager-apisudo ./theseus logs wazuh.manager
dashboardsudo ./theseus logs wazuh.dashboard
keycloaksudo ./theseus logs keycloak, keycloak-db
console-api, console-uisudo ./theseus logs ageleia-backend, ageleia-frontend
enrollsudo ./theseus logs enroll
websudo ./theseus logs web

A service stuck after a configuration change usually recovers with sudo ./theseus restart <service>.

Services are slow to become healthy, or the indexer keeps restarting ​

Symptom. After a start, probes stay DOWN; wazuh.indexer restarts; the install's up step prints some services were slow to become healthy - retrying.

Causes and fixes.

  1. vm.max_map_count too low. The indexer log shows max virtual memory areas vm.max_map_count [65530] is too low.

    bash
    sysctl vm.max_map_count
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-theseus.conf && sudo sysctl --system
sudo ./theseus restart wazuh.indexer

  2. Not enough memory. The indexer is killed (OOMKilled, exit code 137) or the host swaps.

    bash
    free -h
docker inspect --format '{{.State.OOMKilled}} {{.State.ExitCode}}' $(docker ps -aqf name=wazuh.indexer)

    Add memory, or move to two servers. Keep INDEXER_HEAP at about half of the memory you want the indexer to use, and well below the host's free memory.

  3. First start. On a fresh install the indexer and the security setup take several minutes. Wait ten minutes before acting.

Disk full ​

Symptom. Services fail, the indexer stops accepting writes (its log mentions flood stage disk watermark or read_only_allow_delete), the console shows no new alerts.

bash
df -h /opt/theseus /var/lib/docker
sudo docker system df

Fix.

  1. Free space: remove unused images (sudo docker image prune), old backups, and old /opt/theseus.prev-* directories you no longer need.
  2. Grow the disk if alert volume needs it, or keep logs for fewer days: Admin → Integrations → Data retention (default 45 days). The Compliance page shows the disk the period needs (Data retention).
  3. Once the indexer has space again, restart it: sudo ./theseus restart wazuh.indexer.

Clock skew ​

Symptom. theseus-node logs refusals of its requests; Theseus agents are refused; sign-in fails with token errors.

Cause. Signed requests carry a timestamp. The control plane accepts ±5 minutes.

bash
timedatectl

Fix. Enable time synchronisation (sudo timedatectl set-ntp true, or chrony) on the server and on endpoints.

theseus-node is not reporting ​

Symptom. We tell you the server is silent, or configuration changes do not arrive.

bash
sudo systemctl status theseus-node
sudo journalctl -u theseus-node -n 100
Log showsCauseFix
Connection errors, timeoutsOutbound HTTPS to the control plane blockedAllow it (network)
TLS key does not match ca_pinTLS inspection in the pathExclude the control plane from inspection
401 or 403, then a 10-minute pauseThe node was removed or replaced in the control planeContact us; the node can be re-enrolled in place

theseus-node only dials out; nothing needs to reach it.

Two servers: the application server cannot reach the core ​

Symptom. On the application server, ./theseus status shows indexer, manager-api or dashboard DOWN; the SIEM (/siem/) or scan pages fail; the install of the application server waits for the core.

Diagnose, on the application server:

bash
grep CORE_HOST /opt/theseus/theseus.env
nc -zv <core private IP> 9200
nc -zv <core private IP> 55000
nc -zv <core private IP> 5601
nc -zv <core private IP> 9001

On the core:

bash
grep CORE_BIND /opt/theseus/theseus.env
sudo ss -ltn | grep -E ':(9200|55000|5601|9001) '
FindingFix
nc times outOpen the four ports on the core from the application server's private address (firewall), including cloud security groups
CORE_HOST or CORE_BIND is not the core's private addressThe private address was wrong when we installed; tell us the right one
The core is not listening on those portsThe core's install did not finish: sudo ./theseus status on the core

Wazuh agents connect to the wrong address in a two-server install ​

Symptom. Agents enrol but never connect. AGENT_HOST is a private address endpoints cannot reach.

Cause. Without an agent address, endpoints are given the core's private address.

Fix. Tell us a name or address of the core that endpoints reach on TCP 1514; endpoints enrolled before the change need re-enrolment.

Theseus documentation