Skip to content

Re-enrolling a Site

Re-enrollment recovers the existing site in place when it has lost its local registration. It issues a fresh client certificate and key for the same identity and relinks to the original hub_site record. The site keeps its identifier, subdomain, ACLs, tags, and full audit history. Only the certificate is rotated.

A site loses its local registration through a reinstall, a disk failure, a wiped qie.home, or a corrupted hub_registration row. It can no longer reach the Hub, and Add New Client is the wrong tool for getting it back. Add New Client mints a new site identity and leaves the original hub_site row orphaned, along with its audit history, access grants, and subdomain.

Re-enrollment vs. automatic renewal

Routine certificate renewal happens automatically over the live tunnel and needs no operator action. Re-enrollment is the out-of-band recovery path for when there is no tunnel to renew over because the credentials are gone.

Hub side: generate a recovery bundle

  1. On the Sites Dashboard, select the site that lost its registration. The Re-enroll toolbar button enables once a row is selected.
  2. Click it and confirm. The Re-enroll / Recover Registration confirmation names the site. On confirm the Hub generates a recovery .qcb, a full bundle (CA cert, register/tunnel URLs, and the site's existing identity + subdomain, all read-only) flagged reenroll, and downloads it once. Audited as BUNDLE_REISSUED.
  3. Deliver the .qcb to the site administrator over a trusted channel, exactly as for first-time enrollment.

Note

Only one recovery bundle per site may be outstanding at a time. If one has already been issued and not yet redeemed, Re-enroll refuses with A recovery bundle for this site is already outstanding. Cancel the existing one under Pending Bundles first, so the site cannot be re-keyed by whichever bundle happens to arrive.

The recovery bundle does not change the site's enabled/disabled state. A disabled site stays disabled until you re-enable it.

Recovery bundles are blocked during a CA rotation

Like new enrollment, re-enrollment is blocked while a CA rotation is in progress (it signs a certificate). Complete or retire the rotation first.

Site side: import the recovery bundle

The site administrator imports the recovery .qcb through the same Register with Hub dialog used for first-time enrollment. There is no separate screen. If the QIE still has an existing registration (for example, you are deliberately re-keying a working site rather than recovering a lost one), the dialog warns before overwriting it.

On Confirm, instead of creating a new site the Hub matches the bundle's site identifier to the existing hub_site row and replaces that row's certificate in place. The old cert immediately stops being accepted, the new cert is installed, and the tunnel reconnects under the original identity. The Hub audits SITE_REKEYED, and the site's history on the dashboard is unbroken.

Compromise vs. loss

Re-enrollment does not revoke the old certificate at generation time: it is simply replaced when the site re-registers. If a site is being re-keyed because its key was compromised (not merely lost), also Revoke the old certificate from the Sites Dashboard so a stolen copy cannot reconnect in the meantime.