# Criando uma Carga

Uma carga e uma unidade de entrega. No MVP, o unico tipo suportado e csr_cert — instrui um agent especifico a gerar um keypair + CSR localmente, pedir cert ao server, e escrever em out/<nome>.{crt,key}.

# Pre-requisitos

• Server rodando
• Agent enrolado e ativo (tatuzim-agent run ou systemd)

# 1. Criar a carga

O comando tatuzim carga create precisa do server parado (lock exclusivo do vault):

docker stop dev_tatuzim_server

docker run --rm --entrypoint /usr/local/bin/tatuzim \
    -v tatuzim_tatuzim_vault:/var/lib/tatuzim \
    -e TATUZIM_MASTER_PASSPHRASE=SUA-PASSPHRASE \
    tatuzim-server:dev \
    carga create --root /var/lib/tatuzim \
        --tipo csr_cert \
        --nome traefik-cert \
        --destino vps-01

docker start dev_tatuzim_server

Output:

Carga registrada:
  carga_id:     00000000-0000-...
  entrega_id:   00000000-0000-...
  destinatario: vps-01 (00000000-0000-...)

# Parametros

# 2. Agent processa automaticamente

Se o agent ja esta rodando (systemd), ele vai pegar a carga no proximo poll (default 30s). Pra acompanhar:

ssh vps-01 'journalctl -u tatuzim-agent -f'

Logs esperados:

INFO tatuzim_agent::processor: processing csr_cert carga carga=traefik-cert entrega_id=00000000-0000-...
INFO tatuzim_agent::processor: cert written crt=/var/lib/tatuzim-agent/out/traefik-cert.crt key=/var/lib/tatuzim-agent/out/traefik-cert.key

# 3. Verificar artefatos

ssh vps-01 'sudo ls -la /var/lib/tatuzim-agent/out/'
# -rw-r--r-- 1 tatuzim tatuzim 1263 ... traefik-cert.crt
# -rw------- 1 tatuzim tatuzim  227 ... traefik-cert.key

ssh vps-01 'sudo openssl x509 -in /var/lib/tatuzim-agent/out/traefik-cert.crt -noout -subject -issuer -dates'
# subject=CN=vps-01
# issuer=O=Tatuzim Dev CA, CN=Tatuzim Dev CA Intermediate CA
# notBefore=...
# notAfter=...

# 4. Verificar audit log

Apos processamento bem-sucedido, o agent reporta entrega_instalada:

docker stop dev_tatuzim_server

docker run --rm --entrypoint /usr/local/bin/tatuzim \
    -v tatuzim_tatuzim_vault:/var/lib/tatuzim \
    -e TATUZIM_MASTER_PASSPHRASE=SUA-PASSPHRASE \
    tatuzim-server:dev \
    evento list --root /var/lib/tatuzim --agente vps-01 --verify

docker start dev_tatuzim_server

Output:

Hash chain: VALID

OCORRIDO_EM                  TIPO                  EVENTO_ID
2026-05-23T22:30:15.123...   entrega_instalada     00000000-0000-...
2026-05-23T22:29:30.456...   agent_started         a1b2c3d4-...

# 5. Manifest agora vazio

Como o agent reportou entrega_instalada, o server moveu a entrega de pendente pra instalada — ela some do manifest:

# No VPS, manual:
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) /tmp/chain.pem /tmp/agent.key
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

# {"entregas":[]}

# Limitacao do MVP

O CN do cert emitido e sempre o hostname do agent (vps-01), nao traefik-vps-01.com.br ou similar. Isso porque o middleware de issue valida csr_cn == agent_hostname.

Pra emitir cert com outro CN, alternativas:

1. Usar o cert do agent como base + reload em outro servico que aceita esse cert (Traefik aceita varios certs)
2. Pedir cert diretamente ao step-ca sem passar pelo Tatuzim (usando step CLI)
3. Esperar v0.2 com mecanismo dedicado pra carga csr_cert com CN custom

# Reprocessar carga

Se o agent ja processou (esta em processed.json) e voce quer reprocessar:

ssh vps-01 'sudo rm /var/lib/tatuzim-agent/state/processed.json'
sudo systemctl restart tatuzim-agent

No proximo poll o agent vai ver o manifest e processar de novo (a entrega ainda precisa estar pendente no server — se ja virou instalada, nao vai aparecer).

Pra reentregar do server, voce precisa criar uma carga nova (nao ha "re-deliver" no MVP).

# Proximos passos

• Hooks Pos-Instalacao — automatizar systemctl reload traefik apos novo cert
• Conceitos: Modos de Carga — explicacao detalhada dos tres modos