doo-blog

Obsidian Vault Blog

PARA/03_Resources/R001_개발_레퍼런스(참고문서)/개발 환경과 도구/WireGuard VPN에서 VS Code 원격 SSH 연결 문제 해결 가이드.md

WireGuard VPN에서 VS Code 원격 SSH 연결 문제 해결 가이드

2025년 3월 21일

개요

간만에 마음에 드는 카페를 찾았고, 기분 좋게 맥을 켰는데, 원격 서버에 접속이 안된다.
내 환경은 macOS에서 WireGuard VPN을 통해 사설 네트워크의 RHEL 서버(192.168.0.2)에 접속하는 구성이었다. 지금까지 정상 작동하던 원격 SSH 접속이 갑자기 불안정해졌다.
문제 발생부터 해결까지의 과정을 정리해본다.

문제 상황

VS Code의 Remote-SSH로 서버에 접속했을 때 SSH 연결이 몇 십 초 만에 끊어지고 재연결을 반복하는 현상이 발생했다.
에디터 하단에는 "Attempting to reconnect..."이라는 메시지가 계속 표시되었고, 원격 터미널은 제대로 응답하지 않았다.
이상하게도 VS Code Remote-SSH 환경만, 동작하지 않았다.

터미널 앱에서 SSH로 직접 접속해서 간단한 명령을 실행할 때는 문제없이 작동했다.
근데 터미널에서도 top 같은 대화형(long-running interactive) 명령어를 실행하면 터미널 출력이 멈춰버렸다.

같은 네트워크 내 Windows PC에서 VPN 없이 직접 해당 서버에 VS Code Remote-SSH로 접속했을 때도 정상적으로 작동했다. 문제는 macOS + WireGuard VPN을 통한 접속 경로에서만 발생하는 것으로 보였다. 요약하자면:

  • Mac + WireGuard VPN 환경:
    • VS Code Remote-SSH 연결 안됨 (연결 끊김/재연결 반복)
    • 터미널 접속은 되나, top, tail 등의 명령 실행 시 프리즈 현상
  • Windows + 로컬 네트워크 직결: VS Code Remote-SSH 정상 작동

네트워크 연결 자체(Ping, 일반 SSH)는 멀쩡한데 VS Code의 원격 SSH 세션만 불안정한 독특한 상황이었다.

원인 추정

문제 상황을 정리해보니 **네트워크 연결 경로(WireGuard VPN)**에 무언가 문제가 있을 것으로 추정되었다. 로컬 네트워크에서는 문제 없지만 VPN 경로에서만 SSH 세션이 끊긴다면, VPN 터널 설정이나 네트워크 패킷 처리와 관련된 이슈일 가능성이 높았다.

특히 의심된 것은 MTU(Maximum Transmission Unit) 문제였다. MTU란 한 네트워크 패킷에 담을 수 있는 최대 크기를 의미하는데, VPN 터널 사용 시 encapsulation(캡슐화) 오버헤드로 인해 실제 사용 가능한 MTU가 줄어든다. 만약 경로상의 MTU보다 큰 크기의 패킷이 발생하면 패킷이 잘게 쪼개지거나(Fragmentation) 최악의 경우 전달이 안 되어 세션이 정지될 수 있다.

일반적인 ping이나 간단한 SSH 명령은 패킷이 작아서 문제 없지만, top처럼 출력이 연속적으로 많아지는 상황에서는 더 큰 패킷이 발생해 문제가 드러났을 가능성이 있었다.

게다가 맥 환경은 IPv6 기반 망을 IPv4로 터널링하는 DS-Lite 환경인데, 이런 이중 스택 환경에서는 MTU 관련 문제로 패킷 손실이 생길 수 있다는 보고도 있었다. WireGuard의 기본 MTU 값(1420 바이트)이 네트워크 경로에서 너무 크게 설정되어 있어 SSH 세션이 불안정했던 것으로 추측되었다.

문제 해결 과정

원인을 추정한 후, 하나씩 확인하고 조치를 취해보았다.

  1. 네트워크 기본 연결 확인: ping 192.168.0.2로 서버와의 기본 ICMP 응답을 점검했다. 핑 응답은 양호했기에 기본적인 네트워크 연결은 정상임을 확인할 수 있었다.

  2. SSH 개별 접속 테스트: 터미널에서 ssh user@192.168.0.2 방식으로 VS Code를 거치지 않고 직접 SSH 접속을 해봤다. 로그인 및 간단한 명령 실행까지는 잘 되었고, 일정 시간 유지도 문제 없었다. 이로써 SSH 데몬 설정이나 인증 문제는 없음을 확인했다.

  3. 부하 걸리는 작업 시도: 정상적인 SSH 세션에서 yes 명령 (무한 출력)이나 top 등을 실행하여 대용량 출력 상황을 의도적으로 만들어 봤다. 예상대로 몇 초 후 세션이 멈추는 현상이 재현되었다. 이는 VS Code 유무와 상관없이 VPN 터널을 통한 SSH 연결에서 큰 데이터 전송 시 문제가 발생한다는 것을 의미했다.

  4. VPN 없는 환경 재확인: 다른 PC (Windows)에서 같은 작업을 해봤을 때, VPN을 통하지 않으면 yes나 top 실행 시에도 세션이 정상 작동했다. 이로써 원인은 VPN 터널링 구간에 한정됨을 거의 확신할 수 있었다.

  5. WireGuard 설정 점검 및 MTU 조정: 문제의 핵심 의심 요소였던 MTU 설정을 조정해보기로 했다. WireGuard 클라이언트 설정 파일에 들어가 MTU = 1280으로 설정 값을 낮추었다. 1280 바이트는 IPv6 표준에서 권고하는 최소 MTU 값이고 여러 사례에서 안전한 값으로 통한다. 기본 MTU보다 작게 설정하면 패킷이 작게 쪼개져 전송되고, 경로 중간에서 잘리는 일 없이 안정적으로 전달될 가능성이 높아진다.

    # WireGuard 클라이언트 설정 예시 (/etc/wireguard/wg0.conf)
[Interface]
PrivateKey = (비밀키)
Address = 10.0.0.2/24
MTU = 1280  # MTU 값을 1280으로 조정
DNS = 1.1.1.1
 
[Peer]
PublicKey = (서버 공개키)
Endpoint = 1.2.3.4:51820
AllowedIPs = 192.168.0.0/24

6. **재시작 및 테스트**: MTU 값을 변경한 후 WireGuard 터널을 재시작하고 다시 VS Code Remote-SSH로 서버에 접속했다. 그리고 문제가 됐던 `top` 명령을 실행해봤다. 놀랍게도 **이제 SSH 세션이 끊기지 않고 안정적으로 유지**되었다. VS Code 터미널에서도 `Attempting to reconnect` 같은 메시지가 더 이상 표시되지 않았다.
    

## 해결 결과 및 요약

결국 문제의 원인은 **WireGuard VPN의 MTU 설정 값이 너무 크게 잡혀 있었던 것**으로 추정된다. MTU를 1280으로 낮추자 SSH 세션이 더 이상 끊기지 않고 정상 작동했으니, **패킷 단편화(fragmentation)** 문제였던 것이다. 요약하면, **VPN 터널 구간에서 패킷이 잘게 나뉘거나 손실되면서 VS Code 원격 세션이 불안정**해졌던 것이다. MTU 조정을 통해 패킷 크기를 제약하니 **경로상 어디에서도 문제 없이 전송**될 수 있었고, 결과적으로 연결 안정성이 확보되었다.

이번 사례에서 알 수 있듯이, 겉으로 보기엔 **SSH 자체 문제 같아 보여도 실제 원인은 네트워크 전송 레벨**에 있을 수 있다. 특히 VPN을 사용하거나 특수한 망 환경(예: IPv6 터널링, PPPoE 등)에선 **MTU 값을 세심히 조절**해야 예기치 않은 전송 문제를 피할 수 있다.

## 추가 팁 및 교훈

마무리로, 비슷한 문제를 겪는 분들을 위한 몇 가지 팁과 교훈을 정리한다:

- **MTU 문제 진단하기**: SSH처럼 **TCP 기반 연결이 갑자기 멈춘다면** MTU/fragmentation 이슈를 의심해볼 필요가 있다. 
  진단 방법으로는 `ping` 명령에 `-s`(패킷 크기) 옵션과 `-M do`(fragmentation 방지) 옵션을 사용해 볼 수 있다. 예를 들어 `ping -M do -s 1400 <서버 IP>`처럼 점점 패킷 크기를 키워가며 보내볼 수 있다. 
  특정 크기 이상에서 응답이 없다면 경로 MTU 한계에 부딪힌 것이다. 
  마치 큰 물건을 들고 작은 문을 통과하려는 것과 같다. 결국 물건이 문보다 크면 못 지나가는 법이다.
    
- **WireGuard MTU 조정 가이드**: WireGuard의 기본 MTU는 보통 1420으로 설정되지만, 환경에 따라 최적값이 다를 수 있다. 
  **IPv6를 통한 터널**이나 **여러 라우팅 경유** 환경이라면 **1280으로 설정**하는 것을 권장한다. 
  1280바이트는 IPv6 표준 최소값이기도 해서 대부분의 네트워크 장비가 호환되도록 만들어져 있기 때문이다.
    
- **다른 VPN의 경우**: OpenVPN 등 다른 VPN을 사용 중인데 유사한 증상이 있다면, 해당 VPN의 **MSS 클램프(MSS clamping)** 옵션이나 MTU 관련 설정(`--fragment` 옵션 등)을 확인해볼 필요가 있다. 
  예를 들어 OpenVPN에는 `mssfix`나 `tun-mtu` 설정으로 패킷 크기를 조정하는 방법이 있다. 원리는 같아서, **패킷 크기를 제한**하여 전송 경로에서 문제없이 통과시키는 것이다.
    
- **문제 해결 태도**: 한 가지 문제가 발생하면 **여러 층위를 의심**해보는 것이 중요하다. 이번 경우 처음엔 VS Code나 SSH 소프트웨어 버그처럼 보였지만, 결국 **네트워크 계층**에서 답을 찾았다. 이렇듯 클라이언트-서버 애플리케이션 문제의 원인이 항상 애플리케이션 자체에 있는 것은 아니며, **환경적인 요소(VPN, 방화벽, 네트워크 설정 등)**를 함께 고려해야 한다.
    
- **로그와 커뮤니티 활용**: VS Code Remote-SSH의 출력 로그(`Remote-SSH: Show Log`)나 서버 측 syslog를 확인했다면 좀 더 빠르게 단서를 찾을 수도 있었을 것이다. 운 좋게 MTU를 바로 의심했지만, 일반적으로는 로그에 `Write failed: Broken pipe` 또는 `channel frozen` 등의 힌트가 남기도 한다. 또한 구글링이나 관련 커뮤니티를 검색해보면 유사 사례를 발견할 수 있으니 적극 활용해야 한다.
    

문제를 해결하고 나니 비로소 원격 개발 환경이 **안정**을 되찾았다. 이번 경험을 통해 VPN 사용 시 **네트워크 세부 설정**이 얼마나 중요한지 깨달았다. 특히 어떤 값을 조정해야 할지 모르는 상태에서 여러 가지를 바꿔보는 과정은 정말 지치는 일이었다. 카공하러 가면서 원대한 계획을 했지만 결국 오후 내내 트러블 슈팅만 하다가 집에 오게 된 것은 참으로 슬프지 않을 수 없다


WireGuard 환경에서 VSCode Remote SSH로 개발 서버 포트가 연결되지 않는 별도 이슈는 [트러블슈팅 - VSCode Remote SSH에서 localhost3000 안됨](/posts/PARA/03_Resources/R001_%EA%B0%9C%EB%B0%9C_%EB%A0%88%ED%8D%BC%EB%9F%B0%EC%8A%A4(%EC%B0%B8%EA%B3%A0%EB%AC%B8%EC%84%9C)/%ED%8A%B8%EB%9F%AC%EB%B8%94%EC%8A%88%ED%8C%85/%ED%8A%B8%EB%9F%AC%EB%B8%94%EC%8A%88%ED%8C%85%20-%20VSCode%20Remote%20SSH%EC%97%90%EC%84%9C%20localhost3000%20%EC%95%88%EB%90%A8)에서 다룬다.

댓글

첫 번째 댓글을 남겨보세요.