On-Prem VM Registration

Deploy AdWAN OS as a virtual machine on Proxmox, VMware vSphere, Microsoft Hyper-V, or generic KVM when you need a data-center hub, lab edge, or PoC — without bare-metal serial whitelisting or public-cloud metadata.

When to Use On-Prem VM vs Other Paths

Deployment	Registration path	Token / identity
Bare metal	Serial whitelist → auto POST /v1/devices/add	Hardware serial
Public cloud	Cloud-init / user-data → POST /v1/devices/cloud/register	Cloud instance ID + bootstrap token
On-prem VM	Cloud-init, guestinfo, or custom data → POST /v1/devices/vm/register	DMI system UUID + VM bootstrap token

On-prem VM edges are best suited for DC hub / PoC workloads. Branch CPE replacement typically remains bare metal or cloud.

Architecture Overview

Portal Workflow

1. Go to Devices → Create Device.
2. Select a physical site (not a cloud site).
3. Choose On-Prem VM as the deployment type.
4. Pick your hypervisor: Proxmox/KVM, VMware, Hyper-V, or generic KVM.
5. Configure token limits (max uses, expiry) and click Next.
6. Copy the bootstrap token and the hypervisor snippet before leaving the page.

VM-only tokens are rejected by the cloud registration endpoint, and cloud-only tokens are rejected by the VM endpoint.

Token Injection by Hypervisor

The contract is the same everywhere: write the token to /etc/adwan/cloud-token with mode 0600, then run adwan-agent.

Proxmox / KVM (cloud-init)

Use the #cloud-config snippet from the portal as Cloud-Init or Custom Cloud-Init Drive when creating the VM:

#cloud-config
write_files:
  - path: /etc/adwan/cloud-token
    content: "<bootstrap-token>"
    permissions: "0600"
    owner: root:root
runcmd:
  - adwan-agent --env production

AdWAN OS images include cloud-init with datasource order: Ec2, NoCloud, ConfigDrive, VMware, None.

VMware vSphere (guestinfo)

Set VM configuration parameters before first boot:

Parameter	Value
guestinfo.adwan.token	Bootstrap token
guestinfo.adwan.env	production or staging

vSphere UI: VM → Edit Settings → VM Options → Advanced → Configuration Parameters.

govc example:

govc vm.change -vm "AdWAN-Edge-01" \
  -e guestinfo.adwan.token="<bootstrap-token>" \
  -e guestinfo.adwan.env="production"

AdWAN OS runs open-vm-tools and a first-boot helper that reads guestinfo into /etc/adwan/cloud-token.

Microsoft Hyper-V (custom data)

Save the portal snippet as adwan-bootstrap.sh, then attach as Custom Data on a Gen2 VM:

$script = Get-Content -Raw -Path .\adwan-bootstrap.sh
$bytes = [System.Text.Encoding]::UTF8.GetBytes($script)
Set-VM -Name "AdWAN-Edge-01" -CustomData ([Convert]::ToBase64String($bytes))
Start-VM -Name "AdWAN-Edge-01"

VM Identity and Serial Format

The agent collects:

1. Primary: DMI system-uuid from /sys/class/dmi/id/product_uuid (when available).
2. Fallback: /etc/machine-id.

Registration payload includes hypervisor, vm_uuid, hostname, SSH keys, and system info. The platform assigns serial:

vm-{hypervisor}-{uuid}

Example: vm-proxmox-a1b2c3d4-e5f6-7890-abcd-ef1234567890

Hypervisor detection on the agent:

Signal	Mapped hypervisor
/etc/pve-version present	proxmox
DMI vendor VMware	vmware
DMI vendor Microsoft	hyperv
Other virtualization	kvm

Proxmox Lab E2E Checklist

Use this checklist to validate a full registration in a lab.

Prerequisites

• AdWAN OS QCOW2/raw image imported into Proxmox storage
• Physical site created in the portal (not a cloud site)
• Network: VM can reach the platform API and controller on HTTPS

Steps

1. Portal: Devices → Create Device → select lab site → On-Prem VM → Proxmox → generate token
2. Proxmox: Create VM (2 vCPU, 4 GB RAM minimum recommended for lab)
3. Proxmox: Attach AdWAN OS disk; add Cloud-Init drive if using NoCloud
4. Proxmox: Paste portal #cloud-config into Cloud-Init Custom YAML (or use CI user-data field)
5. Do not power on until token is injected
6. Start VM and open console
7. Verify first boot:
   • /etc/adwan/cloud-token exists, mode 600
   • journalctl -u adwan-agent or first-boot log shows VM registration path
8. Portal: Device appears within ~5 minutes with serial vm-proxmox-...
9. Portal: Device assigned to correct site; status becomes operational after provisioning

Troubleshooting

Symptom	Likely cause	Action
Agent runs bare-metal path	Token missing before boot	Recreate VM; inject token via cloud-init before start
401 / invalid token	Expired or wrong deployment target	Generate new VM token (deployment_target=vm)
Cloud register attempted	Token on cloud IMDS VM	Use VM token on virt without IMDS, or cloud token on AWS/Azure/GCP
No DMI UUID	Some VM configs hide UUID	Agent falls back to machine-id; ensure UUID stable across reboots
Device not in portal	Network / API unreachable	Check DNS, firewall, adwan-agent --env staging vs production

Manual re-run

If first boot missed the token window (up to ~180s wait on virt), write the token and re-run:

mkdir -p /etc/adwan
echo "<token>" > /etc/adwan/cloud-token
chmod 600 /etc/adwan/cloud-token
adwan-agent --env production

API Reference (operators)

Create VM bootstrap token (same endpoint as cloud tokens):

POST /v1/devices/cloud/tokens/
Content-Type: application/json

{
  "site_id": 123,
  "deployment_target": "vm",
  "hypervisor": "proxmox",
  "max_uses": 1,
  "expires_in_hours": 24,
  "label": "Proxmox DC hub"
}

Register VM (called by agent):

POST /v1/devices/vm/register
Authorization: Bootstrap <token>
Content-Type: application/json

{
  "hypervisor": "proxmox",
  "vm_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "hostname": "vm-proxmox-7890abcd",
  "public_key": "...",
  "system_info": { ... }
}

Roadmap (v2)

Portal-driven deploy from linked hypervisor accounts (Proxmox API, vCenter, Hyper-V) is planned for a future release. v1 is token + copy-paste snippets only.

Related Documentation

• Cloud Provider Integration — AWS/Azure portal deploy
• Getting Started — bare metal serial whitelisting