SynapsePraesidion
한국어English
문서 목차

안내서

SSH로 접속하기 (허용된 경우)

관리자가 SSH를 허용하면 내 컴퓨터의 터미널이나 데스크톱 VS Code로 켜져 있는 내 작업공간에 접속합니다. 키 만들기와 등록, 접속 명령, 안 될 때.

개발 중인 화면

이 페이지에서

포털 화면은 개발 중입니다. 화면의 낱말과 배치는 바뀔 수 있고, 단추가 실행하는 명령은 이미 만들어져 있습니다.

관리자가 계정마다 SSH를 허용하면, 내 컴퓨터의 터미널과 scp, sftp, 데스크톱 VS Code(Remote-SSH)로 켜져 있는 내 작업공간에 접속할 수 있습니다. 웹 IDE와 같은 작업공간, 같은 사용자라서 웹에서 띄운 tmux와 screen에 그대로 붙습니다.

먼저 알아 둘 것

  • 관리자가 사람마다 허용합니다. 허용되지 않았으면 [내 계정]의 SSH 구역에 「관리자가 SSH를 허용하면 여기서 키를 등록합니다.」가 나옵니다.
  • SSH는 대량 내려받기와 같습니다. SSH를 허용하면 작업공간의 파일을 scp나 sftp로 한꺼번에 가져갈 수 있습니다. 그래서 기본으로 꺼져 있습니다.
  • 비밀번호로는 들어갈 수 없습니다. 「비밀번호로는 접속할 수 없습니다. 등록한 키로만 들어갑니다.」
  • 내 작업공간에만, 켜져 있을 때만. 키는 내 작업공간에만 닿고, 「작업공간이 켜져 있을 때만 접속됩니다.」

필요한 것

  • OpenSSH 8.1 이상. ssh -V 명령으로 확인합니다. 최신 업데이트를 받은 Windows 10, 11과 macOS, Linux에 들어 있습니다. 그보다 낮은 Windows 10이면 Windows를 업데이트하세요.
  • cloudflared. 인터넷에서 접속할 때만 필요합니다.
  • 데스크톱 VS Code와 Remote - SSH 확장. VS Code로 접속할 때만 필요합니다.

이 컴퓨터 준비 (컴퓨터마다 한 번)

[내 계정]의 SSH 구역에 「이 컴퓨터 준비」가 차례대로 나옵니다. 「이 컴퓨터」에서 Windows (PowerShell), macOS, Linux 가운데 하나를 고르면 그 운영체제의 명령이 나오고, 누르면 복사됩니다. 아래 명령은 화면에 나오는 것과 같은 예시입니다.

  1. 터미널 열기

    Windows는 시작 메뉴에서 PowerShell을 찾아 엽니다(명령 프롬프트가 아니라 PowerShell). macOS는 Spotlight(Cmd+Space)에서 터미널을 찾아 엽니다. Linux는 터미널을 엽니다. 아래 명령은 모두 여기에 붙여 넣습니다.

  2. 키 만들기

    ssh-keygen -t ed25519

    Enter를 누르면 기본 파일에 저장합니다. 노트북이면 암호를 두기를 권합니다. 두지 않으려면 Enter를 두 번 누릅니다. 파일이 이미 있다고 하면 n을 누르고 그 키를 쓰세요. 다만 폐기한 키라면(비밀번호를 바꾸면 폐기됩니다) y를 눌러 새로 만드세요.

  3. 공개키 보기

    Windows (PowerShell)

    Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

    macOS, Linux

    cat ~/.ssh/id_ed25519.pub

    나온 한 줄을 모두 복사하세요. 그 줄은 이렇게 시작합니다: ssh-ed25519. 비밀키(.pub이 없는 id_ed25519)는 붙여 넣지 마세요.

  4. 키 등록

    [내 계정]의 SSH 구역에서 [키 등록]을 누르고, 「공개키 (~/.ssh/id_ed25519.pub의 내용)」에 복사한 줄을 붙여 넣습니다. OTP 앱을 등록한 계정은 10분 안에 넣은 코드가 필요합니다. 비밀키를 붙여 넣으면 비밀키라고 알려 주고 등록하지 않습니다. 키는 한 사람에 기본 10개까지 등록할 수 있습니다.

  5. cloudflared 설치 (인터넷에서 접속할 때, 한 번)

    Windows (PowerShell)

    winget install --id Cloudflare.cloudflared

    macOS와 Linux의 설치 명령은 화면에 나오는 한 줄을 복사해 실행합니다. Cloudflare가 GitHub에 올린 cloudflared를 받아 설치합니다. 관리자 암호를 물으면 이 컴퓨터의 암호를 넣으세요. 설치한 다음 터미널과 VS Code를 다시 여세요.

  6. VS Code 준비 (VS Code로 접속할 때, 한 번)

    확장 보기에서 Remote - SSH(ms-vscode-remote.remote-ssh)를 설치합니다. 그다음 설정(Ctrl+, / Cmd+,)에서 Local Server Download를 찾아 always로, Download Extensions Locally를 찾아 켭니다. settings.json에서 직접 고친다면 이 줄을 넣습니다.

    settings.json

    "remote.SSH.localServerDownload": "always",
"remote.downloadExtensionsLocally": true

    작업공간은 VS Code 서버와 확장을 직접 내려받을 수 없어서 이 컴퓨터가 받아 넣습니다.

키를 등록하면 화면 아래 콘솔에 이런 명령이 나옵니다.

명령 콘솔 개발 중인 화면
synapse ssh-key add --name laptop 완료 
표준 입력: (숨김)Added SSH key: k-7d1f9e24 (laptop, SHA256:EAHucGguNs+B+u0EKvEBqdDNQsKyB42UfiCebb80fck)It reaches your active workspaces while they run and SSH is allowed. How to connect: synapse ssh guide
예시이며, 개발 중인 화면을 옮겨 그렸습니다.

접속하기

작업공간이 「실행 중」이면 작업공간 화면의 「SSH로 접속」과 [내 계정] SSH 구역의 「접속」에 접속 명령이 나옵니다. 명령은 서버가 이 설치에 맞게 만들고, 누르면 복사됩니다. 키를 등록하기 전에는 명령이 흐리게 보입니다.

망을 고르는 탭이 둘 있습니다: 「사내망」과 「인터넷」. 사내와 집을 오가는 노트북에는 인터넷 줄을 두세요. 사내에서도 그대로 접속됩니다.

아래는 모양을 보여 주는 예시입니다. 주소와 포트는 설치마다 다르니 화면의 명령을 복사하세요.

사내망에서

터미널

ssh -a -x -J [email protected]:2222 researcher@ws-0012

인터넷에서

먼저 이 명령을 실행해 두고 창을 닫지 마세요.

이 명령을 실행해 두세요 (창을 닫지 마세요)

cloudflared access tcp --hostname ssh.example.org --url 127.0.0.1:2022

그다음 다른 터미널에서 접속합니다.

다른 터미널에서

ssh -a -x -J [email protected]:2022 researcher@ws-0012

짧은 명령과 VS Code

SSH 설정 파일 맨 앞에 화면의 설정 줄을 한 번 붙여 넣으면, 그다음부터는 짧은 명령으로 접속합니다. 한 컴퓨터에는 한 망의 줄만 둡니다. 설정 파일은 Windows에서 %USERPROFILE%\.ssh\config, macOS와 Linux에서 ~/.ssh/config 파일입니다. 화면에 그 파일을 여는 명령이 있습니다.

~/.ssh/config (인터넷, 예시)

# Synapse (app.example.org) from the internet, through Cloudflare
Host ws-*
  User researcher
  ProxyCommand ssh -o StrictHostKeyChecking=accept-new -o "ProxyCommand=cloudflared access ssh --hostname ssh.example.org" -W %h:%p [email protected]
  StrictHostKeyChecking accept-new
  ForwardAgent no
  ForwardX11 no
  ServerAliveInterval 30

이 줄은 이름이 이렇게 시작하는 모든 호스트에 쓰입니다: ws-. PowerShell에서 > 기호나 Set-Content 명령으로 이 파일을 만들지 마세요. OpenSSH가 읽지 못하는 인코딩으로 저장됩니다.

그다음에는 터미널에서 이렇게 접속합니다. VS Code에서는 Remote-SSH: Connect to Host...를 고른 다음 호스트 칸에 넣습니다: ws-0012

ssh ws-0012

처음 접속할 때

한 줄 명령으로 처음 접속하면 호스트 키를 믿을지 입구와 작업공간에서 한 번씩, 두 번 묻습니다. 화면의 「처음 접속할 때 확인하는 지문」과 같으면 yes를 치세요. 설정 줄을 넣고 접속하면(VS Code 포함) 처음 보는 호스트 키를 묻지 않고 받아들입니다. 확인하고 싶으면 처음 접속한 뒤 화면의 지문과 견주어 보세요.

안 될 때

OpenSSH가 영어로 내는 말과 그 뜻입니다. 화면의 「안 될 때」에도 고른 망에 맞는 것이 나옵니다.

이런 말이 나오면뜻과 할 일
Permission denied (publickey)이 컴퓨터의 키가 내 계정에 등록되어 있지 않습니다. 내 계정에서 키를 등록하세요. SSH 허용이 거두어지거나 계정이 사용 중지되면 키가 듣지 않고, 비밀번호를 바꾸면 키가 폐기됩니다.
open failed: connect failed: Connection refused작업공간이 막 시작해 SSH가 아직 뜨지 않았습니다. 30초쯤 기다렸다가 다시 하세요.
Temporary failure in name resolution작업공간이 켜져 있지 않습니다. 시작한 다음 다시 하세요.
administratively prohibited내 작업공간이 아니거나 사용 중인 작업공간이 아닙니다.
connect to host (입구 주소) port 2222: Connection refused사내망: SSH 입구가 돌고 있지 않습니다. 관리자에게 알리세요.
Connection timed out, Operation timed out, No route to host, Network is unreachable사내망: 이 컴퓨터가 사내망에 있지 않습니다. 인터넷 줄을 쓰세요.
connect to host 127.0.0.1 port 2022: Connection refused인터넷: 첫 단계(cloudflared)가 돌고 있지 않습니다. 다른 터미널에서 실행해 두고 창을 닫지 마세요.
cloudflared: command not found, 'cloudflared' is not recognized인터넷: cloudflared가 설치되지 않았거나, 설치하기 전에 연 터미널이나 VS Code입니다. 설치한 다음 다시 여세요.
Connection closed by 127.0.0.1 port 2022, kex_exchange_identification, websocket: bad handshake인터넷: Cloudflare를 거친 접속이 SSH 입구에 닿지 못했습니다. 1분쯤 뒤에 다시 하고, 계속 안 되면 관리자에게 알리세요.
Could not resolve hostname ws-짧은 명령은 SSH 설정 줄이 있어야 됩니다. 설정 줄을 넣거나 한 줄 명령을 쓰세요.
Too many authentication failures이 컴퓨터가 다른 키를 너무 많이 먼저 내밀었습니다. ssh-add -D로 SSH 에이전트의 키를 비우고(키 파일은 그대로) 다시 하세요.
REMOTE HOST IDENTIFICATION HAS CHANGED접속하지 말고 관리자에게 알리세요.

키 폐기

[내 계정]의 SSH 구역에서 키를 폐기할 수 있습니다. 폐기한 키로는 새로 접속할 수 없고, 같은 키는 다시 등록할 수 없습니다. 이미 열린 접속은 작업공간을 정지하면 끝나고, 마지막 키였다면 2분쯤 안에 끝납니다. 비밀번호를 바꾸면 「API 토큰과 SSH 키는 그대로 두기」를 고르지 않는 한 키가 모두 폐기됩니다.