> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH

> 키 기반 인증과 신뢰할 수 있는 호스트 키를 사용하여 에이전트가 셸 명령을 실행할 수 있도록 SSH를 통해 서버를 CloudThinker에 연결합니다

SSH를 통해 서버를 연결하면 [Alex](/ko/guide/agents/alex) (Cloud Engineer)가 호스트에서 셸 명령을 직접 실행할 수 있습니다: 디스크 사용량 확인, 로그 추적, 서비스 점검, 문제 진단 등이 가능합니다.

## 사전 요구사항

| 요구 사항           | 세부 정보                                         |
| --------------- | --------------------------------------------- |
| **접근 가능한 호스트**  | 서버가 SSH 포트에서 CloudThinker의 인바운드 SSH를 허용해야 함   |
| **로그인 사용자**     | 셸 접근 권한이 있는 기존 사용자 계정                         |
| **인가된 키**       | 해당 사용자의 `~/.ssh/authorized_keys`에 공개 키가 있어야 함 |
| **키 기반 인증 활성화** | `sshd`가 해당 사용자에 대한 공개 키 인증을 허용해야 함            |

## 설정

<Steps>
  <Step title="키 쌍 준비">
    기존 키 쌍을 사용하거나 CloudThinker 전용 키를 생성하세요:

    ```bash theme={null}
    ssh-keygen -t ed25519 -C "cloudthinker" -f ./cloudthinker_key
    ```

    이 명령은 `cloudthinker_key` (개인 키)와 `cloudthinker_key.pub` (공개 키)를 생성합니다. OpenSSH (`-----BEGIN OPENSSH PRIVATE KEY-----`)와 PEM (`-----BEGIN RSA/EC PRIVATE KEY-----`) 형식 모두 지원되며, `ed25519`, `rsa`, `ecdsa` 키를 사용할 수 있습니다.
  </Step>

  <Step title="공개 키 인가">
    서버의 로그인 사용자 인가된 키에 공개 키를 추가하세요:

    ```bash theme={null}
    ssh-copy-id -i ./cloudthinker_key.pub user@server.example.com
    # 또는 cloudthinker_key.pub를 ~/.ssh/authorized_keys에 수동으로 추가
    ```
  </Step>

  <Step title="CloudThinker에 연결 추가">
    **Connections → SSH**로 이동하여 다음을 입력하세요:

    * **Host**: 호스트명 또는 IP, 예: `server.example.com` 또는 `10.0.0.5`
    * **User**: 로그인 사용자, 예: `ubuntu`
    * **Port**: SSH 포트 (선택 사항, 기본값 `22`)
    * **Private key**: `BEGIN`/`END` 줄을 포함한 전체 개인 키
    * **Passphrase**: 선택 사항, 개인 키에 패스프레이즈가 있는 경우에만 필요

    CloudThinker가 연결을 테스트하고 성공하면 **Connected** 상태를 표시합니다.
  </Step>
</Steps>

### 호스트 키 검증

처음 연결할 때 CloudThinker가 서버의 호스트 키를 기록합니다. 이후 모든 연결에서 키가 여전히 일치하는지 확인하므로 서버 ID가 예기치 않게 변경되면 경고를 받습니다.

키가 변경되면 연결이 중단되고 CloudThinker가 이전에 신뢰한 지문과 새 지문을 모두 표시합니다. 이는 일반적으로 서버 재구축 또는 SSH 키 교체 후에 발생합니다. 변경이 예상된 것임을 확인한 후 **Trust new host key**를 선택하여 계속하세요.

<Warning>
  서버 ID 변경이 예상하지 않은 경우라면 새 키를 신뢰하지 마세요. 예기치 않은 변경은 연결이 가로채지고 있다는 신호일 수 있습니다. 먼저 서버에서 새 지문을 직접 확인하세요.
</Warning>

## 연결 세부 정보

| 필드              | 설명                            | 예시                                       |
| --------------- | ----------------------------- | ---------------------------------------- |
| **Host**        | 대상 서버의 호스트명 또는 IP 주소          | `server.example.com`                     |
| **User**        | 셸 접근 권한이 있는 로그인 사용자           | `ubuntu`                                 |
| **Port**        | SSH 포트                        | `22`                                     |
| **Private key** | `BEGIN`/`END` 헤더를 포함한 전체 개인 키 | `-----BEGIN OPENSSH PRIVATE KEY-----...` |
| **Passphrase**  | 키가 암호화된 경우의 패스프레이즈            | —                                        |

## 필요 권한

Alex는 로그인 사용자의 권한으로 명령을 실행합니다. 에이전트가 특권 명령을 실행해야 하는 경우가 아니면 루트 접근이 필요하지 않습니다.

<Tip>
  에이전트가 실제로 필요로 하는 명령과 경로로만 로그인 사용자를 제한하세요. `authorized_keys`에서 `command=` 및 `from=` 옵션을 사용하여 키가 실행할 수 있는 것과 접근 원본을 제한하세요.
</Tip>

## 에이전트 기능

연결이 완료되면 Alex가 SSH를 통해 서버에서 셸 명령을 실행합니다.

| 기능         | 설명                          |
| ---------- | --------------------------- |
| **시스템 점검** | 디스크, 메모리, CPU, 프로세스, 서비스 상태 |
| **로그 분석**  | 애플리케이션 및 시스템 로그 읽기 및 검색     |
| **진단**     | 호스트의 장애, 연결성, 설정 조사         |
| **운영 확인**  | 서버 상태를 보고하는 읽기 전용 명령 실행     |

### 연결 확인

```text theme={null}
@alex #report show system uptime, disk usage, and top memory processes on the server
```

### 예시 프롬프트

```text theme={null}
@alex #report check disk usage on all filesystems and flag anything above 80%
@alex #report tail /var/log/app/error.log and summarize the last 100 error lines
@alex #report show which processes are using the most CPU and memory right now
```

<Warning>
  명령은 로그인 사용자의 권한으로 실행됩니다. 에이전트가 실제로 필요로 하는 것으로만 해당 사용자를 제한하세요.
</Warning>

## 문제 해결

<Accordion title="인증 실패">
  * 공개 키가 로그인 사용자의 `~/.ssh/authorized_keys`에 있는지 확인하세요
  * **User**가 해당 키가 인가된 계정과 일치하는지 확인하세요
  * `BEGIN`/`END` 줄을 포함하여 개인 키가 전체로 붙여넣어졌는지 확인하세요
  * 키에 패스프레이즈가 있는 경우 **Passphrase**를 제공하세요
</Accordion>

<Accordion title="호스트에 연결할 수 없음">
  * **Host**와 **Port**가 올바른지 확인하세요
  * 서버가 CloudThinker의 SSH를 허용하는지 확인하세요 (방화벽, 보안 그룹, 허용 목록)
  * SSH 데몬이 실행 중이고 해당 포트에서 수신 대기 중인지 확인하세요
</Accordion>

<Accordion title="호스트 키 변경됨">
  * 서버 재구축 또는 SSH 키 교체 후 예상되는 상황입니다: 새 지문을 검토하고 **Trust new host key**를 선택하세요
  * 변경이 예기치 않은 경우 재신뢰 전에 조사하세요
</Accordion>

<Accordion title="원격 명령 실패">
  * 연결은 정상이지만 명령이 0이 아닌 종료 코드를 반환함
  * 명령, 사용자 권한, 원격 호스트의 경로를 확인하세요
</Accordion>

## 보안

* **최소 권한** — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
* **기본 읽기 전용** — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
* **자격증명 교체** — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
* **오프보딩 시 취소** — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.

- **전용 키** — CloudThinker 전용 키 쌍을 생성하여 독립적으로 취소할 수 있도록 하세요.
- **교체 및 검증** — 주기적으로 키를 교체하고 재신뢰 전에 항상 호스트 키 변경을 확인하세요.

## 관련 항목

<CardGroup cols={2}>
  <Card title="Alex 에이전트" icon="cloud" href="/ko/guide/agents/alex">
    클라우드 엔지니어링 및 인프라 운영
  </Card>

  <Card title="Kubernetes 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/kubernetes.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=7c03292954ff635a1994623a5c39971b" href="/ko/guide/connections/kubernetes" width="24" height="24" data-path="images/icons/kubernetes.svg">
    워크로드 분석 및 운영을 위한 클러스터 연결
  </Card>
</CardGroup>