Ssh Agent Wsl

Windows ssh-agent 연동

이 프로그램은 Windows의 ssh-agent 서비스와 통신하여, WSL 내부에서 ssh-add -l 명령으로 Windows에 등록된 SSH 키 목록을 확인하고, ssh 명령으로 해당 키를 사용할 수 있도록 환경 변수를 설정합니다.

쉘 통합 지원

사용자는 ~/.bashrc 또는 ~/.zshrc에 eval $(ssh-agent-wsl -r) 명령을 추가하여, 새 셸이 시작될 때마다 자동으로 Windows ssh-agent와 연결할 수 있습니다. -r 옵션은 이미 실행 중인 에이전트가 있으면 재사용하고, 없으면 새로 시작합니다.

Win32 헬퍼 파이프 통신

ssh-agent-wsl은 WSL 내부에서 실행되지만, 실제 키 관리는 Windows 측에서 이루어집니다. 이를 위해 pipe-connector.exe라는 Win32 헬퍼 바이너리를 실행하여, 파이프를 통해 Windows ssh-agent 서비스와 통신합니다. 이 헬퍼는 기본적으로 프로그램과 동일한 디렉터리에서 탐색되며, -H 옵션으로 경로를 지정할 수 있습니다.

Scoop을 통한 설치

Scoop 패키지 관리자를 사용하는 경우, 다음 명령어로 extras 버킷을 추가하고 패키지를 설치할 수 있습니다:

scoop bucket add extras
scoop install ssh-agent-wsl

설치 후, 프로그램은 셸 초기화 파일(.bashrc 등)에 추가할 명령을 출력합니다. 이 명령은 최신 바이너리를 GitHub에서 직접 다운로드하여 설치합니다.

수동 바이너리 설치

GitHub 릴리스 페이지에서 아카이브를 다운로드한 후, Windows 파일 시스템 내의 드라이브(예: C:tools)에 압축을 풀어야 합니다. WSL에서는 lxfs 마운트(WSL 내부 파일 시스템)에서 Win32 바이너리를 실행할 수 없으므로, 반드시 drvfs 경로(예: /mnt/c/tools)에 풀어야 합니다.

Windows 측 ssh-agent 서비스 시작

먼저 Windows에서 OpenSSH 인증 에이전트 서비스가 실행 중인지 확인하고, 자동 시작으로 설정해야 합니다. PowerShell을 관리자 권한으로 열어 다음 명령을 실행합니다:

Start-Service ssh-agent
Set-Service -StartupType Automatic ssh-agent

셸 초기화 파일 설정

ssh-agent-wsl의 압축을 풀은 디렉터리 경로를 확인하고, ~/.bashrc 또는 ~/.zshrc 파일에 다음 줄을 추가합니다:

eval $(/경로/ssh-agent-wsl -r)

여기서 -r 옵션은 이미 실행 중인 에이전트가 있으면 재사용하고, 없으면 새로 시작하도록 합니다. eval 명령은 출력된 환경 변수를 현재 셸에 적용하여, ssh 및 ssh-add가 Windows ssh-agent를 사용하도록 합니다.

설정 적용 및 확인

셸을 재시작하거나 source ~/.bashrc 명령을 실행한 후, ssh-add -l을 입력하면 Windows ssh-agent에 등록된 키 목록이 표시되어야 합니다. 키가 정상적으로 인식된다면, WSL 내에서 ssh 명령으로 Windows 측 키를 사용한 인증이 가능해집니다.

제한 사항·확인 사항

• WSL 내부 파일 시스템(lxfs)에서는 Win32 바이너리를 실행할 수 없으므로, 반드시 Windows 드라이브 경로(drvfs, 예: /mnt/c)에 파일을 풀어야 합니다.
• WSL 콘솔을 종료할 때 pipe-connector.exe가 높은 CPU 사용률에 빠질 수 있는 알려진 문제가 있으며, 이는 WSL과 Win32 간 세션 처리 차이로 인한 것입니다. 이를 방지하려면 셸 종료 시 ssh-agent-wsl -k 명령을 수동으로 실행하여 프로세스를 종료하는 것이 권장됩니다.
• screen 또는 tmux 내에서 SSH_AUTH_SOCK 변수가 설정된 상태에서 WSL 콘솔을 종료하고 다른 창에서 세션을 재연결하면, 에이전트 연결이 작동하지 않을 수 있습니다. 이 경우 ssh-agent-wsl를 tmux 시작 전에 실행하거나, Windows 10 버전 1809 이상에서는 -b 플래그를 사용해 보완할 수 있습니다.
• 이 프로그램은 Windows 10 버전 1703(Creators Update) 이상에서만 작동하며,それより 오래된 버전에서는 Windows/Ubuntu 간 호환성 기능이 없어 동작하지 않습니다.
• Windows와 WSL 간 상호작용은 WSL을 시작한 사용자의 자격 증명으로 이루어지므로, 원격으로 WSL에 접근 권한을 주는 경우 해당 사용자의 SSH 키에 노출될 수 있는 보안 고려 사항이 있습니다.

최신 버전·업데이트

현재 버전은 2.5이며, 공식 README에 따르면 이 프로젝트는 더 이상 업데이트되지 않고 아카이브될 예정입니다. 개발자는 사용자에게 더 나은 대안인 wsl-ssh-agent 프로젝트로 이전할 것을 권장하고 있습니다.