# Primeiro Enrollment

Pressupoe que voce ja:

• Instalou o Tatuzim Server
• Instalou o tatuzim-agent no VPS
• Copiou o stepca-root.pem pro VPS em /etc/tatuzim-agent/stepca-root.pem

# 1. Gerar enrollment token (no hub)

O server precisa estar parado pra o CLI offline acessar o vault:

docker stop dev_tatuzim_server

Gere o token (use o hostname exato que o agent vai usar):

TOKEN=$(docker run --rm --entrypoint /usr/local/bin/tatuzim \
    -v tatuzim_tatuzim_vault:/var/lib/tatuzim \
    -e TATUZIM_MASTER_PASSPHRASE=SUA-PASSPHRASE \
    tatuzim-server:dev \
    token create --root /var/lib/tatuzim \
        --hostname vps-01 \
        --role mautic \
        --ttl 1h \
    | awk '/^    [A-Za-z0-9_-]{20,}$/ { print $1; exit }')

echo "Token: $TOKEN"

docker start dev_tatuzim_server

Output do token create mostra:

Enrollment token created:
  ID:       00000000-0000-4000-8000-000000000002
  Hostname: vps-01
  Role:     mautic
  Expires:  2026-05-23T23:02:22+00:00

Token (single-use, save it now — won't be shown again):

    EXEMPLO_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cuidado: o token e cleartext uma unica vez. O server so guarda o SHA256.

# 2. Transferir o token pro VPS

Escolha um canal seguro:

• Implant (preferido em prod) — entrega via canal autenticado
• SSH manual (dev/teste): ssh vps-01 "echo $TOKEN > /tmp/tatuzim-token"
• Password manager temporario — copy/paste rapido

Nao envie por email/Slack/Telegram em texto claro.

# 3. Enroll no VPS

ssh root@vps-01

TOKEN=$(cat /tmp/tatuzim-token)

sudo -u tatuzim \
    TATUZIM_SERVER_URL="https://tatuzim.dev.borlot.com.br" \
    TATUZIM_SERVER_MTLS_URL="https://tatuzim.dev.borlot.com.br:8443" \
    TATUZIM_SERVER_CA_PATH="/etc/tatuzim-agent/stepca-root.pem" \
    TATUZIM_AGENT_HOSTNAME="vps-01" \
    TATUZIM_AGENT_ROLE="mautic" \
    TATUZIM_AGENT_DATA_DIR="/var/lib/tatuzim-agent" \
    TATUZIM_ENROLL_TOKEN="$TOKEN" \
    /usr/local/bin/tatuzim-agent enroll

# Apague o token apos uso
rm /tmp/tatuzim-token

Sucesso:

INFO starting enrollment hostname=vps-01 role=mautic
INFO calling enrollment endpoint url=https://tatuzim.dev.borlot.com.br/v1/enroll

Enrolled successfully!
  agent_id: 00000000-0000-4000-8000-000000000001
  hostname: vps-01
  identity: /var/lib/tatuzim-agent/identity

You may now remove TATUZIM_ENROLL_TOKEN from the environment.

# 4. Verificar identidade

sudo -u tatuzim \
    TATUZIM_SERVER_URL="https://tatuzim.dev.borlot.com.br" \
    TATUZIM_AGENT_HOSTNAME="vps-01" \
    TATUZIM_AGENT_DATA_DIR="/var/lib/tatuzim-agent" \
    /usr/local/bin/tatuzim-agent identity

Mostra:

Tatuzim Agent identity:
  hostname:    vps-01
  cert CN:     vps-01
  cert serial: 0123456789abcdef0123456789abcdef
  not_before:  May 23 22:03:09 2026 +00:00
  not_after:   May 24 22:04:09 2026 +00:00
  data_dir:    /var/lib/tatuzim-agent

Os arquivos:

sudo ls -la /var/lib/tatuzim-agent/identity/
# -rw-r--r-- 1 tatuzim tatuzim 1259 ... agent.crt
# -rw------- 1 tatuzim tatuzim  227 ... agent.key
# -rw-r--r-- 1 tatuzim tatuzim 1132 ... ca.pem

# 5. Testar mTLS contra o server

Validacao manual via curl (precisa de --key + --cert chain.pem):

sudo cat /var/lib/tatuzim-agent/identity/agent.crt \
         /var/lib/tatuzim-agent/identity/ca.pem > /tmp/chain.pem
sudo cp /var/lib/tatuzim-agent/identity/agent.key /tmp/agent.key
sudo chown $(whoami):$(whoami) /tmp/chain.pem /tmp/agent.key
sudo chmod 0600 /tmp/agent.key

curl --cert /tmp/chain.pem \
     --key /tmp/agent.key \
     --cacert /etc/tatuzim-agent/stepca-root.pem \
     https://tatuzim.dev.borlot.com.br:8443/v1/manifest

# Esperado (sem cargas pendentes ainda): {"entregas":[]}

rm /tmp/chain.pem /tmp/agent.key

Se receber {"entregas":[]} — mTLS strict OK.

# 6. Habilitar o daemon

sudo systemctl enable --now tatuzim-agent
sudo journalctl -u tatuzim-agent -f

Logs esperados (com RUST_LOG=info):

INFO tatuzim_agent::commands::run: agent running hostname=vps-01
INFO tatuzim_agent::events: emit agent_started ✓
... (a cada poll_interval)
DEBUG tatuzim_agent::commands::run: manifest empty

# Problemas comuns

# `token_not_found`

• Token expirou (TTL ja passou)
• Token ja consumido (single-use)
• Server foi reiniciado e nao tem o token no DB atual
• CLI rodou enquanto server tinha vault aberto (raro com VaultLock — confirme vault.lock foi liberado)

# `hostname_mismatch` ou `role_mismatch`

TATUZIM_AGENT_HOSTNAME ou TATUZIM_AGENT_ROLE diferentes do que o token foi vinculado. Gere outro token com o hostname/role corretos.

# `Connection refused` ou `unable to verify`

Server publico nao alcancavel ou DNS errado. Teste:

curl -v https://tatuzim.dev.borlot.com.br/v1/enroll -X POST -d '{}' -m 10

Deve responder 401 token_not_found — se nao, problema de rede/DNS.

# Refazer enroll (se necessario)

Se precisar refazer (cert perdido, hostname mudou):

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

# Gerar token novo no hub, depois fazer enroll de novo

Voce vai ter outro agent_id no server. O antigo continua registrado (revoga ele se quiser limpar).

# Proximos passos

• Criando uma Carga — entregar um cert ou plugin pro agent
• Hooks Pos-Instalacao — automatizar reload de Traefik etc.