# Troubleshooting

# Server nao sobe

# `Error: TATUZIM_STEPCA_URL required`

O server precisa do step-ca pra emitir o proprio cert. Garanta que estao setados:

• TATUZIM_STEPCA_URL
• TATUZIM_STEPCA_PROVISIONER_KID
• TATUZIM_STEPCA_PROVISIONER_KEY (JSON do JWK descriptografado)
• TATUZIM_STEPCA_ROOT_CA_PATH

Pra obter PROVISIONER_KEY:

ENC_KEY=$(docker exec dev_stepca_tatuzim step ca provisioner list | jq -r '.[0].encryptedKey')
docker exec -i dev_stepca_tatuzim sh -c \
    "echo '$ENC_KEY' | step crypto jwe decrypt --password-file /run/secrets/ca_password"

# `Error: vault already locked`

Outro processo tem o vault aberto. Identifique:

# No host
cat /var/lib/tatuzim/vault.lock          # mostra PID
ps -ef | grep tatuzim                     # confirma processo

Pare o outro processo (docker stop dev_tatuzim_server ou systemctl stop ...) antes de iniciar este.

# `Error: stepca sign: ... UnknownIssuer`

Server tenta auto-bootstrap do proprio cert mas o step-ca rejeita. Causas:

1. JWK provisioner key errada — recapturar TATUZIM_STEPCA_PROVISIONER_KEY (passphrase do step-ca pode ter mudado)
2. CN do server vazio ou invalido — checar TATUZIM_SERVER_CN
3. step-ca container nao acessivel — curl -sk $TATUZIM_STEPCA_URL/health

# `Address already in use`

Outra instancia do server (ou de outro produto) ja escuta nas mesmas portas. Verifique:

ss -ltnp | grep -E ":(8080|8443|8444)\b"

Mude o TATUZIM_*_BIND pra portas livres, ou pare o conflito.

# Agent: enroll falha

# `server rejected enrollment (401): token_not_found`

Possiveis causas:

1. Token errado ou expirou — gere outro com tatuzim token create
2. Token ja consumido (single-use) — gere outro
3. CLI gerou token mas server tem visao stale — restart o server depois de criar token (era bug antigo, ja corrigido com VaultLock; ainda pode ocorrer em config errada)

# `server rejected enrollment (403): hostname_mismatch`

O hostname do agent (TATUZIM_AGENT_HOSTNAME) nao bate com o que o token foi vinculado. Gere outro token com o hostname certo:

tatuzim token create --hostname meu-hostname-real --role mautic --ttl 1h

# `server rejected enrollment (403): role_mismatch`

Mesma logica — TATUZIM_AGENT_ROLE diferente do token. Gere outro.

# `connection refused` no enroll

Server nao esta alcancavel. Verifique:

# Do agent
curl -v $TATUZIM_SERVER_URL/v1/enroll -X POST -d '{}'
# Se 401 token_not_found → server OK, problema era outro
# Se Connection refused → servidor/firewall

# Agent: mTLS falha

# `received fatal alert: UnknownCA`

Bundle do cert do agent nao contem o intermediate CA, ou server nao confia no root.

Checagem rapida no agent:

# Deve ter intermediate + leaf
sudo cat /var/lib/tatuzim-agent/identity/ca.pem | grep -c BEGIN
# Esperado: 1 (intermediate)

sudo cat /var/lib/tatuzim-agent/identity/agent.crt | grep -c BEGIN
# Esperado: 1 (leaf)

Se faltar ca.pem, refaca o enroll.

# `received fatal alert: BadCertificate` ou `agent_not_registered`

O agent tem cert valido mas o server nao tem registro do agente. Possiveis causas:

1. Vault foi recriado/restaurado de backup antigo
2. Agent foi enrolado em outro vault
3. Bug do VaultLock (deveria ser raro agora)

Solucao: refaca o enroll. Antes, no agent:

sudo rm -rf /var/lib/tatuzim-agent/identity/*
sudo rm -f /var/lib/tatuzim-agent/state/processed.json

# `agent_revoked`

Agente foi marcado como revogado no server. Sem recuperacao — enroll novo necessario.

# Agent: run nao processa cargas

# Manifest vazio mas voce criou cargas

A carga foi atribuida pra outro agente_id. Verifique:

# Stop server
docker stop dev_tatuzim_server

# List todas as entregas
docker run --rm --entrypoint /usr/local/bin/tatuzim \
    -v tatuzim_tatuzim_vault:/var/lib/tatuzim \
    -e TATUZIM_MASTER_PASSPHRASE=... \
    tatuzim-server:dev \
    agente list --root /var/lib/tatuzim

# A carga create usa --destino <hostname>, garantir que bate

# Carga aparece no manifest mas nao processa

Olhe os logs com RUST_LOG=debug:

sudo systemctl stop tatuzim-agent
sudo -u tatuzim RUST_LOG=debug /usr/local/bin/tatuzim-agent run

Erros comuns:

• csr_cn_mismatch — o CSR gerado tem CN != hostname do agent (bug, reportar)
• stepca_failed — server nao consegue assinar (ver logs do server)
• db_error — vault corrupto (rare)

# Vault corrompido

Sintomas:

• Error: parse cargas: ...
• agente list retorna entradas truncadas

Recuperacao:

1. Pare o server
2. Inspecione o backup mais recente (voce TEM backup, certo? ver Backup & Recovery)
3. Restore:

cp /backup/db.enc /var/lib/tatuzim/db.enc
cp /backup/config.json /var/lib/tatuzim/config.json
rm -rf /var/lib/tatuzim/db.plain /var/lib/tatuzim/db.tar /var/lib/tatuzim/vault.lock
systemctl start tatuzim-server

# Logs uteis

# Server

docker logs -f dev_tatuzim_server                    # tail
docker logs dev_tatuzim_server 2>&1 | grep WARN      # warnings
docker logs dev_tatuzim_server 2>&1 | grep -i mtls   # filtrar mTLS

# Agent (systemd)

journalctl -u tatuzim-agent -f
journalctl -u tatuzim-agent --since "1 hour ago"
journalctl -u tatuzim-agent -p err

# Agent (foreground com debug)

sudo systemctl stop tatuzim-agent
sudo -u tatuzim RUST_LOG=debug /usr/local/bin/tatuzim-agent run

# step-ca

docker logs dev_stepca_tatuzim 2>&1 | tail -50

# Reset completo

Cuidado: apaga tudo do server e dos agents.

# Server
docker compose down tatuzim-server
docker volume rm tatuzim_tatuzim_vault
docker compose up -d tatuzim-server

# Cada agent
sudo systemctl stop tatuzim-agent
sudo rm -rf /var/lib/tatuzim-agent/identity/* \
    /var/lib/tatuzim-agent/state/* \
    /var/lib/tatuzim-agent/out/*

# Re-enroll cada agent