Skip to content

Enrollment

Enrollment is how a gateway first registers with an environment. The box presents a bootstrap token minted in that environment's portal, and every enrollment lands the device in the holding zone, from which an administrator assigns it to an organization.

Device identity

Identity is minted by Nexus at enrollment:

  • a gateway id of the form gw-xxxxxxxx, and
  • an API token, returned to the device once and stored by Nexus only as a SHA-256 hash.

The agent keeps both, with the Nexus and Realtime addresses it enrolled against, in /var/lib/edge-agent/identity.json, and authenticates with them from then on. Identity is per environment: dev, staging and production each mint their own.

MAC is metadata, not identity

The MAC address, hostname, architecture and agent version the box reports are recorded as metadata. The MAC is never used to identify or authenticate a gateway, and bootstrap tokens are not tied to one.

A box that reports the installer's generic hostname (digilan-gw) is named digilan-<id> instead (for gw-32b20ed5, digilan-32b20ed5), so units from one batch are distinguishable.

Bootstrap tokens

Mint tokens at Admin → Enrollment, kind Bootstrap token. A token looks like GW-XXXX-XXXX-XXXX-XXXX and is:

  • named, so you know which batch or installer it belongs to;
  • shown once, at creation; Nexus keeps only its hash;
  • revocable at any time, which stops further enrollments with it and leaves enrolled devices untouched;
  • usage-limited by Max uses:
Max uses Meaning
0 Unlimited: bake one token into an image and flash a whole batch
1 Single use
n Refused after n enrollments

The list on the same page shows each token's uses (3 / 10, or 3 / ∞) and whether it is exhausted or revoked.

A token authorizes a box to enroll. It does not decide which organization the box belongs to.

Device codes

Admin → Enrollment also creates device codes: single codes recorded against one MAC address, for other device types. Gateways use bootstrap tokens.

Enrollment flow

  1. An administrator mints a bootstrap token in the target environment.
  2. The token is baked into the install image as ENROLL_TOKEN (Build the install image), or passed to edge-agent setup --token on an installed box.
  3. On first boot rc.firsttime runs edge-agent setup --addr <nexus> --realtime <realtime> --token <token>, which calls Nexus Enroll.
  4. Nexus checks the token (exists, not revoked, not expired, uses left), mints the gateway id and API token, and creates the device with status holding and no organization. The token's use count goes up by one.
  5. The agent writes identity.json, then edge_agent is enabled and started.

Nexus refuses with a distinct error for an unknown token, a revoked one, an expired one, and one whose use limit is reached; setup prints it, and the first-boot log (/var/log/digilan-enroll.log) keeps it.

edge-agent setup does nothing on a box that already has an identity. To point an enrolled box at another environment, see Move a device between environments.

The holding zone

A newly enrolled device has status = holding and no organization. It is registered, connected and reporting, but belongs to no organization, so no customer sees it.

Find holding devices on Admin → Devices with the Holding filter, and assign them from there; see Device lifecycle. Separating enrollment from assignment lets you flash hardware in bulk with one token and decide ownership later.