GUIDE · PREVIEW
EDIT ON GITHUB →
GUIDE / SER.58
source: docs/guide/services/Provisioner.md
Services

Provisioner

Role

The provisioner handles node enrollment: authenticating new hardware, delivering identity material, and serving boot images. It is NOT a permanently running service. The provisioner is pulled from shard storage on demand, requires an admin YubiKey or CAC to start, and shuts down when provisioning is complete.

When no provisioner instance is running in the org, no new nodes can be added. This is defense-in-depth: provisioning capability exists only when an admin deliberately activates it.

What It Does

  • Enrollment gateway: Receives TLS connections from preboot agents. Validates the admin's YubiKey/CAC (which serves as auth for the enrolling node -- the admin's physical token is the "send what you have" credential). Generates identity material (preboot_secret, Ed25519 keypair). Returns material over TLS.
  • Boot image serving: Serves the preboot UKI and generation images to enrolling nodes via PXE (TFTP) or direct TLS download. Images come from org shard storage -- the provisioner decrypts them to tmpfs for serving.
  • Cloud provisioning tokens: While the admin's YubiKey is present, the provisioner can generate short-lived, single-use tokens for VPS provisioning. These tokens enable out-of-band secret delivery: the VPS boots with a token baked into its cloud-init, the preboot consumes the token on first auth, and the token expires. No long-lived credentials for cloud provisioning.
  • Gossip announcement: When the provisioner starts, it announces to the org via gossip: "provisioning is active on node X." Other nodes know that enrollment is happening. When no provisioner is announced, the org ignores enrollment attempts entirely -- unknown preboot connections are rejected at the conn_auth layer.
  • Enrollment state management: Records pending enrollments (nonce + IP). Promotes pending -> confirmed when the main OS presents the nonce over WireGuard. Communicates enrollment confirmations to the maintainer via IPC.

Lifecycle

  1. Admin decision: An admin decides to provision new nodes.
  2. Pull from storage: The reconciler pulls the provisioner image from org shard storage. The image is encrypted with service-owned encryption; the key service provides the decryption key.
  3. Admin auth: The admin presents their YubiKey/CAC + PIN. The provisioner starts only with this physical authorization.
  4. Provisioning window: The provisioner runs, enrolls nodes, generates cloud tokens. The admin's YubiKey may remain inserted or the provisioner may operate on generated tokens for a configured window.
  5. Shutdown: Provisioning is done. The provisioner shuts down. Its scratch is destroyed. The gossip announcement is withdrawn. The org returns to "no provisioning active."

Why Not Tier 1

A permanently running provisioner is an always-open door for enrollment. If the provisioner code or its host node is compromised, the attacker can enroll malicious nodes into the org at will. Making the provisioner on-demand with physical YubiKey/CAC authorization means:

  • No provisioner = no enrollment surface. Most of the time, the attack surface for enrollment doesn't exist.
  • Admin physical presence required. A remote attacker can't start provisioning without the physical token.
  • Provisioning code is encrypted at rest. The provisioner binary lives in shard storage, encrypted. A compromised node doesn't have the provisioner code in memory unless an admin deliberately started it.

UKI Signing

The provisioner or the Build Service signs generation UKIs -- this is an org policy decision:

  • Build service signs: The build environment is controlled, the signing key is available during build. Simpler. But a compromised build service can sign malicious images.
  • Provisioner signs: Separation of concerns -- building and signing are different trust domains. The provisioner holds the org CA's signing key (via admin YubiKey). A compromised build service produces an unsigned image that the provisioner must independently approve.
  • Both viable. The org's threat model determines which is appropriate. Higher-security orgs separate the two.

Not the Admin Tool

The provisioner enrolls nodes into an existing org. It cannot create an org. The create-org capability exists only in the standalone admin tool (fortros-admin). The provisioner is a service on an org node; the admin tool creates the org. See Org Bootstrap for the admin tool's lifecycle, web UI, and migration to org-hosted admin.

Links