Behavioral Change in Device Staging Using staging.py

Summary

A behavioral change introduced in the February 24, 2026 hotfix affects device onboarding when using the staging.py script across both physical and certain virtual platforms.

This change enforces validation between hardware and software serial numbers during the bootstrap process.

What Changed

With this update, Director now requires that the serial number provided during staging matches the platform-reported hardware serial number.

• If there is a mismatch, the device will fail to bootstrap

• Director will reject the request with a validation error

Reason for the Change

This enhancement was introduced to improve security by preventing unauthorized scenarios where:

• A hardware device’s serial number is modified

• The modified device is used to improperly bootstrap into the system

While this validation was designed primarily for physical devices, it also impacts certain virtual environments.

Impact on Virtual Environments

Some virtual platforms (such as AWS, Azure, VMware, GCP, and OCI) expose a hardware-like serial number or UUID at the hypervisor level.

If a user manually specifies a different serial number in staging.py using:

--serial-number <value>

and this value does not match the platform-assigned serial number, bootstrap will fail.

Workaround

To successfully onboard devices using staging.py, ensure that the serial number passed matches the platform-assigned hardware ID (UUID).

Step 1: Retrieve Hardware Serial Number

From CLI:

show system details | match Hardware

Example:

Hardware Details
  Hardware ID number  ec28bd6c-2daa-086d-79a7-acc4ebb29dd5

From VOS shell:

vsh details | grep "Hardware ID number"

Example:

[admin@Ohio-Site-1: ~] $ vsh details | grep "Hardware ID number" | awk '{print $NF}'
ec28bd6c-2daa-086d-79a7-acc4ebb29dd5
[admin@Ohio-Site-1: ~] $ 

Step 2: Use This Serial Number in staging.py

Example:

sudo python /opt/versa/scripts/staging.py \
--local-id <local ID> \
--remote-id <remote ID> \
--static <static IP> \
--controller <Controller IP> \
--gateway <gateway IP> \
--serial-number ec28bd6c-2daa-086d-79a7-acc4ebb29dd5

Note: If the hardware serial number or UUID contains spaces, enclose the value in double quotes when passing it to the --serial-number option.

Example

Retrieve the hardware ID:

[admin@demo: ~] $ vsh details | grep "Hardware ID number" | sed 's/.*Hardware ID number[[:space:]]*//'
VMware-56 4d 04 2f 0a 31 71 56-78 86 a5 bb e2 03 f8 fd
[admin@demo: ~] $

Run staging.py using the value in double quotes:

[admin@demo: ~] $ sudo python /opt/versa/scripts/staging.py --local-id SDWAN-Branch@provider-org.com --remote-id SDWAN-Controller1-staging@provider-org.com --dhcp -controller 192.168.211.1 --serial-number "VMware-56 4d 04 2f 0a 31 71 56-78 86 a5 bb e2 03 f8 fd"
[sudo] password for admin:
=> Setting up staging config
=> Checking if all required services are up
=> Checking if there is any existing config
=> Generating staging config
=> Config file saved /opt/versa/scripts/staging.cfg
=> Saving serial number
=> Check if control-plane is up and running
=> Loading generated config into CDB
=> Taking staging snapshot

[admin@demo: ~] $

Impacted by Platform and ZTP method

Future Update

This strict serial number validation is temporary.

A future hotfix will remove the requirement for the hardware and user-provided serial number to match in virtual environments.

Key Takeaways

• Serial number validation between hardware and software is now enforced during bootstrap

• Virtual platforms with hypervisor-assigned serial numbers are impacted

• Always use the platform-provided hardware serial (UUID) with staging.py

• Other ZTP methods remain unaffected