온프레미스

작동 방식

HopToDesk는 두 종류의 서버를 사용합니다. 시그널 서버는 장치들이 서로를 찾고 세션을 맺도록 돕습니다. TURN 릴레이는 두 장치 사이에 직접 연결이 불가능할 때만 세션 트래픽을 전달합니다.

세션은 종단 간 암호화되므로 어느 서버도 화면, 파일, 채팅을 읽을 수 없습니다. 시그널 서버는 장치 ID와 연결 요청만 봅니다.

이 페이지의 설치 프로그램은 시그널 서버를 설정합니다. 릴레이 트래픽은 기본적으로 HopToDesk 릴레이를 거치고, 지정하면 자체 TURN 서버를 거칩니다.

대시보드는 호스팅 서비스로 유지됩니다. 자체 호스팅 네트워크의 장치도 관리를 위해 대시보드에 연결할 수 있으며, 대시보드가 네트워크 설정을 장치에 전송할 수 있습니다.

시작하기 전에

• Ubuntu 18.04에서 24.04를 실행하는 서버 또는 Windows 서버.
• 해당 서버의 root 또는 sudo 접근 권한.
• 모든 장치가 접근할 수 있는 IP 주소 또는 호스트 이름. LAN을 벗어나지 않는 네트워크라면 사설 주소로 충분합니다.
• 장치를 위해 서버 방화벽에서 TCP 80 포트를 열어 둘 것.
• 자체 릴레이를 원한다면: TURN 서버의 호스트, 포트, 사용자 이름, 비밀번호.

1단계: Linux에 시그널 서버 설치하기

1. root 또는 sudo 권한이 있는 사용자로 서버에 로그인합니다.
2. 이 페이지 상단에서 LAN + Default Relay 또는 Custom TURN Server를 선택합니다. 선택에 따라 설치 명령이 달라집니다.
3. Copy를 클릭하고 명령을 터미널에 붙여넣은 뒤 Enter를 누릅니다.
4. 스크립트가 끝날 때까지 기다립니다. 새 서버에서는 패키지 설치에 몇 분이 걸릴 수 있습니다.
5. 마지막에 스크립트는 HopSignal Setup Complete를 출력하고, 이어서 서버 주소와 바로 사용할 수 있는 네트워크 설정 블록을 표시합니다. 3단계에서 필요하므로 이 출력을 보관하세요.

cd /home && curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sh hsinstall.sh

자체 TURN 서버를 쓰는 경우 명령 끝에 네 개의 값을 이 순서로 추가합니다: 호스트, 포트, 사용자 이름, 비밀번호.

sh hsinstall.sh turn.example.com 443 myuser mypassword

스크립트가 하는 일

• 필요한 빌드 도구와 OpenSSL 라이브러리를 apt로 설치합니다.
• 시그널 서버 바이너리를 /home/hopsignal 폴더로 내려받습니다.
• hopsignal이라는 systemd 서비스를 만들고 부팅할 때마다 시작합니다.
• 서비스가 응답을 멈추면 다시 시작하고 로그가 100MB를 넘으면 순환시키는 cron 감시자를 추가합니다.
• ufw가 활성화된 경우 ufw에서 TCP 80 포트를 엽니다.

Windows의 1단계: 시그널 서버 실행하기

1. 이 페이지 상단의 OS 스위치를 Windows로 바꾸고 Download를 클릭합니다. hopsignal.exe라는 파일 하나를 받게 됩니다.
2. C:\hopsignal 같은 폴더를 만들고 hopsignal.exe를 그 안으로 옮깁니다.
3. 같은 폴더에 fedlist.txt라는 빈 텍스트 파일을 만듭니다.
4. Windows 빌드는 PEM 형식의 TLS 인증서와 개인 키도 필요로 합니다. 자체 서명을 포함해 어떤 쌍이든 됩니다. 같은 폴더에 cert.pem과 key.pem으로 저장하세요.
5. 관리자 권한으로 명령 프롬프트를 열고 서버를 시작합니다.

cd C:\hopsignal
hopsignal.exe --ADDR 0.0.0.0:80 --WSS_ADDR 0.0.0.0:443 --CERT cert.pem --KEY key.pem --FEDLIST fedlist.txt --FEDADDR 127.0.0.1:82 --FEDPWD 123456789 --LOGFILE hs.log

OpenSSL이 있다면 이 명령으로 자체 서명 인증서 쌍을 만들 수 있습니다:

openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 3650 -subj "/CN=hopsignal"

Windows 방화벽에서 포트를 허용합니다:

netsh advfirewall firewall add rule name="HopSignal" dir=in action=allow protocol=TCP localport=80

재부팅 후에도 서버가 계속 실행되게 하려면 SYSTEM 계정으로 부팅 시 시작되는 예약 작업으로 등록합니다:

schtasks /Create /TN HopSignal /SC ONSTART /RU SYSTEM /TR "C:\hopsignal\hopsignal.exe --ADDR 0.0.0.0:80 --WSS_ADDR 0.0.0.0:443 --CERT C:\hopsignal\cert.pem --KEY C:\hopsignal\key.pem --FEDLIST C:\hopsignal\fedlist.txt --FEDADDR 127.0.0.1:82 --FEDPWD 123456789 --LOGFILE C:\hopsignal\hs.log"
schtasks /Run /TN HopSignal

2단계: 서버가 실행 중인지 확인하기

Linux에서는 서비스와 로그를 확인합니다:

sudo systemctl status hopsignal
tail /home/hopsignal/hs.log

Windows에서는 포트가 수신 대기 중인지 확인합니다:

netstat -an | find ":80 "

아무 컴퓨터에서나 WebSocket 포트를 테스트합니다. SERVER_IP를 서버 주소로 바꾸세요. 정상인 서버는 HTTP/1.1 101 Switching Protocols로 응답합니다.

curl -i -N -m 5 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" http://SERVER_IP:80/

3단계: 장치를 서버로 연결하기

모든 장치는 작은 JSON 문서에서 네트워크 설정을 읽습니다. 이것은 설치 프로그램이 1단계 끝에 출력한 블록입니다. SERVER_IP를 서버 주소로 바꾸고, 자체 릴레이를 운영한다면 TURN 블록을 채우세요.

{
  "turnservers": [
    {
      "protocol": "turn",
      "host": "turn.hoptodesk.com",
      "port": "443",
      "username": "hoptodesk",
      "password": "hoptodesk1234"
    }
  ],
  "rendezvous": {
    "host": "SERVER_IP",
    "port": "80"
  },
  "winversion": "1.0.0",
  "macversion": "1.0.0",
  "linuxversion": "1.0.0",
  "none": "none"
}

rendezvous 블록이 시그널 서버입니다. Cloudflare Worker나 AWS 배포처럼 서버에 TLS로 접근하는 경우 rendezvous 대신 rendezvousssl 키를 사용하세요. turnservers 목록에는 하나 이상의 릴레이를 넣습니다. 일반 연결은 프로토콜을 turn으로, TLS 연결은 turn-tls로 설정합니다. 버전 키는 그대로 두세요.

이 문서를 장치에 전달하는 방법은 세 가지입니다. 환경에 맞는 것을 고르세요.

옵션 A: 각 장치에 api.json 파일 넣기

문서를 api.json이라는 파일로 HopToDesk 구성 폴더에 저장한 뒤 HopToDesk를 다시 시작합니다. 앱은 시작할 때 이 파일을 읽고 더 이상 HopToDesk API에 접속하지 않습니다.

Linux에서는 백그라운드 서비스가 root로 실행되어 /root 아래의 파일을 읽고, 사용자가 여는 앱은 자신의 홈 폴더에 있는 파일을 읽습니다. 두 곳 모두에 사본을 두세요.

옵션 B: 파일을 URL에 올리고 앱에서 선택하기

1. 장치가 접근할 수 있는 아무 웹 서버에나 api.json을 업로드합니다. HTTPS를 권장합니다.
2. HopToDesk에서 톱니바퀴 아이콘을 클릭해 설정을 엽니다.
3. Network에서 Choose Network를 클릭합니다.
4. Custom Network Settings를 선택하고 파일의 URL을 붙여넣은 뒤 확인합니다.
5. HopToDesk가 파일을 내려받아 유효한 rendezvous 항목과 turnservers 목록이 있는지 확인한 뒤, 사용자의 서버를 통해 다시 연결합니다.

공개 네트워크로 돌아가려면 Choose Network를 다시 열고 HopToDesk Network를 선택합니다.

옵션 C: 대시보드에서 설정 배포하기

장치가 HopToDesk 대시보드에 연결되어 있다면 계정 전체에 대해 네트워크를 한 번만 설정하면 됩니다. 대시보드에서 만든 맞춤 클라이언트에는 이 설정이 기본으로 포함됩니다.

1. 소유자 또는 관리자로 대시보드에 로그인하고 설정을 엽니다.
2. Network Settings에서 Custom Network를 선택합니다.
3. 시그널 서버 호스트, 포트, 프로토콜로 WS를 입력합니다. 자체 릴레이를 운영한다면 TURN 서버를 추가하고, HopToDesk 릴레이를 계속 쓰려면 비워 두세요.
4. Save Network Settings를 클릭합니다. 연결된 모든 장치가 새 설정을 받아 재설치 없이 적용합니다.

자체 TURN 릴레이 운영하기 (선택 사항)

직접 연결할 수 없는 세션은 기본적으로 HopToDesk 릴레이를 거칩니다. 모든 트래픽을 자체 인프라에 두려면 TURN 서버를 운영하세요. 표준 TURN 서버라면 무엇이든 되며, Linux에서는 coturn이 흔한 선택입니다.

1. 릴레이 서버에 coturn을 설치합니다.

sudo apt install coturn

2. /etc/turnserver.conf를 편집하고 최소한 아래 값을 설정합니다. realm, 자격 증명, 공인 IP는 본인의 것으로 바꾸세요.

listening-port=443
fingerprint
lt-cred-mech
user=myuser:mypassword
realm=example.com
external-ip=PUBLIC_IP

3. /etc/default/coturn에 TURNSERVER_ENABLED 줄이 있으면 주석을 해제합니다. 그런 다음 서비스를 활성화하고 시작합니다.

sudo systemctl enable --now coturn
sudo systemctl restart coturn

4. 릴레이 방화벽에서 수신 포트를 TCP와 UDP 모두 열고, UDP 릴레이 범위 49152부터 65535까지도 엽니다.
5. 장치에 릴레이를 전달합니다: 네 개의 TURN 값을 넣어 설치 프로그램을 다시 실행하거나, 네트워크 설정의 turnservers 블록을 편집합니다. 릴레이가 TLS를 종단하면 프로토콜로 turn-tls를 사용하세요.

Linux에서 서버 관리하기

sudo systemctl status hopsignal
sudo systemctl restart hopsignal
sudo systemctl stop hopsignal
tail -f /home/hopsignal/hs.log

서버를 업데이트하려면 서비스를 중지하고 설치 명령을 다시 실행합니다. 최신 바이너리를 내려받고 서비스를 다시 작성합니다.

서비스와 cron 항목까지 함께 서버를 제거하려면:

cd /home && curl -o hsinstall.sh -sL https://www.hoptodesk.com/hs/hsinstall && sh hsinstall.sh remove

문제 해결

• ID가 Generating에 머물러 있거나 앱이 계속 네트워크에 연결을 시도하는 경우: 장치가 시그널 서버에 접근할 수 없습니다. 서비스가 실행 중인지, 80 포트가 열려 있는지, 네트워크 설정의 주소가 올바른지 확인하세요.
• 장치가 LAN에서는 연결되지만 외부에서는 연결되지 않는 경우: 릴레이에 접근할 수 없습니다. 기본 릴레이를 쓰는 경우 장치에서 turn.hoptodesk.com의 443 포트로 나가는 접근이 필요합니다. 자체 릴레이를 쓰는 경우 방화벽 규칙과 자격 증명을 확인하세요.
• 앱이 api.json을 무시하는 경우: 파일이 후행 쉼표 없는 유효한 JSON인지, 올바른 폴더에 있는지, HopToDesk를 다시 시작했는지 확인하세요. 파일이 읽히면 앱 로그에 Loaded local api.json 줄이 남습니다.
• 82 포트는 여러 자체 시그널 서버를 연결하는 페더레이션 포트입니다. 인터넷에 대해서는 닫아 두세요.
• 시그널 서버는 세션 데이터를 저장하지 않습니다. 무언가 멈춘 것처럼 보이면 서비스를 다시 시작하세요. 장치는 약 1분 안에 스스로 다시 연결합니다.