Skip to main content

Bootstrap

Bootstrap lets Kerrigan recognize a bare DevKit as soon as it receives a DHCP lease, then SSH into the device and install everything needed for normal Fleet Manager registration.

The default bootstrap credentials are:

username: sima
password: edgeai

Flow​

  1. A DevKit gets a DHCP lease from the Kerrigan host.
  2. NetworkManager's dnsmasq runs /usr/local/bin/kerrigan-dhcp-lease-hook.
  3. The hook posts the lease to POST /v1/bootstrap/dhcp-lease with a generated bearer token.
  4. Fleet Manager normalizes the MAC address and checks whether the device is already provisioned.
  5. New devices appear in the default pool with state bootstrapping.
  6. Bootstrap workers wait for SSH, then compare the DevKit's UTC system clock with the Kerrigan host clock. When the difference exceeds 60 seconds in either direction, they set the DevKit clock from Kerrigan over SSH using the bootstrap account's sudo access and verify the correction.
  7. Workers validate network access, write agent config, install standard prerequisites including Git and wireguard-tools, and install the configured device bundle. They then inspect NVMe without modifying it. A namespace with an existing partition or recognized on-disk signature is mounted with sima-cli nvme remount. A namespace is automatically formatted only when it has no partitions and no recognized signatures. If inspection is inconclusive, bootstrap stops instead of risking existing data.
  8. When the device agent heartbeats, the target transitions to normal idle fleet state.

The clock check runs before HTTPS probes or downloads, so a newly booted device with an old clock can validate TLS certificates. Kerrigan's host clock is the reference and must be accurate. A device already within 60 seconds is left unchanged. This correction sets the system clock only; it does not disable NTP, change the timezone, or write the hardware clock. Existing NTP synchronization continues to maintain time after bootstrap.

Bootstrap events record the observed clock difference and successful correction. If reading, setting, or verifying the clock fails, bootstrap stops before network checks and follows its normal retry policy.

Duplicate Protection​

MAC address is the unique identity for bootstrap. If a DHCP lease arrives for a MAC that already belongs to a provisioned target, Kerrigan records a skipped bootstrap job and updates the target's latest IP without reinstalling anything. If the target's last heartbeat is stale, a worker waits briefly for the existing device agent to resume before changing the target to bootstrapping. A fresh heartbeat during that recovery window skips reinstallation. If no heartbeat arrives, Kerrigan continues with normal bootstrap so a reimaged device that kept the same MAC address can recover.

Stale Discovery Records​

Fleet Manager reconciles stale records at bootstrap startup and periodically at the DHCP lease scan interval. A target that has not been seen within the online threshold (30 seconds) no longer remains bootstrapping when its bootstrap jobs are terminal or missing: it becomes offline, retaining the last observation time and any recorded failure. A successful historical job alone does not prove that an agent is still online.

When a valid DevKit DHCP lease assigns an address to a different MAC, the old stale target's latest_ip is cleared. Authenticated DHCP del events likewise clear the stale association only when both MAC and IP match. These operations preserve target identity, pool assignment, and job history; devices are never merged solely because they used the same IP.

Recently seen targets, active bootstrap jobs, firmware updates, agent maintenance, and other active lifecycle states are left alone. Matched DHCP deletions are persisted in the Fleet Manager database and retried after protection ends, including across restarts. A newer heartbeat, a matching active lease, or a changed address supersedes the pending deletion. The pending-event table is created automatically when an existing database is opened. Lease scans recheck address ownership even for previously processed leases. Missing or unreadable lease files are not treated as proof of address deletion. When DHCP file scanning is disabled, terminal bootstrap state is still reconciled and DHCP hook events still work.

Error Handling​

Bootstrap jobs keep attempts, phase, error code, and event history. Common error codes include:

  • clock_read_failed
  • clock_sync_failed
  • ssh_unreachable
  • fleet_manager_unreachable
  • dns_unreachable
  • nat_unreachable
  • device_prerequisites_failed
  • nvme_remount_failed
  • nvme_inspection_failed
  • nvme_format_failed
  • nvme_mount_validation_failed
  • sima_cli_install_failed
  • device_agent_install_failed
  • agent_not_registered

Jobs retry with exponential backoff up to the configured maximum attempt count. Because DHCP can arrive before the DevKit has finished booting, each attempt waits up to KERRIGAN_BOOTSTRAP_SSH_TIMEOUT_SEC for SSH readiness before recording ssh_unreachable.

Host-Side Configuration​

Ubuntu setup generates:

  • KERRIGAN_BOOTSTRAP_DHCP_HOOK_TOKEN
  • /usr/local/bin/kerrigan-dhcp-lease-hook
  • /etc/NetworkManager/dnsmasq-shared.d/90-kerrigan-bootstrap.conf

Bootstrap is disabled automatically in host-only mode.