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: UUID on VMware may have spaces, please change it by replacing space with hyphon(-) as below

[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: ~] $

1. Backup original dmidecode binary
sudo mv /usr/sbin/dmidecode /usr/sbin/dmidecode.real
 
2. Create dmidecode wrapper
sudo tee /usr/sbin/dmidecode << 'EOF'
#!/bin/bash
/usr/sbin/dmidecode.real "$@" | python3 -c "
import sys, re
for line in sys.stdin:
    if 'VMware-' in line and re.search(r'[0-9a-fA-F]{2} [0-9a-fA-F]{2}', line):
        line = re.sub(r'(?<=[0-9a-fA-F]{2}) (?=[0-9a-fA-F]{2})', '-', line)
    sys.stdout.write(line)
"
EOF
sudo chmod +x /usr/sbin/dmidecode
 
3. Verify wrapper works
sudo dmidecode -s system-serial-number
# Should show: VMware-56-4d-04-2f-0a-31-71-56-78-86-a5-bb-e2-03-f8-fd
 
4. Update the cached serial file
NEW_SERIAL=$(sudo dmidecode -s system-serial-number)
echo -n "$NEW_SERIAL" | sudo tee /var/lib/vs/.serial
 
5. Regenerate hw_info.in
sudo bash /opt/versa/scripts/hwinfo.sh
 
6. Verify hw_info.in
grep serial /opt/versa/etc/hw_info.in
# Both hw_serial and serial should show the hyphenated value
 
7. Verify in VOS CLI
vsh details | grep Hardware
# Hardware ID number should show hyphenated serial

[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: ~] $

Impacted by Platform and ZTP method

Future Update

This strict serial number validation is temporary.

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

Important points

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

• Virtual platforms with hypervisor-assigned serial numbers are affected

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

• Other ZTP methods remain unaffected