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 broker 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

server:
  address: ":8443"
  tls:
    cert: /etc/certplane/broker.crt
    key: /etc/certplane/broker.key
    min_version: "1.2"
  mtls:
    agent_ca_bundle: /etc/certplane/agent-ca.crt

policy:
  path: /etc/certplane/policy.yml
  watch: false

issuer:
  provider: acme
  acme:
    directory_url: https://acme-staging-v02.api.letsencrypt.org/directory
    account_email: admin@example.com
    account_key: /etc/certplane/acme/account.key
    dns_provider: cloudflare

secrets:
  provider: env

store:
  driver: sqlite
  path: /var/lib/certplane/broker.db

audit:
  enabled: true
  failure_mode: fail_open
  mirror_to_log: true

rate_limits:
  per_identity_per_hour: 50
  per_identity_profile_per_hour: 20

logging:
  level: info
  format: json
  destination: stdout

​
server

​
server.address
string
predeterminado:":8443"
Dirección y puerto en los que escucha el broker, con la forma host:port. Usa :8443 para escuchar en todas las interfaces en el puerto 8443.

​
server.tls

​
server.tls.cert
string
requerido
Ruta al certificado TLS del servidor del broker (PEM). Este certificado se presenta a los agentes y a cualquier otro cliente que se conecte a la API del broker.
​
server.tls.key
string
requerido
Ruta a la clave privada TLS del servidor del broker (PEM).
​
server.tls.min_version
string
predeterminado:"1.2"
Versión mínima de TLS que el broker acepta. Valores aceptados: "1.2" o "1.3". Define "1.3" para deshabilitar TLS 1.2 en entornos de alta seguridad.

​
server.mtls

​
server.mtls.agent_ca_bundle
string
requerido
Ruta al bundle de CA interna (PEM) usado para validar los certificados de identidad de agente durante el handshake mTLS. Solo los agentes cuyos certificados encadenen a una CA en este bundle podrán conectarse.

​
Tiempos de espera del servidor

Estos campos ajustan los tiempos de espera a nivel de conexión del servidor HTTP. Los valores por defecto son conservadores y adecuados para la mayoría de despliegues.
​
server.read_header_timeout
duration
predeterminado:"5s"
Tiempo máximo permitido para leer las cabeceras de la solicitud.
​
server.read_timeout
duration
predeterminado:"10s"
Tiempo máximo permitido para leer el cuerpo completo de la solicitud.
​
server.write_timeout
duration
predeterminado:"60s"
Tiempo máximo permitido para escribir la respuesta. Defínelo por encima de cualquier tiempo de ida y vuelta ACME esperado.
​
server.idle_timeout
duration
predeterminado:"120s"
Tiempo máximo que se mantiene abierta una conexión keep-alive inactiva.

​
policy

​
policy.path
string
requerido
Ruta al archivo YAML de política. El archivo de política define qué hosts pueden solicitar qué perfiles de certificado.
​
policy.watch
boolean
predeterminado:"false"
Cuando es true, el broker observa el archivo de política y lo recarga automáticamente sin reinicio. Útil en entornos donde la política se gestiona con herramientas de gestión de configuración.

​
issuer

​
issuer.provider
string
predeterminado:"acme"
Proveedor emisor de certificados. El único valor admitido es acme.

​
issuer.acme

Estos campos son obligatorios cuando issuer.provider es acme.
Usa el directorio de staging mientras pruebas para evitar alcanzar los límites de tasa de Let’s Encrypt:
  • Staging: https://acme-staging-v02.api.letsencrypt.org/directory
  • Producción: https://acme-v02.api.letsencrypt.org/directory
Cambia al directorio de producción solo cuando tu configuración esté verificada y funcionando de extremo a extremo.
​
issuer.acme.directory_url
string
requerido
URL del directorio ACME para la CA que quieras usar. Consulta la nota anterior para las URLs de staging y producción de Let’s Encrypt.
​
issuer.acme.account_email
string
requerido
Dirección de correo registrada en la cuenta ACME. Let’s Encrypt usa esta dirección para enviar advertencias de expiración y notificaciones de política.
​
issuer.acme.account_key
string
requerido
Ruta a la clave privada de la cuenta ACME (PEM). Si el archivo no existe, el broker genera una nueva clave y registra una nueva cuenta en el primer arranque.
​
issuer.acme.dns_provider
string
requerido
Proveedor DNS usado para completar desafíos dns-01, por ejemplo cloudflare. El broker usa las credenciales correspondientes del proveedor desde el proveedor de secretos configurado.
​
issuer.acme.preferred_chain
string
Nombre preferido de la cadena de certificados cuando la CA ACME ofrece varias cadenas. Para Let’s Encrypt suele ser "ISRG Root X1". Si se omite, se usa la cadena por defecto de la CA.

​
store

​
store.driver
string
predeterminado:"sqlite"
Driver de almacenamiento para el estado del broker. Valores aceptados: sqlite o file.
​
store.path
string
predeterminado:"/var/lib/certplane/broker.db"
Ruta al archivo de almacenamiento. Para el driver sqlite es el archivo de la base de datos SQLite. El broker crea el archivo si no existe.

​
audit

​
audit.enabled
boolean
predeterminado:"true"
Habilita el logging de auditoría. Cuando está habilitado, el broker registra un evento de auditoría por cada solicitud de certificado, incluyendo la identidad solicitante, el perfil solicitado y el resultado.
​
audit.failure_mode
string
predeterminado:"fail_open"
Controla el comportamiento del broker cuando no se puede escribir el log de auditoría. Valores aceptados:
  • fail_open — el broker continúa emitiendo certificados aunque falle el logging de auditoría.
  • fail_closed — el broker se niega a emitir certificados hasta que se restablezca el logging de auditoría.
​
audit.mirror_to_log
boolean
predeterminado:"false"
Cuando es true, los eventos de auditoría se escriben en el log principal de la aplicación además del log de auditoría dedicado. Útil para desarrollo y resolución de problemas.

​
rate_limits

​
rate_limits.per_identity_per_hour
integer
predeterminado:"50"
Número máximo de solicitudes de certificado que una sola identidad de host puede realizar en cualquier ventana móvil de una hora, en todos los perfiles. Define 0 para deshabilitar este límite.
​
rate_limits.per_identity_profile_per_hour
integer
predeterminado:"20"
Número máximo de solicitudes de certificado que una sola identidad de host puede realizar para un perfil específico en cualquier ventana móvil de una hora. Define 0 para deshabilitar este límite.

​
logging

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