Saltar al contenido principal

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.

El agente lee un único archivo de configuración YAML, pasado al inicio con el flag --config. Esta página documenta cada campo admitido, su tipo, valor por defecto y cuándo es obligatorio.

​
Ejemplo completo

state_dir: /var/lib/certplane/agent

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: /var/lib/certplane/agent-ca.crt
  bootstrap_token: /etc/certplane/agent/bootstrap-token
  renew_before: 8h
  warn_before: 24h
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256-fingerprint"
    root_ca_bundle: /etc/certplane/ca/step-ca-root.crt

broker:
  url: https://certplane-broker.int.example.com:8443
  server_ca_bundle: /etc/certplane/broker-ca.crt
  timeout: 30s

logging:
  level: info
  format: text
  destination: stderr

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
    renew_before: 720h
    reload_command: "systemctl reload nginx"
    reload_timeout: 30s

​
Nivel superior

​
state_dir
string
predeterminado:"/var/lib/certplane/agent"
Directorio base donde el agente escribe sus archivos de estado. Todas las rutas relativas usadas internamente por el agente se resuelven contra este directorio.

​
identity

La sección identity controla cómo el agente registra y renueva su propio certificado de identidad mTLS. Este certificado se presenta al broker en cada llamada a la API.
​
identity.name
string
requerido
Common name (CN) para el certificado de identidad de este host. Usa un hostname totalmente cualificado que identifique de forma única a la máquina, por ejemplo edge01.h.int.example.com.
​
identity.provider
string
predeterminado:"step-ca"
Proveedor de CA usado para registrar y renovar el certificado de identidad. El único valor admitido es step-ca.
​
identity.cert
string
requerido
Ruta donde el agente escribe y lee su certificado de identidad (PEM). El archivo se crea en el primer registro y se sobrescribe en cada renovación.
​
identity.key
string
requerido
Ruta donde el agente escribe y lee la clave privada de identidad (PEM).
​
identity.issuer_ca_bundle
string
requerido
Ruta al bundle de CA interna (PEM) usado para verificar el certificado de identidad emitido por step-ca. El agente usa este bundle al validar su propia cadena de certificados tras la renovación.
​
identity.bootstrap_token
string
Ruta al archivo del token de arranque. Este token solo se consume durante el registro inicial. Puedes eliminarlo de la configuración una vez que el agente se haya registrado por primera vez.
​
identity.renew_before
duration
predeterminado:"8h"
El agente solicita un nuevo certificado de identidad cuando queda menos de esta duración antes de la expiración. Acepta cadenas de duración Go como 8h o 30m.
​
identity.warn_before
duration
predeterminado:"24h"
El agente escribe una advertencia en su log cuando queda menos de esta duración antes de que expire el certificado de identidad. Defínelo a un valor mayor que renew_before para tener tiempo de investigar si falla la renovación automática.

​
identity.step_ca

Estos campos son obligatorios cuando identity.provider es step-ca.
​
identity.step_ca.url
string
requerido
URL de la API de step-ca, por ejemplo https://ca.int.example.com:9000. El agente contacta con este endpoint para registrar y renovar el certificado de identidad.
​
identity.step_ca.fingerprint
string
Huella digital SHA-256 del certificado raíz de step-ca. Se debe proporcionar fingerprint o root_ca_bundle para que el agente pueda establecer confianza en step-ca.
​
identity.step_ca.root_ca_bundle
string
Ruta al certificado raíz de step-ca (PEM). Se debe definir este campo o fingerprint. Si se proporcionan ambos, root_ca_bundle tiene preferencia.
​
identity.step_ca.timeout
duration
predeterminado:"10s"
Tiempo de espera para cada llamada a la API de step-ca. Acepta cadenas de duración Go como 10s o 1m.

​
broker

​
broker.url
string
requerido
URL de la API de certplane-broker, por ejemplo https://broker.internal.example.com:8443. El agente envía solicitudes de certificado a este endpoint.
​
broker.server_ca_bundle
string
requerido
Ruta al bundle de CA (PEM) usado para verificar el certificado TLS del servidor del broker. Suele ser tu CA raíz interna.
​
broker.timeout
duration
predeterminado:"30s"
Tiempo de espera para las llamadas a la API del broker. Acepta cadenas de duración Go como 30s o 1m.

​
certificates

certificates es un array obligatorio. Debe haber al menos una entrada. Cada entrada describe un certificado de servicio que el agente gestiona en nombre de un proceso local.
​
certificates[].name
string
requerido
Un nombre único para esta entrada de certificado. Los nombres se usan en mensajes de log y no se pueden duplicar dentro del mismo archivo de configuración.
​
certificates[].profile
string
requerido
El nombre del perfil a solicitar al broker. El perfil debe estar listado bajo este host en el archivo de política del broker, de lo contrario la solicitud se rechaza.
​
certificates[].dns_names
string[]
requerido
Array de nombres DNS a incluir en los Subject Alternative Names del certificado. Se admiten nombres wildcard como *.example.com.
​
certificates[].key
string
requerido
Ruta donde el agente escribe la clave privada de servicio (PEM). Esta ruta debe ser distinta de cert.
​
certificates[].cert
string
requerido
Ruta donde el agente escribe el certificado de servicio (PEM).
​
certificates[].chain
string
requerido
Ruta donde el agente escribe la cadena intermedia de certificados (PEM), sin el certificado de entidad final.
​
certificates[].fullchain
string
requerido
Ruta donde el agente escribe la cadena completa (PEM): el certificado de entidad final seguido de todos los intermedios. Usa este archivo con la mayoría de servidores web.
​
certificates[].reload_command
string
Comando de shell a ejecutar después de escribir el certificado en disco. Úsalo para recargar el proceso que consume el certificado, por ejemplo systemctl reload nginx.
​
certificates[].reload_timeout
duration
predeterminado:"30s"
Tiempo máximo permitido para que reload_command complete. Si el comando supera este tiempo, el agente registra un error pero no reintenta automáticamente.
​
certificates[].renew_before
duration
predeterminado:"720h"
El agente solicita un nuevo certificado de servicio cuando queda menos de esta duración antes de la expiración. El valor por defecto de 720h (30 días) es adecuado para certificados de 90 días emitidos por Let’s Encrypt.

​
logging

​
logging.level
string
predeterminado:"info"
Nivel mínimo de log a emitir. Valores aceptados: debug, info, warn, error.
​
logging.format
string
predeterminado:"text"
Formato de salida para las líneas de log. Valores aceptados: text para salida legible para humanos, json para logging estructurado.
​
logging.destination
string
predeterminado:"stderr"
Dónde se escriben los logs. Valores aceptados: stdout o stderr.