온프레미스

작동 방식

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

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

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

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

대시보드도 자체 서버에 두어야 하나요? 문의하기

시작하기 전에

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

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

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

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

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

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

스크립트가 하는 일

• 프로세서(Intel, AMD 또는 ARM)에 맞는 시그널 서버를 /home/hopsignal 폴더로 내려받습니다.
• 다운로드한 파일을 공개된 SHA256SUMS 목록과 대조하고, 일치하지 않으면 아무것도 변경하지 않고 중단합니다.
• hopsignal이라는 systemd 서비스를 만들고 부팅할 때마다 시작합니다.
• 권장 연결 제한값과 무작위 페더레이션 비밀번호로 서버를 시작합니다. 비밀번호는 root만 접근할 수 있는 /home/hopsignal/hopsignal.env에 저장됩니다.
• 서비스가 응답을 멈추면 다시 시작하고 로그가 100MB를 넘으면 순환시키는 cron 감시자를 추가합니다.
• ufw가 활성화된 경우 ufw에서 TCP 80 포트를 엽니다.

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

1. 이 페이지 상단의 OS 스위치를 Windows로 바꾸고 Download를 클릭합니다. hopsignal.exe라는 파일 하나를 받게 됩니다.
2. C:\hopsignal 같은 폴더를 만들고 hopsignal.exe를 그 안으로 옮깁니다.
3. 같은 폴더에 fedlist.txt라는 빈 텍스트 파일을 만듭니다.
4. 관리자 권한으로 명령 프롬프트를 열고 서버를 시작합니다.

cd C:\hopsignal
for /f %i in ('powershell -NoProfile -Command "[guid]::NewGuid().ToString('N')"') do @(setx /M FEDPWD %i >nul & set FEDPWD=%i)
hopsignal.exe --ADDR 0.0.0.0:80 --FEDLIST fedlist.txt --FEDADDR 127.0.0.1:82 --LOGFILE hs.log

두 번째 줄은 무작위 페더레이션 비밀번호를 Windows 시스템 설정으로 저장하므로 서버 명령줄에 절대 나타나지 않습니다.

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 --FEDLIST C:\hopsignal\fedlist.txt --FEDADDR 127.0.0.1:82 --LOGFILE C:\hopsignal\hs.log"
schtasks /Run /TN HopSignal

Docker를 사용한 1단계: 컨테이너에서 시그널 서버 실행하기

hoptodesk/hopsignal 이미지는 Intel, AMD, ARM 호스트에서 동일한 시그널 서버를 실행합니다. 권장 제한값으로 시작하세요:

docker run -d --name hopsignal --restart unless-stopped -p 80:80 \
  -e HS_MAX_MESSAGE_KB=64 -e HS_QUEUE_LIMIT=256 -e HS_MAX_CONNS=20000 \
  -e HS_CONNS_PER_IP=100 -e HS_LOOKUPS_PER_IP=20 \
  -e HS_IDLE_TIMEOUT=300 -e HS_UPGRADE_TIMEOUT=10 \
  hoptodesk/hopsignal

각 HS_ 값은 제한 하나를 켭니다: 메시지 크기(KB), 연결당 대기 중인 메시지 수, 열린 연결 수, 주소당 초당 새 연결 수와 조회 수, 유휴 시간(초), 핸드셰이크 시간(초). 값을 생략하면 그 제한은 꺼진 상태로 유지됩니다.

컨테이너를 대시보드 계정에 자동으로 연결하려면 대시보드의 Set up a private network에 있는 Docker 명령을 사용하세요. HS_SETUP_TOKEN과 HS_DASHBOARD_URL이 추가되고, 서버는 처음 시작할 때 한 번 주소를 보고합니다.

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

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

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

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

netstat -an | find ":80 "

Docker에서는 컨테이너와 로그를 확인합니다:

docker ps --filter name=hopsignal
docker logs hopsignal

아무 컴퓨터에서나 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처럼 서버에 TLS로 접근하는 경우 rendezvous 대신 rendezvousssl 키를 사용하세요. turnservers 목록에는 하나 이상의 릴레이를 넣습니다. 일반 연결은 프로토콜을 turn으로, TLS 연결은 turn-tls로 설정합니다. 버전 키는 그대로 두세요.

위 예시처럼 모든 포트 번호를 따옴표로 감싸세요. 따옴표 없이 숫자로만 쓴 포트는 앱이 무시합니다.

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

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

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

Linux에서는 /root/.config/hoptodesk에 사본을 하나 더 두세요. 사용자가 로그인하기 전 로그인 화면에서는 앱이 이 사본을 사용합니다.

옵션 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 (Default)를 선택합니다.

Android와 iOS에서는 설정을 열고 네트워크 섹션에서 Use HopToDesk Network를 끈 다음 파일의 URL을 입력하세요. EMM으로 관리되는 휴대폰은 관리 설정 custom_api_url로 같은 URL을 받을 수 있습니다.

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

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

새 서버: 대시보드에서 설정, Network Settings, Set up a private network를 엽니다. In my AWS account 또는 On my own server를 고릅니다. 서버가 시작할 때 주소를 보고하고, 연결된 모든 기기가 설정을 받습니다. 입력할 것이 없습니다.

이미 운영 중인 서버: 설정을 직접 입력합니다.

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 항목까지 함께 서버를 제거하려면:

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

문제 해결

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