> ## 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.

# Configuración del agente

> Referencia completa de agent.yml — identidad, broker, certificates y logging.

Esta página documenta cada campo de `agent.yml`. La fuente autoritativa es [`schemas/agent.schema.json`](https://github.com/TaconeoMental/Certplane/blob/main/schemas/agent.schema.json).

Claves obligatorias de nivel superior: `identity`, `broker`, `certificates`.

## `state_dir`

```yaml theme={null}
state_dir: /var/lib/certplane/agent
```

Directorio base para el estado del agente. Contiene `agent.lock`. Por defecto: `/var/lib/certplane/agent`.

## `identity`

```yaml theme={null}
identity:
  name: edge01.h.int.example.com
  provider: step-ca
  cert: /var/lib/certplane/agent/identity.crt
  key:  /var/lib/certplane/agent/identity.key
  issuer_ca_bundle: /etc/certplane/ca/agent-identity-ca-bundle.crt
  bootstrap_token: /etc/certplane/bootstrap-token  # solo para enroll
  renew_before: 8h
  warn_before: 24h
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256:aabbcc..."
    # O
    root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
    timeout: 10s
```

| Campo                    | Tipo            | Por defecto | Notas                                                              |
| ------------------------ | --------------- | ----------- | ------------------------------------------------------------------ |
| `name`                   | string          | —           | **Obligatorio.** CN del certificado de identidad.                  |
| `provider`               | enum: `step-ca` | `step-ca`   |                                                                    |
| `cert`                   | string          | —           | **Obligatorio.** Ruta del certificado de identidad.                |
| `key`                    | string          | —           | **Obligatorio.** Ruta de la clave (modo `0600`).                   |
| `issuer_ca_bundle`       | string          | —           | **Obligatorio.** Bundle de CA del emisor.                          |
| `bootstrap_token`        | string          | —           | Obligatorio solo para `enroll`. Se borra tras un registro exitoso. |
| `renew_before`           | duration        | `8h`        | Renueva la identidad cuando queda menos que esto.                  |
| `warn_before`            | duration        | `24h`       | Avisa cuando queda menos. Debe ser mayor que `renew_before`.       |
| `step_ca.url`            | string          | —           | URL de la API de `step-ca`.                                        |
| `step_ca.fingerprint`    | string          | —           | SHA-256 de la raíz. Obligatorio si no se da `root_ca_bundle`.      |
| `step_ca.root_ca_bundle` | string          | —           | Bundle PEM de la raíz. Obligatorio si no se da `fingerprint`.      |
| `step_ca.timeout`        | duration        | `10s`       |                                                                    |

Hay que dar exactamente uno entre `step_ca.fingerprint` y `step_ca.root_ca_bundle`.

## `broker`

```yaml theme={null}
broker:
  url: https://certplane-broker.int.example.com:8443
  server_ca_bundle: /etc/certplane/ca/broker-server-ca-bundle.crt
  timeout: 30s
```

| Campo              | Tipo     | Por defecto | Notas                                               |
| ------------------ | -------- | ----------- | --------------------------------------------------- |
| `url`              | string   | —           | **Obligatorio.** Endpoint HTTPS del broker.         |
| `server_ca_bundle` | string   | —           | **Obligatorio.** CA que firma el server del broker. |
| `timeout`          | duration | `30s`       | Timeout por petición.                               |

## `certificates`

Lista con **al menos un** elemento. Cada uno es un certificado de servicio gestionado.

```yaml theme={null}
certificates:
  - name: edge-wildcard
    profile: public_edge_main
    dns_names:
      - "*.example.com"
    key:       /var/lib/certplane/agent/service.key
    cert:      /var/lib/certplane/agent/service.crt
    chain:     /var/lib/certplane/agent/service.chain.crt
    fullchain: /var/lib/certplane/agent/service.fullchain.crt
    reload_command: "systemctl reload traefik"
    reload_timeout: 30s
    renew_before: 720h
```

| Campo            | Tipo      | Por defecto | Notas                                                                                |
| ---------------- | --------- | ----------- | ------------------------------------------------------------------------------------ |
| `name`           | string    | —           | **Obligatorio.** Etiqueta única; aparece en los logs.                                |
| `profile`        | string    | —           | **Obligatorio.** Perfil del broker. Debe estar permitido para la identidad del host. |
| `dns_names`      | string\[] | —           | **Obligatorio.** No vacío. Debe satisfacer los DNS permitidos del perfil.            |
| `key`            | string    | —           | **Obligatorio.** Clave privada de servicio. Se genera si falta.                      |
| `cert`           | string    | —           | **Obligatorio.** Ruta del certificado hoja.                                          |
| `chain`          | string    | —           | **Obligatorio.** Ruta de la cadena intermedia.                                       |
| `fullchain`      | string    | —           | **Obligatorio.** Ruta de `hoja + intermedias`.                                       |
| `reload_command` | string    | —           | Comando shell tras una instalación exitosa.                                          |
| `reload_timeout` | duration  | `30s`       | Timeout del comando.                                                                 |
| `renew_before`   | duration  | `720h`      | Renueva cuando queda menos.                                                          |

Ver [Comandos de recarga](/es/guides/reload-commands).

## `logging`

```yaml theme={null}
logging:
  level: info        # debug | info | warn | error
  format: text       # text | json
  destination: stderr  # stdout | stderr
```

Defaults del agente: `info`, `text`, `stderr`.

## Validación

`certplane-agent ... check` (y todo subcomando al arrancar) valida que:

* Todos los obligatorios están presentes.
* Cada `dns_names[]` es un nombre DNS válido.
* `step_ca.url` y `broker.url` son URLs válidas.
* Exactamente uno entre `step_ca.fingerprint` y `step_ca.root_ca_bundle`.
* Las rutas en `certificates` son absolutas.

Lista completa en [`config/agent.go`](https://github.com/TaconeoMental/Certplane/blob/main/config/agent.go).