> ## Documentation Index
> Fetch the complete documentation index at: https://certplane.kippel.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Ejecutar el agente

> Lanza certplane-agent run con un timer de systemd para renovar identidad y certificados de servicio.

`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

| Comando                              | Propósito                                                                                                 |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `certplane-agent -c <config> enroll` | Registro único. Ver [Registro del agente](/es/setup/agent-enroll).                                        |
| `certplane-agent -c <config> run`    | Renueva la identidad si toca y luego cada certificado de servicio dentro de su ventana de `renew_before`. |
| `certplane-agent -c <config> check`  | Valida 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](/es/how-it-works#fase-2-bucle-de-renovacion). 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`](/es/guides/ansible) instala ambos. Manualmente:

```ini /etc/systemd/system/certplane-agent.service theme={null}
[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
```

```ini /etc/systemd/system/certplane-agent.timer theme={null}
[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`):

```bash theme={null}
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](/es/guides/reload-commands).

## Logs

El agente loguea por `stderr` por defecto. `systemd` lo lleva al journal:

```bash theme={null}
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

```bash theme={null}
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.