KapsuleHost 사이트의 SSH 액세스는 키 기반으로만 동작하므로, 셸이나 SFTP 세션을 열기 전에 KPanel에서 해당 사이트에 공개 키를 등록해야 합니다. 이 가이드에서는 해당 페이지의 위치, 이미 가지고 있는 키를 추가하는 방법, KapsuleHost가 대신 키를 생성하도록 하는 방법, 더 이상 신뢰하지 않는 키를 폐지하는 방법을 다룹니다.
SSH 키 페이지의 위치
웹사이트를 열고 사이트를 클릭한 다음, 사이트의 왼쪽 메뉴에서 설정 그룹을 열고 SSH 키를 선택합니다. 이 페이지의 제목은 SSH 액세스이며, 이 사이트의 연결 정보와 현재 해당 정보를 사용하도록 인증된 공개 키 목록이라는 두 가지 정보를 담고 있습니다.
메인 사이드바에는 최상위 SSH 항목이 없습니다. 키는 사이트별로 관리되므로, 여기에서 추가하는 키는 이 사이트에 대해서만 인증됩니다. 여러 사이트를 운영한다면 노트북에 있는 키가 동일하더라도 각 사이트마다 별도의 항목이 필요합니다.
키를 추가하거나 폐지하려면 sites:write 권한이 필요합니다. 읽기 전용 역할의 팀 계정을 사용 중이라면 키 추가 버튼과 폐지 아이콘이 표시되지 않습니다. 계정 소유자나 관리자에게 변경을 요청하세요.
연결 정보
페이지 상단의 연결 정보 카드에는 클라이언트에 필요한 모든 정보가 표시됩니다:
| 항목 | 설명 |
|---|---|
| 호스트 | 연결할 호스트 이름 |
| 포트 | 이 사이트의 SSH 포트 |
| 사용자 이름 | 사이트가 실행되는 시스템 사용자 |
| SSH | 이 사이트에 대해 바로 사용할 수 있는 ssh 명령 |
| SFTP | 이 사이트에 대해 바로 사용할 수 있는 sftp 명령 |
각 행에는 복사 버튼이 있으며, SSH와 SFTP 행은 값만이 아니라 전체 명령을 복사하므로 터미널에 바로 붙여넣을 수 있습니다. 직접 명령을 입력하기보다는 이 두 가지를 사용하세요. 이미 올바른 사용자, 호스트, 포트가 포함되어 있습니다.
이 카드가 전혀 표시되지 않는다면 사이트의 셸 사용자 프로비저닝이 아직 끝나지 않은 것입니다. 이 경우 API는 단순히 사이트에 SSH 사용자가 없습니다 오류를 반환합니다. 사이트 상태 표시가 Active로 바뀔 때까지 기다린 후 새로고침하세요.
이미 가지고 있는 키 추가하기
대부분의 사람들은 이미 자신의 기기에 키 쌍을 가지고 있습니다. 여기에서는 공개 키 쪽을 추가합니다.
- 본인의 컴퓨터에서 공개 키를 출력합니다. macOS와 리눅스에서는 보통
cat ~/.ssh/id_ed25519.pub을 사용하며, 이전 버전의 RSA 키라면cat ~/.ssh/id_rsa.pub를 사용합니다. OpenSSH를 사용하는 Windows에서는type %USERPROFILE%\.ssh\id_ed25519.pub입니다. ssh-ed25519,ssh-rsa또는ecdsa-sha2-nistp256으로 시작하는 한 줄 전체를 복사합니다.- KPanel에서 키 추가를 클릭합니다.
- Label 필드에 기억하기 쉬운 이름을 입력합니다. 예를 들어 키가 저장된 기기 이름을 사용하세요.
- 공개 키를 두 번째 필드에 붙여넣습니다.
- 키 추가를 클릭합니다.
키는 즉시 Authorised keys 목록에 나타나며, 라벨 아래에 지문(fingerprint)이 함께 표시됩니다. 바로 연결할 수 있습니다.
KapsuleHost는 키가 추가될 때마다 계정 이메일 주소로 메일을 보내며, 여기에는 라벨, 지문, 사이트 정보가 담겨 있습니다. 이는 의도된 동작입니다. SSH 액세스는 신뢰도가 높은 권한이므로, 본인이 추가하지 않은 키가 나타나면 즉시 폐지하고 비밀번호를 변경하세요.
반드시 .pub 파일만 붙여넣으세요. 개인 키 파일은 .pub 확장자가 없으며 -----BEGIN OPENSSH PRIVATE KEY-----와 같은 줄로 시작합니다. 만약 그것을 붙여넣었다면 그것은 개인 키이며, 재사용하지 말고 새로 생성해야 합니다.
아직 키가 없는 경우
ssh-keygen -t ed25519 -C "your-label"으로 로컬에서 키를 생성하고, 기본 파일 위치를 그대로 두고, 메시지가 나타나면 암호 구절(passphrase)을 설정하세요. 그러면 ~/.ssh/id_ed25519(비공개로 유지)과 ~/.ssh/id_ed25519.pub(이것을 붙여넣으세요)이 생성됩니다.
KapsuleHost가 키 쌍을 생성하도록 하기
ssh-keygen을 직접 실행하고 싶지 않다면 KPanel이 대신 키 쌍을 만들어 줄 수 있습니다.
- 키 추가를 클릭합니다.
- Label 필드를 입력합니다. 공개 키 입력란은 비워 둡니다.
- 키 쌍 생성을 클릭합니다.
KapsuleHost는 Ed25519 키 쌍을 생성하고, 공개 키 쪽을 사이트에 설치한 다음 키 쌍이 생성되었습니다. 지금 개인 키를 다운로드하세요라는 녹색 배너를 표시합니다. .pem 다운로드를 클릭해 개인 키를 저장하세요. 파일 이름은 선택한 라벨을 따릅니다.
개인 키는 단 한 번만 표시됩니다. 배너에도 명확히 적혀 있듯이, 다운로드할 수 있는 기회는 이번 한 번뿐입니다. KapsuleHost는 나중에 다시 받을 수 있는 사본을 보관하지 않습니다. 배너를 다운로드하지 않고 닫았다면 키를 폐지하고 새 키 쌍을 생성하세요.
생성된 키에는 암호 구절이 없는데, 이 때문에 스크립트에서 별도의 입력 없이 바로 사용할 수 있습니다. 반대로 말하면 파일 자체가 곧 인증 수단 전체라는 뜻입니다. 암호 구절을 원한다면 ssh-keygen로 직접 키 쌍을 생성한 후 공개 키 쪽을 붙여넣으세요.
다운로드한 후에는 파일을 적절한 위치로 옮기고 권한을 강화하세요. SSH는 누구나 읽을 수 있는 개인 키 사용을 거부합니다:
mv ~/Downloads/my-laptop_id_ed25519.pem ~/.ssh/kapsule-mysite.pem
chmod 600 ~/.ssh/kapsule-mysite.pem
ssh -i ~/.ssh/kapsule-mysite.pem <username>@<host> -p <port>
연결 정보 카드에 있는 사용자 이름, 호스트, 포트로 대체하세요.
인증된 키 목록 읽는 법
Authorised keys의 각 행에는 다음이 표시됩니다:
- 키에 부여한 라벨.
- 키 지문. 라벨이 비슷할 때 두 키를 구별하는 데 사용됩니다.
- 등록된 날짜가 표시되는 Added.
- 가장 최근 인증 날짜가 표시되는 마지막 사용, 또는 아직 인증된 적이 없다면 사용 안 됨.
정리 작업을 할 때 유용한 것은 마지막 사용 열입니다. 한 번도 사용된 적이 없거나 몇 달째 사용되지 않은 키는 대개 교체된 노트북이거나 퇴사한 외주 작업자의 것입니다.
키 폐지하기
해당 키 행의 빨간 휴지통 아이콘을 클릭합니다. KPanel은 SSH 키를 폐지하시겠습니까?라는 확인 메시지와 함께 해당 키가 이 사이트에 더 이상 인증되지 않는다는 안내를 표시합니다. 완료하려면 Revoke를 클릭합니다.
폐지는 새로운 연결부터 적용됩니다. 이미 열려 있는 SSH 세션은 키를 폐지해도 종료되지 않으므로, 아직 연결되어 있을 수 있는 사용자의 액세스를 제거하는 경우라면 키를 폐지한 뒤 그 사람이 가져갔을 수 있는 모든 것, 즉 데이터베이스 비밀번호, 애플리케이션 시크릿, 사이트에 저장된 토큰 등을 변경하세요.
키 목록은 짧게 유지하세요. 기기당 하나의 키를 기기 이름으로 라벨링해 두면 "key1", "new key", "temp"처럼 이름 붙인 키 더미보다 훨씬 감사하기 쉽습니다.
문제 해결
Permission denied (publickey). 가장 흔한 원인은 클라이언트가 등록한 키와 다른 키를 제시하는 경우입니다. ssh -i /path/to/private_key ...로 올바른 키를 강제로 지정하거나, ssh -v으로 어떤 키가 제시되고 있는지 확인하세요.
Connection refused 또는 타임아웃. 연결 정보에 표시된 포트를 사용하고 있는지, 기본 포트인 22를 사용하고 있지 않은지 확인하세요. 직접 입력하지 말고 페이지에서 SSH 명령을 복사하세요.
개인 키의 권한이 잘못됨. OpenSSH는 다른 사용자가 읽을 수 있는 개인 키를 거부합니다. 해당 파일에 chmod 600을 실행하세요.
키가 SSH에서는 동작하지만 SFTP에서는 동작하지 않음. 두 프로토콜은 동일한 인증 정보를 공유하므로, 이는 거의 항상 키가 아니라 클라이언트 문제입니다. 이미 올바른 포트가 포함된, 페이지에서 복사한 SFTP 명령을 사용하세요.
다음으로 볼 만한 내용
- SFTP로 파일 업로드하기에서는 동일한 인증 정보를 이용한 파일 전송에 대해 다룹니다.
- SSH 터널을 통해 데이터베이스에 연결하기에서는 방금 추가한 키를 사용해 데스크톱 클라이언트에서 MySQL에 접속합니다.
- 사이트 활동 로그에는 추가한 모든 키가 기록되므로, 나중에 누가 언제 무엇을 추가했는지 확인할 수 있습니다.