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.

Esta guía te lleva por la configuración completa de Certplane: ejecutar el broker, definir una política de certificados, registrar un host con su certificado de identidad e iniciar el bucle de renovación del agente. Al finalizar, tu host tendrá un certificado TLS de confianza pública que se renovará automáticamente.
1

Requisitos previos

Antes de empezar, asegúrate de tener lo siguiente:
  • step-ca — Una instancia de step-ca en ejecución accesible para tus hosts. Es la CA interna que emite los certificados de identidad del agente.
  • Acceso a Let’s Encrypt — El broker usa ACME para obtener certificados públicos. Necesitas una dirección de correo válida para la cuenta ACME.
  • Token DNS de Cloudflare — Certplane usa el desafío dns-01 para demostrar la propiedad del dominio. Crea un token de API en tu panel de Cloudflare con permiso Zone:DNS:Edit para la zona correspondiente.
  • Los binarios de Certplane — certplane-broker en tu host de broker y certplane-agent en cada host gestionado.
2

Despliega el broker

El broker es el servidor central que aplica la política y obtiene certificados de tu CA pública. Crea /etc/certplane/broker.yml:
broker.yml
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

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

audit:
  enabled: true
  failure_mode: fail_open
  mirror_to_log: true

logging:
  level: info
  format: json
  destination: stdout

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

rate_limits:
  per_identity_per_hour: 50
  per_identity_profile_per_hour: 20
Coloca el certificado y la clave TLS del broker en las rutas indicadas en server.tls. El valor de server.mtls.agent_ca_bundle debe ser el conjunto de certificados de la CA que firmó (o firmará) tus certificados de identidad de agente: es el certificado raíz de step-ca.Una vez que el archivo de configuración esté en su sitio, inicia el broker:
certplane-broker --config /etc/certplane/broker.yml
El broker escucha en :8443 por defecto y requiere mTLS de cada agente que se conecte. Para una referencia completa de configuración, consulta Configuración del broker.
3

Crea un archivo de política

El archivo de política define qué perfiles de certificado existen y qué hosts pueden solicitar cada uno. Crea /etc/certplane/policy.yml:
policy.yml
version: 1

profiles:
  public_edge_main:
    cert_type: wildcard
    dns_names:
      - "*.example.com"
    acme_challenge: dns-01
    renew_before: 720h

hosts:
  edge01:
    identity: edge01.h.int.example.com
    profiles:
      - public_edge_main
  • profiles — Cada perfil con nombre define el tipo de certificado (cert_type: wildcard o cert_type: multi), los nombres DNS a incluir y el método de desafío ACME (acme_challenge: dns-01 o acme_challenge: http-01).
  • hosts — Cada entrada de host asigna una clave legible a una identidad de host (el CN del certificado de identidad emitido por step-ca) e indica qué perfiles puede solicitar ese host. El broker rechaza cualquier petición de un perfil no listado aquí.
Para una referencia completa de políticas, consulta Resumen de políticas.
4

Registra tu primer host

El registro proporciona a un host su certificado de identidad. El agente contacta con step-ca una sola vez usando un token de arranque de corta duración, genera un par de claves localmente y almacena el identity.crt resultante.Genera un token de arranque en tu instancia de step-ca:
step ca token edge01.h.int.example.com
Escribe el token en el host en la ruta que referenciarás en la configuración del agente (por ejemplo, /etc/certplane/agent/bootstrap-token).Crea la configuración del agente en /etc/certplane/agent.yml:
agent.yml
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: ""
    reload_timeout: 30s
Ejecuta el registro:
certplane-agent enroll --config /etc/certplane/agent.yml
El agente genera identity.key localmente, crea un CSR y lo envía a step-ca junto con el token de arranque. Si tiene éxito, identity.crt se escribe en la ruta definida en identity.cert.
El token de arranque se consume durante el registro y no puede reutilizarse. Si el registro falla y necesitas reintentarlo, genera un nuevo token desde step-ca. Consulta Registro del agente para solucionar problemas.
5

Ejecuta el agente

Una vez registrado el host, inicia el bucle de renovación:
certplane-agent run --config /etc/certplane/agent.yml
Al iniciarse, el agente:
  1. Genera una nueva service.key para cada entrada de certificado.
  2. Construye un CSR con los nombres DNS de tu configuración.
  3. Se conecta al broker por mTLS presentando identity.crt como certificado de cliente.
  4. El broker verifica la identidad, comprueba la política y devuelve un certificado en caché o solicita uno nuevo a Let’s Encrypt mediante ACME.
  5. El agente escribe el certificado, la cadena y la cadena completa en las rutas configuradas y ejecuta el reload_command que hayas especificado.
El agente sigue ejecutándose y vuelve a comprobar la expiración de cada certificado configurado. Renueva un certificado de servicio cuando queda menos del tiempo renew_before (predeterminado: 720 horas). Para más detalles sobre el bucle de renovación y la integración con systemd, consulta Ejecución del agente.