Installation

Problems while running the install command on a server.

The install command cannot reach the control plane

Symptom. curl fails before anything is printed: Could not resolve host, Connection timed out, Connection refused.

Cause. The server cannot resolve or reach the control plane's address: DNS, an outbound firewall, or a proxy.

Fix.

getent hosts <control host>                          # DNS
curl -sS -o /dev/null -w '%{http_code}\n' -k https://<control host>[:port]/health    # reachability

Allow outbound HTTPS from the server to the host and port in your install command (see Network and firewall). If outbound traffic must go through an HTTP proxy, tell us before installing.

TLS pin error

Symptom. curl: (90) SSL: public key does not match pinned public key, or from theseus-node: control plane TLS key does not match ca_pin.

Cause. Something between the server and the control plane presents a different certificate: a TLS-inspecting proxy or firewall, or the command was edited.

Fix. Exclude the control plane's address from TLS inspection. Use the install command exactly as we sent it. Do not remove --pinnedpubkey: it is what proves the script comes from us.

Token expired or already used

Symptom.

ERROR: enrolment failed (see above). An install token works once and for 24 h: if it was used or
has expired, get a new install command from Daedalus

or the control plane refused the token (wrong, already used or expired).

Cause. Install tokens (TND-...) are valid for 24 hours and for one server.

Fix. Ask us for a new install command. Running the same command again on the same server after it enrolled is safe: the script recognises its token and continues without spending it again.

A host check failed

The command lists every failed check and stops. Fix them and run the same command again.

Message	Fix
unsupported OS '<id> <version>'	Use Ubuntu 22.04/24.04, Debian 12 or RHEL/Rocky/Alma 9 (requirements)
architecture aarch64: Theseus needs x86_64 (amd64)	ARM servers are not supported. Use an x86-64 server (for example on AWS a non-Graviton instance type)
memory: N GB - role all needs at least 8 GB	Add memory, or use two servers
disk: N GB free under /opt - Theseus needs at least 40 GB	Free or add disk on the file system of /opt/theseus
the clock is not synchronised	Install chrony or systemd-timesyncd, run sudo timedatectl set-ntp true, check timedatectl shows System clock synchronized: yes
vm.max_map_count is N and cannot be raised to 262144	The kernel setting is locked (some containers or restricted VMs). Set it on the host: sudo sysctl -w vm.max_map_count=262144
port 443 is in use (nginx): role all needs it	See below
systemd is not running	theseus-node needs systemd; containers without systemd and WSL setups without it are not supported

Ports 80 or 443 already in use

Cause. Another web server, a previous Wazuh install, or a control panel listens on the port.

sudo ss -ltnp 'sport = :443'
sudo ss -ltnp 'sport = :80'
sudo ss -ltnp 'sport = :1514'

Fix. Stop and disable that service (for example sudo systemctl disable --now nginx), or use a dedicated server. Port 1515 must also be free on single and core servers (an old Wazuh manager).

Docker installation fails

Symptom	Fix
podman, buildah or runc packages conflict (RHEL family)	sudo dnf remove podman buildah runc, then run the command again
Docker repository not reachable	Allow outbound HTTPS to download.docker.com, or install Docker Engine 24+ with the Compose plugin yourself first; an existing Docker 24+ is kept
Docker is older than 24	Upgrade Docker, then run the command again

Containers fail to start with cgroup errors

Symptom. The install fails at the install step and the node's log shows container start errors mentioning cgroups (for example failed to create shim task, cgroup or cgroupfs).

Cause. The Docker daemon's cgroup setup does not match the host kernel. This happens on some virtualisation layers and older or unusual kernels. Theseus does not change Docker's configuration.

Fix. Check Docker on its own first:

docker info --format '{{.CgroupDriver}} cgroup v{{.CgroupVersion}}'
sudo docker run --rm hello-world

If hello-world fails too, fix Docker on the host (on most hosts, the systemd cgroup driver with cgroup v2 works; the driver is set by exec-opts in /etc/docker/daemon.json), restart Docker, then ask us to run the install again. Supported servers on the listed distributions work with Docker's defaults.

The install fails during the stack install

Symptom.

ERROR: the install failed: <reason>
Details: journalctl -u theseus-node -n 100, and the machine's page in Daedalus. Your provider can start the install again.

Diagnose.

sudo cat /var/lib/theseus-node/progress.log          # each step: running, done or failed, with details
sudo journalctl -u theseus-node -n 200
cd /opt/theseus && sudo ./theseus status              # if the install step got that far

Failed step	Usual cause
download	The bundle could not be fetched or its checksum did not match: network interruption, proxy
registry login	The server cannot reach the registry on the control plane's address
install	Image pull failed (network), a service did not become healthy (memory, vm.max_map_count, disk), or the Wazuh indexer was slow on first start
secrets	The core could not hand its secrets to the control plane (network)

Fix the cause, then ask us to start the install again: we can re-run it from the control plane without a new command.

The install takes very long

The first install downloads all images (several GB) and initialises the Wazuh indexer. 15 to 30 minutes is normal; slow networks or disks take longer. The display stops after 45 minutes but the install continues (up to 60 minutes for the stack install step):

sudo tail -f /var/lib/theseus-node/progress.log

I closed the terminal before the summary

The install continues. The first sign-in is in /opt/theseus/FIRST-LOGIN.txt once it finishes:

sudo cat /opt/theseus/FIRST-LOGIN.txt

If it has no password (the administrator already existed), make a new temporary password:

cd /opt/theseus && sudo ./theseus admin reset-password