Saltar al contenido principal
certplane-agent es un binario one-shot. Cada run hace el trabajo mínimo necesario para mantener los certificados al día y sale. Prográmalo con un timer de systemd (o cualquier scheduler).

​
CLI

ComandoPropósito
certplane-agent -c <config> enrollRegistro único. Ver Registro del agente.
certplane-agent -c <config> runRenueva la identidad si toca y luego cada certificado de servicio dentro de su ventana de renew_before.
certplane-agent -c <config> checkValida la configuración y los archivos en disco sin contactar a ningún servidor.
-c / --config es obligatorio.

​
Qué hace run

Detalle completo en Cómo funciona. Resumiendo, en cada invocación:
  1. Toma <state_dir>/agent.lock.
  2. Falla rápido si falta identity.cert — hay que registrar primero.
  3. Renueva la identidad si expira dentro de identity.renew_before (por defecto 8h).
  4. Para cada entrada en certificates[]:
    • Genera la clave de servicio en key si falta; la reutiliza si existe.
    • Salta la entrada si el certificado existe, coincide con la clave y aún no entra en la ventana de renew_before.
    • Si no, construye un CSR, pide un bundle al broker, valida que coincide con la clave local y los DNS configurados, escribe cert/chain/fullchain y ejecuta reload_command (con reload_timeout, por defecto 30s).
El lock impide que dos disparos del timer se pisen.

​
Unidad y timer de systemd

El role certplane_agent instala ambos. Manualmente:
/etc/systemd/system/certplane-agent.service
[Unit]
Description=certplane agent run
After=network.target

[Service]
Type=oneshot
User=certplane
Group=certplane
ExecStartPre=/usr/local/bin/certplane-agent -c /etc/certplane/agent.yml check
ExecStart=/usr/local/bin/certplane-agent -c /etc/certplane/agent.yml run
/etc/systemd/system/certplane-agent.timer
[Unit]
Description=certplane agent renewal timer

[Timer]
OnBootSec=1min
OnUnitActiveSec=6h
RandomizedDelaySec=5min
Unit=certplane-agent.service

[Install]
WantedBy=timers.target
Habilita el timer (es el timer el que dispara el servicio — no habilites el .service): 
systemctl daemon-reload
systemctl enable --now certplane-agent.timer
RandomizedDelaySec reparte la carga en una flota.

​
¿Cuándo llama el agente al broker?

Solo cuando un certificado entra en su ventana de renew_before o falta. Con renew_before: 720h (30 días) y un certificado de Let’s Encrypt de 90 días, cada host habla con el broker más o menos cada 60 días. Los otros disparos del timer ven que aún no toca, escriben certificate skipped, not in renewal window y salen.

​
Hooks de recarga

Si una entrada define reload_command, el agente lo ejecuta tras instalar — p. ej. systemctl reload nginx. Corre como el usuario del agente (certplane), así que normalmente necesita una regla de sudoers. Ver Comandos de recarga.

​
Logs

El agente loguea por stderr por defecto. systemd lo lleva al journal: 
journalctl -u certplane-agent --since "1 hour ago"
Líneas clave:
  • agent run started
  • service key generated / service key reused
  • certificate skipped, not in renewal window
  • requesting certificate
  • certificate installed
  • reload started / reload completed / reload failed
  • agent run completed

​
Verificar los certificados instalados

openssl x509 -in /var/lib/certplane/agent/service.crt -noout -subject -issuer -ext subjectAltName -dates
El agente ya verifica que el bundle del broker encaja con la clave local y con los dns_names. Si detecta inconsistencia, no instala el bundle.