Device Migration

1. What is device migration?

Device migration moves an existing Unit of an active Paid License from an old ODRE PQC installation to a new installation. The new device creates its own identity and device keys. Do not copy private keys, device.json, DPAPI state, or Gateway identity from the old device. Trial migration is unsupported.

2. When is it needed?

• Server replacement: the same License Unit must run on a replacement server.
• OS reinstallation: the existing installation identity and protected state cannot be retained.
• Hardware change: the installation must register with a new device identity.

An update that preserves the existing state and identity is not a device migration.

3. Before migration

• Have the Paid License ID and License Key ready. Never place the License Key on a command line or in a support message.
• Install the approved delivery on the new device and use a new-device state directory.
• Decide whether the old device is accessible for a normal replacement or unavailable for recovery.
• Do not delete or reset the old identity or state.

Run register with the installed OS launcher on the new device. Enter its Device Code at the Native registration and transfer portal, verify the License ID/Key, then choose Transfer an existing Unit, the source installation, and the replacement reason. Keep the same operation and state directory throughout.

New Windows device

$state = 'C:\ProgramData\ODRE\native-commercial'
$trust = '<APPROVED_TRUST_JSON_ABSOLUTE_PATH>'
$trustPin = '<INDEPENDENT_TRUST_SHA256>'
& .\runtime\python.exe .\odre-native.py register `
  --state-directory $state `
  --trust-config $trust --trust-pin $trustPin

New Linux device

state="$HOME/.local/state/odre-pqc/native-commercial"
trust='<APPROVED_TRUST_JSON_ABSOLUTE_PATH>'
trust_pin='<INDEPENDENT_TRUST_SHA256>'
python3.12 ./odre-native-ubuntu.py register \
  --state-directory "$state" \
  --trust-config "$trust" --trust-pin "$trust_pin"

4. Handle the old device

Normal replacement: stop new business traffic but keep Native running until drain confirmation completes. Download odre-device-transfer-request.json from the portal, move it to the old device, and run:

Old Windows device

& .\runtime\python.exe .\odre-native.py transfer-release `
  --state-directory $state `
  --trust-config $trust --trust-pin $trustPin `
  --transfer-request ".\odre-device-transfer-request.json" --confirm-stop

Old Linux device

python3.12 ./odre-native-ubuntu.py transfer-release \
  --state-directory "$state" \
  --trust-config "$trust" --trust-pin "$trust_pin" \
  --transfer-request "./odre-device-transfer-request.json" --confirm-stop

Do not restart the old device after release. New authority may wait for all old Offline Leases to expire.

Old device unavailable: request source recovery in the same portal operation. Continue the same register operation on the new device to confirm consent, then wait for support approval and old Lease expiry.

5. Activate the new device

Continue with the same register command and state directory. If it times out, do not reset identity or create another operation; run the same command again. After the server commit and destination binding pass, Native stores the Lease atomically on the new device.

6. Confirm completion

Wait for portal state APPLIED and Native confirmation of local Lease storage, then check the installed product's status. Verify a Gateway → Core → Protected Handler request and one Handler execution per request before opening traffic. COMMITTED alone is not migration completion or application-integration proof.

7. Failures and cautions

• LICENSE_UNIT_LIMIT: transfer an existing Unit or obtain more capacity.
• SUPPORT_PENDING: wait for new-device consent and support approval.
• WAITING_OLD_LEASE: wait for the old Offline Lease to expire.
• If a Device Code expires, check the same Native operation first. Do not create a second operation after selection is fixed.
• After interruption or a lost response, recover with the same register operation and state directory.
• Never copy, delete, or reset identities, private keys, state, or Lease files between devices.
• Do not bypass verification or force the old device back into service.