Skip to main content
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

-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
/etc/systemd/system/certplane-agent.timer
Habilita el timer (es el timer el que dispara el servicio — no habilites el .service):
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:
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

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.