← 모든 문서

페어링, 재페어링, 머신 공유

Terminull이 실행되는 모든 머신에는 비컨 ID와 공개 키로 이루어진 영구 identity가 있으며, 이를 담은 terminull://pair QR을 표시합니다. QR은 두 종류가 있고, 스캔의 결과는 어떤 QR인지와 누가 스캔하는지에 따라 달라집니다. 이 섹션의 핵심은 바로 그 차이입니다. 한쪽 QR은 머신을 넘겨주고, 다른 쪽은 빌려줍니다.

페어링 — 머신을 처음 연결하기

macOS에서는 설정 마법사의 마지막 페이지에 QR이 표시되며, 메뉴 막대의 QR로 기기 추가에서 언제든 다시 열 수 있습니다. 헤드리스 Linux에서는 terminull 서비스가 페어링 URL을 텍스트로 출력합니다(SSH로는 터미널 QR을 읽을 수 없기 때문입니다). 이를 앱에 붙여넣거나 Mac 창으로 끌어다 놓으면 됩니다.

Windows에서는 설치 프로그램의 마지막 단계에 QR이 표시되며, 트레이 아이콘의 Pair a phone (QR)에서 언제든 다시 열 수 있습니다. 아니면 아무 터미널에서 terminull qr을 실행하세요.

앱에서 스캔하면 해당 머신이 내 계정에 등록되고, 나는 그 머신의 소유자가 됩니다. 앱이 비컨 ID와 공개 키를 등록하면, 머신은 영구 인증 토큰을 한 번 받아 온라인 상태가 됩니다. QR에는 비컨 ID, 머신의 공개 키, 일회용 키 교환 키, 홈 릴레이 주소, 그리고 한 번만 쓰는 클레임 코드만 들어 있습니다. 코드나 세션, 자격 증명은 절대 포함되지 않습니다.

헤드리스 머신에서 QR 얻기

새로 설치한 서비스는 페어링되지 않은 상태로 처음 시작할 때 자체 출력에 페어링 QR을 표시하고, 어떤 기기가 등록을 마치면 더 이상 표시하지 않습니다. 그 이후에 QR이 필요하면 실행 중인 서비스에 요청하세요.

terminull-admin qr        # print a QR (needs the service running)
terminull-admin qr --url  # just the pairing link, on stdout

QR은 명령을 입력한 터미널이 아니라 서비스의 출력에 그려집니다. 내 터미널에는 대신 링크가 돌아옵니다. systemd 환경에서 그 출력은 저널이므로 저널에서 렌더링하세요.

journalctl --user -u terminull --no-pager -o cat -n 40

-o cat은 선택이 아닙니다. 이 옵션이 없으면 journald가 모든 줄 앞에 타임스탬프와 유닛 이름을 붙이고, 그 때문에 코드의 각 행이 옆으로 밀립니다. 언뜻 멀쩡해 보여도 스캔되지 않습니다.

SSH에서는 보통 이미지보다 링크가 편합니다. terminull-admin qr --url은 앱에 붙여넣을 수 있는 순수 URL을 출력합니다. 직접 렌더러로 넘기면 저널을 아예 거치지 않습니다: terminull-admin qr --url | qrencode -t ANSI

흔히 걸리는 두 가지가 있습니다. 설치 프로그램이 이 명령을 서비스 자체 환경에 두기 때문에, 셸에서 찾지 못하면 전체 경로 ~/.local/share/terminull/venv/bin/terminull-admin을 쓰세요. 또 이 명령은 로컬 소켓으로 실행 중인 서비스와 통신하므로 “terminull is not running”은 말 그대로의 뜻입니다. systemctl --user start terminull로 시작한 뒤 다시 시도하세요. 출력된 것은 소유자 QR로 간주하고 위에서 설명한 주의사항을 모두 지키세요.

재페어링 — 같은 계정으로 다시 스캔하기

이미 그 머신을 소유한 계정으로 소유자 QR을 다시 스캔하는 것은 재등록이며, 몇 번을 반복해도 안전합니다. 저장된 공개 키와 이름을 갱신하고 토큰 발급 창을 다시 엽니다. 잃는 것은 없습니다. 세션은 휴대폰이 아니라 머신 자체에 있으므로 그대로 남아 있습니다.

본인의 두 번째 기기를 추가할 때(아이폰과 함께 아이패드를 쓰는 경우), 앱을 다시 설치했을 때, 또는 완전 삭제로 머신의 identity를 초기화했을 때 재페어링하세요. 마지막 경우에는 키가 새로 생성되는데, 재등록이 다시 기록하는 것이 바로 그 키입니다.

소유자 QR은 비밀입니다. 다른 계정이 스캔하면 그것은 참여가 아니라 소유권 이전입니다. 서버가 대기 상태로 기록하고, 머신이 다음번 폴링할 때 적용되어 머신이 내 계정에서 빠져나갑니다. 클레임 코드를 가지고 있다는 것은 머신에 물리적으로 접근할 수 있다는 증거이며, 그래서 머신에 대한 권한으로 취급됩니다. 소유권을 넘기지 않고 다른 사람을 들이려면 아래의 공유 QR을 사용하세요.

앱에서 계정을 열고 해당 머신을 찾아 옆의 QR 아이콘을 누르세요. 머신이 2분간 유효한 새 코드를 만들어 서버에 등록하고, 남은 시간이 표시되는 공유 QR을 보여줍니다. (뒤에 계정이 없는 LAN 전용 머신에서는 공유를 사용할 수 없습니다.)

다른 계정이 스캔하면 멤버로 참여합니다. 머신이 상대방 목록에 나타나고, 푸시 알림을 받으며, 그 머신에서 세션을 실행할 수 있습니다. 소유권은 바뀌지 않고 머신의 인증 토큰도 그대로입니다. 이미 참여한 멤버는 새로 공유를 열지 않아도 언제든 다시 스캔할 수 있습니다.

만료는 표시만 되는 것이 아니라 서버가 강제합니다. 일치하는 코드가 없는 스캔은 “이 머신은 지금 공유 중이 아닙니다”로 거부되고, 기한이 지난 경우에는 “이 공유 코드는 만료되었습니다 — 소유자에게 새 QR을 요청하세요”가 표시됩니다. 따라서 예전 공유 QR의 스크린샷은 아무 쓸모가 없습니다. 공유를 영구적인 권한이 아니라 의도적이고 순간적인 행위로 유지하는 것이 목적입니다.

지금 보고 있는 QR은 무엇인가?

	소유자 QR	공유 QR
찾는 위치	설정 마법사 또는 메뉴 막대 → QR로 기기 추가	앱 → 계정 → 머신 옆 QR 아이콘
유효 기간	머신의 identity가 초기화될 때까지	2분, 카운트다운 표시
내 계정으로 스캔하면	재페어링 — 반복해도 안전	달라지는 것 없음, 이미 추가됨
다른 사람 계정으로 스캔하면	머신의 소유권을 가져감	멤버로 참여, 소유자는 그대로
스크린샷해도 되나?	아니요 — 비밀번호처럼 다루세요	2분이 지나면 무해합니다

LAN 전용 페어링

pairing_mode = "lan"으로 설정한 머신은 전적으로 로컬 네트워크에서 페어링합니다. QR이 LAN 전용으로 표시되고, 앱은 계정 등록을 건너뛰며, 어느 단계에서도 서버가 관여하지 않습니다. 이 경우 머신은 같은 네트워크에서만 접근할 수 있고 푸시 알림과 클라우드 AI 어시스트는 사용할 수 없습니다. 공유도 불가능합니다. 공유는 서버를 거치는 개념인데 이 모드에는 서버가 없기 때문입니다.