/
QueryPie를 Jumphost 사용하여 RDP 연동 가이드

QueryPie를 Jumphost 사용하여 RDP 연동 가이드

소개

이 가이드는 Jumphost를 사용하여 그리고 RDP(Remote Desktop Protocol) 서버를 연동하는 방법을 설명합니다. 이 과정을 통해 중복 아이피를 대비하여 안전하고 효율적인 원격 데스크톱 연결을 설정할 수 있습니다.

예상 소요 시간: 30분

구성도

image-20250415-144825.png

사전 요구사항

  • QueryPie 환경 설정

    • Server(JumpHost / Windows), Server Groups, ProxyJump Configurations

  • 각 서버의 IP 주소

    • ALB : rdp.querypie-pe.pro

    • QueryPie : 172.31.60.235, 3.38.40.9

    • JumpHost : 172.31.40.192

    • Windows : 172.31.53.85

  • ALB, Jumphost, RDP 서버에 대한 방화벽 오픈

    • ALB : QueryPie 와 양방향 TCP/443 ( rdp.querypie-pe.pro<-> 3.38.40.9)

    • Jumphost : QueryPie 가 TCP/22 (172.31.60.235 → 172.31.40.192)

    • Windows : JumpHost 가 TCP/13389 (172.31.40.192 → 172.31.53.85)

  • RDP 서버에 QueryPie Server Agent 설치 파일

    • 5월에 릴리즈버전(10.3.0) 이후로는 config에 url를 http://127.0.0.1 변경해서 설치 권장

    • GATEWAY에서 API 로 바로 확인하기때문에 QueryPie 서버 밖으로 안나가도 됨.

설치 과정 요약

  1. QueryPie Gateway 설정 변경 (연결이 안될 시 - Verbose 로그 활성화)

  2. RDP Server Agent 설치 및 설정 (연결이 안될 시 - Verbose 로그 활성화)

  3. QueryPie를 통한 RDP 연결 테스트

  4. 문제 해결 및 최종 확인

단계별 가이드

1. QueryPie Gateway 설정 변경

  1. docker-compose.yml 파일을 열고 app: 섹션 아래에 다음 내용을 추가합니다.

    # Gateway - LOG_LEVEL=Verbose

  2. docker-compose를 재시작하여 변경 사항을 적용합니다.

    docker-compose --env-file compose-env --profile querypie down docker-compose --env-file compose-env --profile querypie up -d

  3. Gateway 로그를 확인하여 연결 상태를 점검합니다.

    docker logs -f querypie-app-1 |grep -i gateway

    예상 결과:

    ## JumpHost 연결 GATEWAY | gateway [VRB] [2025-04-15 13:18:33.424] <q.s.g.GatewayWorker:0FFS5870NIRG/Tunnel> Opening GATEWAY | gateway [VRB] [2025-04-15 13:18:33.433] <q.s.g.GatewayWorker:0FFS5870NIRG/Tunnel> Connecting to SSH host 172.31.40.192:22 GATEWAY | gateway [VRB] [2025-04-15 13:18:33.894] <q.s.g.GatewayWorker:0FFS5870NIRG/Tunnel> Dynamic port forwarding started on 127.0.0.1:16543 GATEWAY | gateway [VRB] [2025-04-15 13:18:33.900] <q.s.g.GatewayWorker:0FFS5870NIRG/Tunnel> Opened ## RDP Agent 설치 전 GATEWAY | gateway [ERR] [2025-04-15 13:19:04.000] <q.s.g.GatewayWorker:0FFS5870NIRG/Tunnel> Failed to connect to 172.31.53.85:13389 over 127.0.0.1:16543 in 30.097 s GATEWAY | Socks5.Exceptions.Socks5ProtocolErrorException: Send command failed! GATEWAY | at Socks5.Clients.Socks5Client.SendCommandAsync(IDuplexPipe pipe, Command command, String dst, IPAddress dstAddress, UInt16 dstPort, CancellationToken token) GATEWAY | at Socks5.Clients.Socks5Client.ConnectAsync(String dst, IPAddress dstAddress, UInt16 dstPort, CancellationToken token) GATEWAY | at QueryPieGateway.Services.Gateway.Tunnel.JumpHostTunnel.ConnectAsync(String host, UInt16 port, CancellationToken cancellationToken) in /src/apps/gateway/QueryPieGateway/Services/Gateway/Tunnel/JumpHostTunnel.cs:line 154 GATEWAY | gateway [WRN] [2025-04-15 13:19:04.013] <q.s.g.GatewayWorker:0FFS5870NIRG/172.31.53.85:13389> Failed to run: Send command failed! ## Windows 까지 연결 GATEWAY | gateway [VRB] [2025-04-15 07:54:16.866] <q.s.g.GatewayService> GetProxyJumps responded 1 items in 4.412 ms GATEWAY | gateway [VRB] [2025-04-15 07:54:59.706] <q.s.g.GatewayWorker:0FFRUJN3PF90/172.31.53.85:13389> Relay Connection aa9763e5-b646-4334-97cb-f59cee373ecd disconnected GATEWAY | gateway [VRB] [2025-04-15 07:54:59.717] <q.s.g.GatewayWorker:0FFRUJN3PF90/Tunnel> Connected to 172.31.53.85:13389 over 127.0.0.1:20901 in 7.067 ms GATEWAY | gateway [VRB] [2025-04-15 07:54:59.724] <q.s.g.GatewayWorker:0FFRUJN3PF90/172.31.53.85:13389> TLS authentication completed in 6.900 ms GATEWAY | gateway [VRB] [2025-04-15 07:54:59.727] <q.s.g.GatewayWorker:0FFRUJN3PF90/172.31.53.85:13389> Relay Connection ecbf44e2-aa33-4417-bb96-2710935ebffb handshake completed in 2.073 ms

2. RDP Server Agent 설치 및 설정

  1. RDP 서버에 QueryPie Server Agent를 설치합니다.

  2. Windows 레지스트리 편집기(regedit.exe)를 실행합니다.

  3. 다음 경로로 이동합니다.

    Computer\\HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\QueryPie Server Agent Persistent

  4. LogLevel 값을 Verbose로 변경하면 바로 적용됩니다.

  5. RDP Agent 로그를 확인하여 연결 상태를 점검합니다.

    예상 결과:

    2025-04-15 14:25:56.149 INF [Thread: 4 .NET TP Worker] [w.a.s.s.m.MainService] Status changed to "Started" 2025-04-15 14:25:58.806 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.t.TlsRouterService] 172.31.40.192:45230 client connected 2025-04-15 14:26:01.905 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.t.TlsRouterService] 172.31.40.192:53496 client connected 2025-04-15 14:26:01.924 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.t.TlsRouterService] TLS Handshake with 172.31.40.192:53496 in 19.351 ms 2025-04-15 14:26:02.100 VRB [Thread: 14 .NET TP Worker] [w.a.s.s.q.g.GatewayService] "Control" Connection "e6afde17-995f-441d-99ba-c5de24c97113" handshake completed in 172.956 ms 2025-04-15 14:26:26.151 ERR [Thread: 14 .NET TP Worker] [w.a.s.s.m.MainService] HeartBeat operation timed out after 30.002 s 2025-04-15 14:26:26.153 INF [Thread: 14 .NET TP Worker] [w.a.s.s.m.MainService] Status changed to "Healthy" 2025-04-15 14:26:26.160 INF [Thread: 14 .NET TP Worker] [m.h.Lifetime] Application started. Hosting environment: Production; Content root path: C:\Program Files\QueryPie Server Access Control 2025-04-15 14:26:26.160 DBG [Thread: 14 .NET TP Worker] [m.e.h.i.Host] Hosting started 2025-04-15 14:26:31.178 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.t.TlsRouterService] 172.31.40.192:58526 client connected 2025-04-15 14:26:32.079 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.t.TlsRouterService] TLS Handshake with 172.31.40.192:58526 in 901.328 ms 2025-04-15 14:26:32.129 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.q.g.GatewayService] "Relay" Connection "2f7f8dc1-b5ab-4672-b455-bad37451bdf9" handshake completed in 49.397 ms 2025-04-15 14:26:32.251 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.m.MainService] HeartBeat Status="Healthy" Message=null in 6.098 s 2025-04-15 14:26:37.123 VRB [Thread: 14 .NET TP Worker] [w.a.s.s.q.g.GatewayService] "Relay" Connection "2f7f8dc1-b5ab-4672-b455-bad37451bdf9" consumed 2025-04-15 14:27:32.275 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.t.TlsRouterService] 172.31.40.192:37550 client connected 2025-04-15 14:27:32.281 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.t.TlsRouterService] TLS Handshake with 172.31.40.192:37550 in 5.876 ms 2025-04-15 14:27:32.283 VRB [Thread: 14 .NET TP Worker] [w.a.s.s.q.g.GatewayService] "Relay" Connection "02348df2-9343-4c41-8592-01c44630664b" handshake completed in 1.810 ms 2025-04-15 14:27:32.396 VRB [Thread: 14 .NET TP Worker] [w.a.s.s.m.MainService] HeartBeat Status="Healthy" Message=null in 140.393 ms 2025-04-15 14:27:37.275 VRB [Thread: 4 .NET TP Worker] [w.a.s.s.q.g.GatewayService] "Relay" Connection "02348df2-9343-4c41-8592-01c44630664b" consumed

3. QueryPie를 통한 RDP 연결 테스트

  1. Server Agents for RDP 메뉴에 생성되고 Status 가 Online 인지 확인합니다.

  2. QueryPie 클라이언트를 실행하고 RDP 연결을 시도합니다.

  3. Gateway 및 RDP Agent 로그를 확인하여 연결이 성공적으로 이루어졌는지 확인합니다.

4. 문제 해결

  • 연결 실패:

    • Gateway 로그에서 Socks5.Exceptions.Socks5ProtocolErrorException: Send command failed! 오류가 발생하는 경우:

      • RDP 서버에 QueryPie Server Agent 설치 확인

      • RDP 서버의 IP 주소 및 포트 번호 확인

      • Jumphost SSH 연결 확인

      • 네트워크 방화벽 설정 확인

    • RDP Agent 로그에서 HeartBeat operation timed out 오류가 발생하는 경우:

      • RDP Agent 서비스 상태 확인

      • QueryPie API 서버 연결 확인

      • 네트워크 연결 상태 확인

QueryPie Gateway와 Server Agent 연결 핵심 요약

QueryPie Gateway와 Server Agent 간의 연결은 다음과 같은 핵심 단계와 특징으로 요약할 수 있습니다.

  • Jump Host 연결: Gateway는 주기적으로 등록된 Jump Host 정보를 받아 SSH 터널을 생성하여 연결을 유지합니다.

  • 게이트웨이 커넥션 형성: Gateway와 Server Agent 간에 SSH/TLS 기반의 단일 게이트웨이 커넥션이 형성됩니다.

  • API 통신: Server Agent는 API와의 모든 통신(heartbeat, audit log, session recording 등)을 게이트웨이 커넥션을 통해 수행합니다.

  • 통신 주체: 게이트웨이 커넥션을 통한 API 요청은 실제로는 Gateway가 주체가 되어 전달합니다.

최종 확인 사항

  • Gateway 및 RDP Agent 로그에서 연결 성공 메시지 확인

  • QueryPie 클라이언트를 통해 RDP 서버에 정상적으로 접속 가능 여부 확인

  • 연결 성능 및 안정성 테스트

 

주의: 이 가이드에 포함된 명령어와 설정은 일반적인 환경을 기준으로 작성되었습니다. 실제 적용 시에는 사용자 본인의 환경에 맞춰 충분히 테스트하고 검증한 후 진행하시기 바랍니다.