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

# Registra el agente

> Registro único que vincula un host a un certificado de identidad emitido por step-ca usando un token de arranque.

El registro se ejecuta una vez por host y produce el par `(identity.key, identity.cert)` que el agente usa en cada llamada al broker.

## Qué hace el registro

`certplane-agent -c <config> enroll`:

1. Toma un lock en `<state_dir>/agent.lock`.
2. Se niega a correr si `identity.cert` ya existe.
3. Genera una clave ECDSA P-256 en `identity.key` (modo `0600`) si falta; la reutiliza si existe.
4. Lee el token de arranque desde `identity.bootstrap_token`.
5. Construye un CSR con `CN = identity.name` y lo envía a `step-ca` en `identity.step_ca.url`, verificando el servidor con `identity.step_ca.fingerprint` o `identity.step_ca.root_ca_bundle`.
6. Escribe el certificado devuelto en `identity.cert` y **borra el archivo del token**.

El lock y la comprobación de existencia hacen seguro `enroll` desde Ansible — reintentar sobre un host ya registrado falla rápido.

## Genera un token de arranque

En el host de `step-ca`:

```bash theme={null}
step ca token edge01.h.int.example.com
```

El CN debe coincidir con `identity.name` en la configuración del agente. Los tokens son de un solo uso y de corta duración.

## Coloca el token en el host

```bash theme={null}
install -o certplane -g certplane -m 0600 /dev/stdin /etc/certplane/bootstrap-token <<< "$TOKEN"
```

El role de Ansible hace esto con `no_log: true` solo si falta el certificado de identidad.

## Configuración de identidad del agente

Campos mínimos para el registro:

```yaml theme={null}
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: /etc/certplane/ca/agent-identity-ca-bundle.crt
  bootstrap_token: /etc/certplane/bootstrap-token
  step_ca:
    url: https://ca.int.example.com
    fingerprint: "sha256:aabbcc..."
    # O root_ca_bundle: /etc/certplane/ca/step-ca-root.crt
    timeout: 10s
```

Hay que dar `step_ca.fingerprint` o `step_ca.root_ca_bundle`. Esquema completo en [Configuración del agente](/es/configuration/agent).

## Ejecuta el registro

```bash theme={null}
certplane-agent -c /etc/certplane/agent.yml enroll
```

Si todo va bien, el agente escribe `identity.crt` y borra el token. El host queda listo para el bucle de renovación.

## Valida la configuración sin registrar

```bash theme={null}
certplane-agent -c /etc/certplane/agent.yml check
```

`check` valida el YAML, aplica defaults, ejecuta la misma lógica `Validate()` que usa el agente al arrancar y confirma que los archivos existen. No contacta `step-ca` ni al broker.

## Solución de problemas

<AccordionGroup>
  <Accordion title="identity cert already exists at ...">
    El registro es one-shot. Para repetirlo, borra `identity.cert` y `identity.key`, genera un token nuevo y vuelve a ejecutar `enroll`.
  </Accordion>

  <Accordion title="reading bootstrap token: no such file or directory">
    Falta el archivo de token en `identity.bootstrap_token`. En Ansible, suele significar que no se definió `certplane_agent_bootstrap_token` para este host.
  </Accordion>

  <Accordion title="bootstrap token is empty">
    El archivo existe pero solo contiene espacios. Regenera con `step ca token ...`.
  </Accordion>

  <Accordion title="enrolling with identity CA: x509: certificate signed by unknown authority">
    El TLS de `step-ca` no es de confianza. Define `identity.step_ca.fingerprint` con el SHA-256 de la raíz, o `identity.step_ca.root_ca_bundle` con un PEM que la contenga.
  </Accordion>

  <Accordion title="el registro funcionó pero el siguiente run falla autenticándose al broker">
    El `server.mtls.agent_ca_bundle` del broker debe confiar en la CA que firmó `identity.cert`. Si rotaste la intermedia de `step-ca` tras desplegar el broker, redespliega el bundle.
  </Accordion>
</AccordionGroup>

## Siguiente: ejecutar el agente

[Ejecutar el agente](/es/setup/agent-run) cubre el subcomando `run`, el timer de `systemd` y el modelo de renovación.