notParsec / 문서전체 문서

설명·설계 문서

Ubuntu 구현·운영 검증 · 2026-09-20

design/UBUNTU_OPERATIONS.ko.md

출처: 현재 작업 폴더 · 원문 다운로드

이 문서의 목차

시작 main: 4789730db48b190403969704921d612cd4a28786. 새 checkout: /home/ahn/notparsec (workspace와 같은 부모). 기존 checkout/작업 변경은 없었다. 기존 ahn 계정의 SSH 키로 같은 GitLab 저장소에 접근했다. 현재 origin은 ssh://git@127.0.0.1/root/notparsec.git이다. 인증정보를 URL/소스에 넣지 않았다.

서버 구현 commit: d20cdc6f8a458012565dcff7f610a1c4071ca2ed, 최종 후보 만료 보정 commit: bc9333e62d4c4585551a9db98e6e066845c7129e (버전 0.1.0, schema 3). 최종 서버 코드와 일치하는 native release를 다시 빌드하고 TLS/WSS를 검증했다. /opt/notparsec/notparsec-control-server에 이 native release를 설치했다. 서버 SHA-256은 d354130e9dbda6f87fb2f39996e05189c90e390bfa2de1080a6c2ce7718d7ff5다.

배포 상태

운영 설치와 공개 HTTPS/WSS 검증을 완료했다. 재개 시 실행 계정은 root(uid=0)였고 경로 접근·설치 권한이 확인됐다. 시작 Git은 main의 acb927790b3f7ac16124098a7581d1565228eb95, 변경 파일 없음이며 git ls-remote로 origin/main도 같은 commit임을 확인했다. 앞선 세션의 sudo/샌드박스 권한 문제는 현재 작업을 막지 않았다.

bash deploy/ubuntu/install.sh → python3 deploy/ubuntu/configure-nginx.py로 전용 사용자·systemd·backup timer·기존 Nginx 경로를 적용했다. 운영 origin은 https://n3m.kr, 내부는 127.0.0.1:18080이다. 공개 /health/live는 200/alive, /health/ready는 200, 미인증 /v1/devices는 401이다. /v1/ 자체는 목록 API가 아니므로 health 판정에 쓰지 않는다.

공개 인증 시험에는 최초 설치의 빈 운영 DB를 보존한 채 runtime systemd override로 별도 /var/lib/notparsec-validation-* DB/키를 사용했다. 검증 뒤 override와 검증 상태를 제거하고 원래 운영 DB/키 및 backup timer로 복귀했다. 운영 등록 기기는 0개다. 코드/키/token 원문은 Git·보고서에 보관하지 않았다. 재현 절차는 deploy/ubuntu/verify-public.py, 실제 요청 시험은 scripts/smoke_public.py다. 실제 기기가 있는 운영 서버에서는 이 초기 배포 drill을 거부한다.

Cloudflare 레코드·proxy·보안 설정 추가 변경은 필요하지 않았다. 기존 Cloudflare edge를 통한 HTTPS/WSS를 서버에서 호출해 검증했으며 별도 외부 회선의 Windows 시험은 아니다. Python 기본 User-Agent 요청은 HTTP 403/error 1010으로 거부됐고 앱 이름/버전을 명시하면 통과했다. 이는 Cloudflare의 클라이언트 서명 차단 설명과 일치한다. 시험과 공통 Rust HTTP 클라이언트에 notParsec/0.1.0 식별자를 사용했다. 기존 Rust 요청 실패를 재현한 결과는 아니며, 최신 소스의 실제 Linux Rust CLI 등록·heartbeat·목록 조회를 공개 경로에서 확인했다. Windows EXE 재빌드·실제 GUI 시험은 남았다.

초기 Nginx 설정 백업은 /var/backups/notparsec/nginx-1789922360206206033에 보관했다. 재설치/rollback과 세부 결과는 배포 근거 JSON을 따른다.

서버 조사

항목 직접 확인한 결과
OS/CPU Ubuntu 24.04.4 LTS, Linux 6.8.0-136-generic, Intel N100, x86_64, 4코어/4스레드
자원 (착수 시점) RAM 15GiB, available 약 10GiB; root 98G 중 39G 여유; swap 4GiB 중 1.6GiB 사용
시간 UTC, system clock synchronized=yes, NTP active
빌드 도구 Git, GCC/build-essential, pkg-config, CA, Python 3.12, OpenSSL 준비됨. Rust 1.93.1 rustfmt/clippy 추가 설치. 작업 수 2
기존 서비스 호스트 Nginx systemd, GitLab Omnibus/runit, workspace systemd 127.0.0.1:3100, ops-monitor 127.0.0.1:3000
Nginx /etc/nginx/nginx.conf → conf.d/.conf + sites-enabled/; default/gitlab/n3m.kr/works.n3m.kr 활성. Docker 실행 파일 없음, Nginx는 호스트 서비스
포트 80/443 Nginx, 22 SSH, loopback 8080 이미 점유. 18080은 설치 전 비었으며 현재 notParsec가 loopback에서만 수신
SSH 내부 0.0.0.0:22 및 [::]:22 실제 수신. 서버에서 공인 주소 9423과 로컬 22의 SSH handshake를 비교해 동일한 Ed25519 host key 확인. hairpin 경로 근거이며 공유기 규칙 직접 열람/별도 외부 회선 시험은 미검증
네트워크 Ubuntu LAN 192.168.50.13/24, gateway 192.168.50.1. 공인 IP가 서버 NIC에 직접 붙은 배치는 아님
방화벽 root 조회: UFW inactive, nft ruleset 출력 없음, fail2ban sshd jail 1개. 공유기 규칙 직접 열람/별도 외부 회선은 미검증. 방화벽 변경 없음
DNS n3m.kr은 Cloudflare A/AAAA 응답. origin 222.107.251.147과 구분
TLS 공개 HTTPS curl 검증 0; 로컬 origin SNI n3m.kr 인증서 Let's Encrypt YE1, 유효 기간 2026-09-17~2026-12-16; SAN n3m.kr/www/monitor/works
갱신 /etc/letsencrypt/renewal/n3m.kr.conf: Certbot nginx authenticator/installer, certbot.timer enabled. certbot renew --cert-name n3m.kr --dry-run --non-interactive 성공: 기존 4개 SAN 전체. 실제 운영 인증서는 교체하지 않음
경로 충돌 기존 n3m.kr / 정적 사이트 200, /gitlab/ 302, 후보 API/health 404. 기존 설정에 /v1 및 /health location 없음

시험 결과와 범위

검증 결과 / 근거
Rust 1.93.1 fmt/clippy/test/build --locked Ubuntu에서 통과. Linux workspace 23개 시험; Windows 전용 GUI/GPU/DPAPI 시험을 Linux 성공으로 세지 않음
서버 전용 native release bash scripts/build-ubuntu.sh 통과. ELF64 x86-64 GNU/Linux, 의존성 libc/libm/libgcc_s/loader. Windows GUI/GPU는 server dependency tree에 없음
기존 QUIC 인증 smoke_auth 통과: 올바른/잘못된 비밀번호, 인증서 고정, 비밀번호 교체, 재접속 실패 제한. 영상 없음
등록/인증/lease/폐기 smoke_control 및 서버 unit tests 통과. 등록 코드 만료/단일 소비/서명·challenge 재사용 거부, 실제 31초 대기로 lease 만료, 미인증 401, 실제 CLI 장치와 키의 백업/복원·재시작 후 신원·추가 폐기 유지
WSS 실제 TCP WebSocket test와 임시 Nginx TLS/WSS 통과. 인증, snapshot/revision, 새 generation, 이전 close 경합, queue overflow 종료, 폐기 연결 종료, 서버 종료
세션/ticket/후보 승인·취소 경합, 멱등 요청, 제3자 404, 승인 전 후보 거부, ticket 재사용/다른 세션/잘못된 peer 증명/만료 거부, 비밀번호 확인 대기, 양쪽 시작 보고, 철회·ACK, 후보 TTL/세대/개수/주소 제한 통과
네트워크 단절 테스트 socket 종료·재연결 및 서버 재시작 통과. 세션/권한 만료는 deadline 변경으로 경계 시험. 실제 Windows의 120초 watchdog/외부 회선 단절은 미검증
공개 방어 임시 Nginx에서 body 413, 요청 과다 429, URL token 거부, safe access log에 token/query 부재, TLS 검증과 원본 URI 전달 통과
백업/복원 3개 운영 시험 통과: WAL 미checkpoint committed 데이터, signing key/권한, 복원 이후 추가 폐기 병합, grant disable, 세션 무효화, 손상 backup 거부
rollback 시작 commit의 실제 schema 2 binary 별도 빌드. schema 3 DB 거부 후 schema 2 backup+binary 복원, readiness 200와 SIGTERM 0 확인
systemd 설치/시작/재시작/enable 설치/시작/재시작/enable 및 systemd-analyze verify 통과. notparsec 전용 사용자·hardening 적용. SIGKILL 1회 후 새 PID/readiness 200으로 자동 복구
운영 재설치·rollback 실제 /var/lib/notparsec와 설치 경로에서 pre-update 일관 bundle 생성 → 같은 schema 3/release 복원 → 원래 서명 키·DB integrity·health 유지. 다른 버전으로의 운영 downgrade는 미실행; schema 2 binary 시험은 격리 환경 결과
운영 backup timer enabled/active, 다음 calendar 예약 확인. 실제 systemctl start notparsec-backup.service 성공 및 bundle hash/integrity/0600 파일/0700 디렉터리 확인. 다음날 timer 자동 발동은 아직 관측하지 않음
운영 로그·요청 제한 설치된 Nginx에 40개/동시 12개 제한된 요청 시험: 422 12개, 429 28개. 공개 과대 body 413. notParsec 로그 실제 회전·새 로그 기록, 전용 journal namespace 8MiB와 상한 설정 확인
실제 재부팅 실행하지 않음
n3m.kr 공개 API/WSS 공개 TLS 검증, Ed25519 등록/인증/재사용 거부, 승인/ticket 서명/단일 소비/비밀번호 대기, WSS 101/snapshot/재연결/철회/폐기, 재시작/token 무효화, Rust CLI 통과. 별도 DB 사용
기존 서비스 nginx/gitlab-runsvdir/workspace/ops-monitor active 및 시작 시각/MainPID 유지. n3m.kr 정적 사이트 200, /gitlab/ 302 유지. Nginx에는 n3m.kr HTTPS block의 notParsec include만 추가
실제 Windows/외부 회선 접근 가능한 Windows 장치·별도 외부 회선이 없어 미검증. mock 보고를 영상 접속으로 판정하지 않음

실행 방법: Ubuntu 운영 문서. 실제 구현 API: CONTROL_API_V1. 설치·공개 검증·backup service 실행·운영 rollback은 완료했다. 남은 운영 검증은 계획된 재부팅, DB 잠금/용량 부족/쓰기 실패와 장시간 proxy timeout, 다음 calendar 백업의 실제 자동 발동 확인 및 외부 재해 복구 백업이다. 인증된 공개 기기 시험은 운영 DB를 오염시키지 않는 별도 상태 디렉터리/검증 배치로 수행해야 한다.

Windows의 후속 작업은 WSS 자동 presence/재동기화 UI, 장치 목록에서 세션 요청/승인, peer 키 증명과 ticket 소비, 매 연결 비밀번호 gate, lease watchdog/종료 ACK, 후보 probe와 실제 미디어 상태 보고다. STUN/relay/VPN은 설치하지 않았고 UDP 포트도 열지 않았다. N100에서 인코딩하는 구조로 변경하지 않았다.