Skip to main content

Re-enrolling a machine

A machine re-enrolls whenever the agent starts without a credential file but with an API key. It reclaims its existing record rather than creating a new one.

When it happens​

  • You deleted the credential file.
  • You rebuilt the machine but kept its hostname.
  • You moved the credential path and the agent found nothing at the new location.
  • You revoked the machine and want it back.

What it does​

Watchtower matches the incoming hostname and hardware identifier against your existing machines. On a match it reuses that record and issues a new secret. The old secret stops working immediately.

The record keeps its history, its labels, and its availability data. From the console's point of view nothing changed except that the machine reconnected.

Bringing back a revoked machine​

Revoking deletes the machine's credential but keeps its record. To bring it back, run the agent again with an API key set — it re-enrolls into the same record and picks up where it left off.

When you get a duplicate instead​

If the hostname or the hardware identifier has changed, the match fails and you get a second record — the old one, now silent, and a new one reporting.

This is the intended failure direction. A miss costs you a duplicate record you can delete; a false match would hand one machine's identity to another.

Common causes:

  • The machine was renamed.
  • The machine was rebuilt in a way that changed its hardware identity — a new virtual machine rather than a reinstall on the same one.
  • You are running a clone of an imaged machine.

Delete whichever record is stale from the machine's page in the console.

Rotating a machine's secret deliberately​

There is no rotate button. Delete the credential file and restart the agent — the machine re-enrolls and receives a fresh secret. That is the rotation.

Do this if you think the credential file was exposed. Revoking the machine first closes the window between exposure and rotation, at the cost of a gap in reporting.