Flashing & Assigning a Device¶

The end-to-end path for bringing a new gateway online: mint a token, build and flash the installer, boot the box, then assign it to the organization it belongs to.

Installing a box and deciding who owns it are separate steps. A technician can flash and rack a device knowing nothing about the customer; an administrator assigns it from the portal afterwards. A freshly enrolled device therefore belongs to no organization: it waits in the holding zone until someone assigns it.

flowchart LR
    A[Mint bootstrap token] --> B[Build USB image<br/>token + environment baked in]
    B --> C[Write image to stick]
    C --> D[Boot device<br/>unattended OpenBSD + agent install]
    D --> E[First boot: agent enrolls<br/>→ holding zone]
    E --> F[Admin assigns device<br/>→ organization]

1. Mint a bootstrap token¶

In the portal, open Admin → Enrollment, choose Bootstrap token, give it a name and a Max uses (0 = unlimited), and create it. The value is shown once: copy it now. It can be revoked later but never displayed again.

Any device that enrolls with the token lands in the holding zone, never directly in an organization, so a leaked token cannot put a device into a customer's account. Revoking a token blocks further enrollments and leaves enrolled devices untouched. See Enrollment.

2. Build the installer image¶

The image is built per environment and per token: the enrollment token and the Nexus/Realtime addresses are baked in at build time, so one image serves a whole batch for one environment. Build it with the digilan/provisioning/openbsd-autoinstall repository. Pick the console variant that matches the hardware (CONSOLE=serial for a headless box with a COM port, CONSOLE=vga for one with a monitor).

See Build the install image for the commands and options.

3. Write it to a USB stick¶

Use balenaEtcher or dd. See Write the image to a USB stick.

4. Boot the device¶

Boot the box from the stick with the console you built for attached. It installs OpenBSD to sd0 with no keystrokes, reboots, and on first boot enrolls itself and starts the agent. Progress is printed on the console and kept in /var/log/digilan-enroll.log.

Pull the stick at the first reboot

Nothing prompts during the install, so a box that still boots USB ahead of its internal disk reinstalls itself in a loop. Remove the stick at the first reboot, or put the internal disk first in the boot order.

The device needs a working WAN with DHCP on its first NIC at first boot; enrollment waits up to 60 seconds for a default route.

5. Confirm it reached the holding zone¶

Open Admin → Devices and filter by Holding. The new device appears with its hostname and hardware details within a minute or two of first boot.

If it does not appear:

Look at the console of the box. Every boot ends with a status box (digilan-status) showing whether it is enrolled, whether the agent runs, and whether Nexus is reachable from it.
Not enrolled, Nexus unreachable — no WAN, no DHCP, or DNS failing.
Not enrolled, Nexus reachable — the token is revoked, used up, expired, or belongs to another environment.

6. Assign it to an organization¶

On Admin → Devices (filter Holding), pick the destination organization and assign the device, or select several and assign them together. The device leaves the holding zone and appears under that organization, where its members can see and manage it.

Assigning does not touch the device's running configuration; it only sets which organization owns it. A device assigned to the wrong organization can be moved. See Device lifecycle.

Hardware for a device you already configured

If the device was created ahead of time (status prepared), do not assign the new unit. Use Connect on it instead, so it takes over the prepared device's id and configuration. See Create device and Connect.

Recap¶

Step	Where	Result
Mint token	Admin → Enrollment	A multi-use secret for the installer
Build image	`provisioning/openbsd-autoinstall`	An image with OS, agent, token and environment
Flash	balenaEtcher or `dd`	A bootable stick
Boot	The device	Unattended install, then self-enrollment
Check	Admin → Devices, filter Holding	Device visible, unassigned
Assign	Admin → Devices	Device owned by the right organization