장치 이전(Device Migration)

1. 장치 이전이란?

장치 이전은 활성 Paid License의 기존 Unit을 기존 ODRE PQC 설치에서 새 설치로 옮기는 절차입니다. 새 장치는 자체 identity와 장치 키를 생성하며, 기존 장치의 private key, device.json, DPAPI 상태 또는 Gateway identity를 복사하지 않습니다. Trial 장치 이전은 지원하지 않습니다.

2. 언제 필요한가?

기존 state와 identity를 그대로 보존하는 업데이트는 장치 이전으로 처리하지 않습니다.

3. 이전 전 준비사항

새 장치에서 설치된 OS용 launcher의 register를 실행합니다. 표시된 Device Code를 Native 장치 등록·이전 페이지에 입력하고 License ID/Key를 확인한 뒤 기존 Unit 이전, 이전할 설치, 교체 사유를 선택합니다. 같은 작업과 같은 state-directory를 끝까지 유지합니다.

Windows 새 장치

$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

Linux 새 장치

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. 기존 장치 처리

기존 장치에 접근 가능한 정상 교체: 새 업무 트래픽 유입을 중단하되 Native는 drain 확인이 끝날 때까지 실행 상태로 둡니다. 포털에서 받은 odre-device-transfer-request.json을 기존 장치에 전달하고 다음 명령을 실행합니다. 이 요청 파일에는 private key나 License Key가 포함되지 않습니다.

Windows 기존 장치

& .\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

Linux 기존 장치

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

완료 후 기존 장치를 다시 시작하지 않습니다. 새 권한은 기존 Offline Lease가 만료될 때까지 발급되지 않을 수 있습니다.

기존 장치에 접근 불가: 동일한 포털 작업에서 접근불가 복구를 요청합니다. 새 장치에서 같은 register 작업을 이어서 동의를 확인하고 지원 승인을 기다립니다. 기존 Lease 만료 절차는 생략되지 않습니다.

5. 새 장치 활성화

새 장치에서 처음 사용한 것과 동일한 register 명령과 state-directory로 작업을 계속합니다. 제한 시간 안에 끝나지 않으면 identity를 초기화하거나 새 작업을 만들지 말고 같은 명령을 다시 실행합니다. 서버의 이전 commit과 새 장치 결속이 확인되면 Lease가 새 장치의 보호 저장소에 원자적으로 저장됩니다.

6. 이전 완료 확인

포털 상태가 APPLIED이고 Native가 로컬 Lease 저장을 확인한 뒤, 설치본의 status를 확인합니다. 이어서 Gateway → Core → Protected Handler 요청이 정상 처리되고 Handler가 요청당 한 번 실행되는지 확인한 후에만 새 장치에 트래픽을 엽니다. COMMITTED만으로 이전 완료나 업무 통합 성공으로 판단하지 않습니다.

7. 실패 시 처리 및 주의사항