WSL2 포트 포워딩 자동화 스크립트 README

1. 개요

이 스크립트는 Windows 운영체제에서 WSL2(Windows Subsystem for Linux 2)의 동적 IP 주소를 자동으로 감지하여, Windows 호스트의 특정 포트로 들어오는 요청을 WSL2 내부로 전달하는 포트 포워딩(Port Forwarding) 규칙을 자동으로 설정하는 PowerShell 스크립트이다.

WSL2는 재부팅할 때마다 내부 IP 주소가 변경되므로, 외부 네트워크에서 WSL2 내부의 SSH, 웹 서버 등 각종 서비스로 안정적인 접속을 유지하기 위해 이 스크립트가 필요하다.

2. 주요 기능

• 지능적인 시작 대기 (Intelligent Startup Wait):

  • 스크립트 실행 시, WSL 서비스가 완전히 부팅되어 IP 주소를 할당받을 때까지 주기적으로 확인하며 대기한다.
  • PC 부팅 속도에 관계없이 안정적으로 IP를 가져온 후 작업을 시작하여, 단순 시간 지연 방식의 불안정성과 비효율성을 해결했다.

• 동적 IP 자동 감지:

  • wsl hostname -I 명령어를 통해 현재 WSL2의 IP 주소를 자동으로 가져온다.

• 포트 포워딩 규칙 자동 갱신:

  • 스크립트 실행 시마다 설정된 포트에 대한 기존의 netsh portproxy 규칙을 먼저 삭제하고, 감지된 최신 IP 주소로 새로운 규칙을 생성하여 항상 정확한 경로를 유지한다.

• 실행 로그 상세 기록:

  • 스크립트의 모든 실행 과정(시작, IP 확인 시도, 성공/실패, 규칙 삭제/생성 등)을 타임스탬프와 함께 지정된 로그 파일에 기록하여, 문제 발생 시 원인을 쉽게 추적할 수 있다.

• UTF-8 인코딩 완벽 지원:

  • 스크립트 파일 자체(UTF-8 with BOM 저장 권장), 스크립트 실행 환경, 로그 파일 출력까지 모두 UTF-8 인코딩을 기준으로 동작하여 한글 깨짐 현상을 원천적으로 방지한다.

3. 설정 방법

스크립트 상단의 **'사용자 설정 영역'**에서 네 가지 값을 자신의 환경에 맞게 수정해야 한다.

• $listenPort: Windows 호스트에서 외부 요청을 수신할 포트 번호를 지정한다.
• $logFilePath: 스크립트의 실행 기록을 저장할 로그 파일의 전체 경로와 파일명을 지정한다.
• $maxRetries: WSL의 IP 주소 확인을 위한 최대 시도 횟수를 지정한다.
• $retryIntervalSeconds: IP 주소 확인 재시도 간의 대기 시간(초)을 지정한다.

4. 사용 방법

이 스크립트는 netsh 명령어 실행을 위해 관리자 권한이 반드시 필요하다. 부팅 시 완전 자동 실행을 위해서는 Windows 작업 스케줄러에 등록하는 것이 가장 올바른 방법이다.

1. 작업 스케줄러(taskschd.msc)를 실행한다.
2. 새로운 작업을 생성하고, [일반] 탭에서 가장 높은 수준의 권한으로 실행 옵션을 체크한다.
3. [트리거] 탭에서 작업을 시작할 시점으로 **로그온할 때**를 선택한다.
4. [동작] 탭에서 실행할 프로그램을 powershell.exe로 지정하고, 인수 추가 란에 -ExecutionPolicy Bypass -File "C:\경로\스크립트파일명.ps1" 과 같이 스크립트의 전체 경로를 입력한다.
5. (선택) [조건] 탭에서 노트북 사용 시 전원 연결과 무관하게 실행되도록 관련 옵션을 해제하고, [설정] 탭에서 작업 실패 시 재시도 옵션을 설정하면 안정성을 더욱 높일 수 있다.

5. 시스템 요구사항

• Windows 10 버전 2004 이상 또는 Windows 11
• WSL2 설치 및 배포판 구성 완료
• PowerShell