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

# Hosts

> Bind a step-ca identity to the profiles it may request.

The `hosts` map binds each managed host's **machine identity** to the set of certificate profiles it can request.

```yaml theme={null}
hosts:
  edge01:
    identity: edge01.h.int.example.com
    profiles:
      - public_edge_main

  api01:
    identity: api01.h.int.example.com
    profiles:
      - api_san
      - public_edge_main
```

## Fields

| Field      | Type      | Required | Notes                                                            |
| ---------- | --------- | -------- | ---------------------------------------------------------------- |
| `identity` | string    | yes      | The CN of the host's identity certificate (issued by `step-ca`). |
| `profiles` | string\[] | yes      | Non-empty list of profile names the host may request.            |

The top-level map key (`edge01`, `api01`) is a human-readable label only — it appears in audit events and policy validation output. The broker authorizes by `identity`, not by label.

## Matching rules

* `identity` must be a stable CN — the agent presents it as the client certificate's CN over mTLS.
* Two host entries must not share the same `identity`. The policy compiler rejects duplicates.
* `profiles` must reference profiles that exist in the same policy file.
* An agent that asks for a profile not in its host's `profiles` list is rejected with an authorization failure, regardless of whether the profile itself exists.

## Adding a new host

1. Issue a `step-ca` bootstrap token for the new CN.
2. Add a host entry to the policy file:

   ```yaml theme={null}
   hosts:
     edge02:
       identity: edge02.h.int.example.com
       profiles:
         - public_edge_main
   ```
3. If `policy.watch: true` is set on the broker, the change goes live immediately. Otherwise restart the broker.
4. Deploy the agent and run `enroll` on the host.

## Removing a host

Delete its `hosts.<label>` entry. With `policy.watch: true` the change applies on next file change. The host's identity certificate may continue to be valid (`step-ca` decides that), but the broker will reject all of its issuance requests.

## Validate the host list

```bash theme={null}
certplane-broker -c /etc/certplane/broker.yml policy validate --policy /etc/certplane/policy.yml
```

The output includes the number of compiled identities:

```
policy ok: hash=abc123… profiles=2 identities=42
```