# 테라클론 공장초기화 계약

웹 `POST /api/v1/system/factory-reset`과 SW2 모니터는 동일한 `Store.FactoryReset`을 호출한다.
초기화 후 기본 계정은 `terauser / terauser` 하나다. 고객 계정과 사용자 정의 그룹, 로그인 세션/토큰/실패 기록, 주소 필터, 장비 설정과 보류 변경, 저장 인증정보, 고객 TLS 키와 인증서, 과거 로그와 내보내기, 진단 파일, 알림 전송/재시도 기록, 업로드된 펌웨어 패키지를 삭제한다. TLS 기본 키는 새로 생성한다.

설정 저장을 마친 후 기존 시스템 제어 서비스에 재부팅을 요청한다. 설치된 펌웨어와 제조사 업데이트 검증 키는 유지한다. 공장초기화 자체 및 다음 부팅에서 새로 발생한 시스템/감사 이벤트는 새 기록이다. 파일시스템 상의 삭제이며 저장 매체의 포렌식 보안 소거 기능은 아니다.

## 구현

- frontend 서버는 SQLite를 열지 않고 사용자·장비 데이터를 tera-api로 전달한다. 기존 로컬 계정 API와 터미널용 legacy 경로는 서버에 등록하지 않는다.
- 이전 설치의 `/var/lib/teraweb/frontend.db` 및 `/var/lib/tera-clone-demo-web/teraclone.db`와 `-wal`, `-shm`, `-journal`은 공통 초기화에서 정리한다.
- 인증 파일 로딩은 초기 계정 목록에 병합하지 않고 저장된 목록으로 교체한다. 재기동 시 admin 등 샘플 계정이 재생성되지 않는다.
- 일반 로그 삭제의 감사 로그 보호 정책과 공장초기화는 별도다. `preserve_on_factory_reset`은 false이며 true 설정은 거부한다.
- reset은 진행 중인 HTTP 변경을 기다리고, 완료 후 재부팅 전 추가 변경을 거부한다. 진단·알림 작업을 종료한 뒤 결과 파일과 재시도 상태를 지운다.
- 네트워크 기본 설정은 재부팅 시 적용되도록 저장한다. 기존 rollback snapshot/timer가 기본값을 다시 덮어쓰지 못하도록 제거한다.
- 초기화 중 삭제/저장/서비스 오류가 있으면 성공을 반환하지 않는다. 펌웨어 업그레이드 진행 중에는 초기화를 거부한다. 저장 장치 오류 시 이미 삭제한 데이터는 자동 복구되지 않는다.

## 함께 배포할 구성

`build/factory-reset-linux-arm64/`에 다음 ARM64 실행 파일을 빌드했다.

- tera-api (테라클론 API 설치 이름은 tera-clone-demo-api)
- tera-clone-demo-web
- tera-logd, tera-netd, tera-alarmd, tera-updated, tera-snmpd

API만 교체하면 이전 보조 서비스가 새로운 factory_reset 명령을 지원하지 않을 수 있으므로 함께 교체한다. clone 전용 alarmd 인스턴스에도 같은 alarmd 빌드를 사용한다. 웹 env의 TERACLONE_DB_PATH는 제거했다.

80 포트의 별도 teraWeb/8082 API가 계속 설치되어 있으면 해당 서비스에도 동일 소스의 변경을 통합해야 한다. 수정 대상은 tera_Clone_Demo 소스다. 2026-09-08 해당 웹/API와 보조 서비스 8개를 장비에 배포했다. 기존 별도 tera-web/tera-api 실행 파일은 교체하지 않았다. 장비의 수동 배포 백업 디렉터리나 다른 프로그램의 파일을 임의로 재귀 삭제하지 않는다.

## 검증

- 임시 저장소에 계정·세션·그룹·로그·비밀정보·고객 인증서·진단 파일을 넣고 초기화한 후 재개방: terauser/terauser만 로그인 성공, 이전 세션/계정 거부.
- 로그 네 종류(audit/system/port/link): 로그 서비스 소켓을 통한 삭제, 디스크 원문 제거, 재개방 후 빈 기록 검증.
- 네트워크 pending transaction/rollback 제거 및 재부팅용 파일 저장 검증.
- 알림 전송 기록과 재시도 상태: 재기동 후 복구되지 않음 검증.
- 업로드된 서명 펌웨어 패키지 삭제 및 현재 설치 버전 유지 검증.
- SQLite sidecar 삭제, 비관련 파일 보존, stateless frontend의 로컬 계정 생성 거부 검증.
- API 권한, reset 완료 후 쓰기 차단, SW2 모니터 호출 경로, 한국어/영어 안내와 프론트엔드 회귀 테스트 통과.
- ARM64 실행 파일 7개 빌드 완료. 실장비 서비스 배포·재시작 및 HTTPS/해시 검증을 완료했다. 공장초기화와 장비 재부팅 자체는 실행하지 않았다.

배포 백업: `/userdata/tera-backups/factory-reset-deploy-20260908-104450`. 배포 중 발견된 기존 updater 상태 파일의 `apply_policy` 호환성을 수정하고 회귀 테스트를 추가했다.

## Factory defaults correction (2026-09-08)

CAPTCHA defaults to enabled, including after factory reset and state reload. The 48 serial ports default to 9600 8N1; the COM5 management console stays at 115200. On-device checking after setting 9600 confirmed CR response on CH18, the only connected port. Login autofill uses username/current-password.

## PC clock synchronization (2026-09-08)

The first successful browser login with time.sync permission after API service startup submits PC UTC time through the existing tera-timed boundary. Synchronization precedes session issuance and retains the configured device timezone and NTP settings. Later logins do not override the clock again. Failed synchronization is audited and retried at the next authorized login. Browser access is required; no PC clock is available to the device while the PC/browser is disconnected. No public unauthenticated clock setter is exposed.