This page documents how to build a ZEDEDA Cloud hardware model for a new edge node, including a simpler alternative to the USB-round-trip and console/debug-shell methods.

Two “official” ways exist to pull hardware spec info off a node running EVE-OS:

• USB install method — boot the EVE-OS installer from USB; EVE-OS writes a best-effort model file back to the inventory partition of the USB stick. Requires physically getting the USB stick back after install.
• Console + debug shell method — get serial/KVM console access, drop into the EVE-OS debug shell, and run spec.sh manually. Requires ongoing console/KVM access to the device.

Both are fine if you have that physical/console access. The real problem shows up when you don't: a remote site, a device with no console port wired up, no one on hand to swap the USB stick back out, etc. In that case you're stuck — you can't SSH in to grab the info remotely, because SSH normally isn't available until the node is onboarded, and it can't be onboarded without knowing its hardware model. A third option that works over the network, with no console and no USB round-trip, would help a lot.

You don't actually need onboarding to get SSH. EVE-OS supports a bootstrap SSH config baked into the installer image itself, via files placed on the config partition before flashing. This gets you a root shell over the network the moment the node boots — no console, no USB round-trip, no onboarding.

• Docker running on your workstation.
• An SSH keypair (ssh-keygen -t ed25519 if you don't have one).

1. Create the config staging directory:

mkdir -p /tmp/config/GlobalConfig

1. Drop your public key in as authorized_keys:

PUBLIC_KEY_PATH=~/.ssh/id_ed25519.pub
cat "$PUBLIC_KEY_PATH" > /tmp/config/authorized_keys

1. Add the controller FQDN in a server file:

cat <<EOF > /tmp/config/server
zedcloud.zededa.net
EOF

1. Enable SSH via GlobalConfig/global.json (this file must exist for EVE-OS to load the bootstrap config at all):

cat <<EOF > /tmp/config/GlobalConfig/global.json
{
  "GlobalSettings": {
    "debug.enable.ssh": {
      "Key": "debug.enable.ssh",
      "ItemType": 3,
      "StrValue": "$(cat "$PUBLIC_KEY_PATH")"
    }
  }
}
EOF

  ''ItemType: 3'' = string value; ''debug.enable.ssh'' holds the actual public key, not a boolean.

1. Build the installer image with the config folder mounted in:

docker run -v /tmp/config:/in --rm lfedge/eve:latest installer_raw > installer-ssh.raw

1. Flash installer-ssh.raw to USB and boot the target device.

1. SSH straight in:

ssh -i ~/.ssh/id_ed25519 root@<DEVICE_IP>

Note: this bootstrap SSH access only works before onboarding. Once the node onboards, these settings are ignored. If you want to keep SSH access afterward, re-enable it through ZCLI:

zcli edge-node update <edge-node-name> --config="debug.enable.ssh:$(cat ~/.ssh/id_ed25519.pub)"

Once you have a shell, pull the same information the console/debug-shell method would give you, without needing physical access at all.

spec.sh

This produces a JSON blob (CPU count, memory, storage, and an ioMemberList of guessed adapters — VGA, USB, COM ports, NVMe, Ethernet, etc.). Save it, e.g. as MyModel.json. Treat it as a draft — EVE-OS's guesses are “best effort” and usually need correcting.

• Remove logo placeholders — logo_back/logo_front default to placeholder paths; blank them out or you'll get a cosmetic error.
• PCI devices (VGA, USB, Ethernet, etc.):

lspci -k

• IOMMU groupings (which devices share a passthrough group — matters for assigngrp):

find /sys/kernel/iommu_groups/ -type l

• Serial/COM ports:

dmesg | grep -i ttyS

• USB topology (to confirm which physical port maps to which controller):

lsusb
lsusb -t

Cross-check each entry in the ioMemberList against this output:

• Fix or fill in empty PciLong / Ioports / assigngrp values.
• Delete entries for ports that don't actually exist as separate controllers (e.g., a device with 4 physical USB ports but only 1-2 controllers in lspci/iommu output — the extra logical entries should be removed since they can't be independently passed through).
• Omit adapters you don't intend to model (e.g., NVMe, if not relevant).

Validate the final file with a JSON linter before uploading.

1. Copy the validated JSON into the ZCLI docker container:

docker cp /path/to/MyModel.json docker_containerID:/home/zcli

1. Create the hardware brand, if it doesn't already exist:

zcli brand create NAME --title=TITLE

1. Create the model, linking it to the JSON:

zcli model create NAME --hardware-details=PATH/TO/JSON --brand=BRAND [--title=TITLE]

1. To revise a model later, edit the JSON and:

zcli model update NAME [--hardware-details=PATH/TO/JSON] [--brand=BRAND] [--title=TITLE]

  Changes propagate to every edge node currently using that model.

With the model created, onboard the edge node in ZEDEDA Cloud (GUI or ZCLI): pick the Brand/Model, choose a Hardware Identity method (Edge Node Certificate from the USB inventory partition, Onboarding Key + serial number, or a single-use installer), and finish the flow.

Good to know: for lab/test nodes, ZEDEDA Cloud lets you onboard with *any* placeholder model just to get connectivity up — you don't strictly need the final model in hand before the first boot. That's a second way to sidestep the chicken-and-egg problem: onboard with a generic model + Onboarding Key/soft-serial (no cert extraction needed at all), then once online, correct/replace the model later. The SSH-image method above is still preferable when you want the *real* model nailed down before onboarding at all, e.g. for image reuse across a fleet of identical devices.

• Get an SSH-enabled EVE-OS image
• Compile JSON File for Hardware Model Manifests
• ZCLI: Upload and Create Hardware Models
• Onboard Edge Nodes using Models
• lf-edge/eve
• lf-edge/eve-api
• Terraform Registry: zededa/zedcloud
• zededa/terraform-provider-zedcloud