Skip to content

Commit 525ee89

Browse files
mamemame
committed
Update README.md
1 parent 607f772 commit 525ee89

File tree

1 file changed

+66
-53
lines changed

1 file changed

+66
-53
lines changed

‎README.md‎

Lines changed: 66 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,20 @@ This tool allows from WSL2 to use the ssh-agent service on Windows host.
99
Put `wsl2-ssh-agent` binary in your favorite directory in WSL2, for example, `$HOME/`.
1010

1111
```
12+
# For x86-64 architecture
1213
curl -L -O https://github.com/mame/wsl2-ssh-agent/releases/latest/download/wsl2-ssh-agent
13-
```
14-
If you are under ARM64 architecture, download the `arm64` binary instead:
15-
```
14+
15+
# For ARM64 architecture
1616
curl -L -O https://github.com/mame/wsl2-ssh-agent/releases/latest/download/wsl2-ssh-agent-arm64
1717
```
18-
Change permisions so the binary is executable:
18+
19+
Then, make the binary executable:
20+
1921
```
2022
chmod 755 wsl2-ssh-agent
2123
```
2224

23-
**If you are using ArchLinux, you can install the [wsl2-ssh-agent](https://aur.archlinux.org/packages/wsl2-ssh-agent) package from the AUR (maintained by @Hill-98).**
25+
Note for Arch Linux users: You can install the [wsl2-ssh-agent](https://aur.archlinux.org/packages/wsl2-ssh-agent) package from the AUR (maintained by @Hill-98).
2426

2527
### 2. Modify your shell's rc file
2628

@@ -44,74 +46,85 @@ end
4446

4547
### 3. Reopen your terminal
4648

47-
Close and reopen the terminal and execute `ssh your-machine`.
48-
The command should communicate with ssh-agent.exe service.
49+
Close and reopen the terminal.
50+
You should now be able to run `ssh your-server` and connect using the keys managed by the Windows ssh-agent.exe service.
4951

50-
## Tip: For pageant.exe
52+
## Tip: Using with pageant.exe
5153

52-
If you want to use with the named pipe provided by pageant.exe, you can use the `-pipename` option.
53-
You can configure wsl2-ssh-agent as follows:
54+
If you want to use the named pipe provided by pageant.exe, you can use the `-pipename` option.
55+
For example:
5456

5557
```
5658
eval $($HOME/wsl2-ssh-agent -pipename $(grep -oP "IdentityAgent \"//\./pipe/\K[^\"]+" /mnt/c/.../pageant.conf))
5759
```
5860

59-
(The author does not use pageant.exe. Let me know if it does not work.)
61+
(Note: The author does not use pageant.exe. If this doesn't work, please open an issue.)
6062

6163
## Troubleshooting
6264

63-
### Make sure that ssh-agent.exe is working properly
65+
### Confirm ssh-agent.exe is working
6466

65-
* Open the "Services" app and check that "OpenSSH Authentication Agent" service is installed and running.
66-
* Check that `ssh your-machine` works perfect on cmd.exe or PowerShell, not on WSL2.
67+
* Open the "Services" app on Windows and confirm the "OpenSSH Authentication Agent" service is installed and running.
68+
* Check that `ssh your-server` works perfectly from cmd.exe or PowerShell (i.e., outside of WSL2).
6769

68-
### Check the log of ssh
70+
### Check the ssh client log
6971

70-
* You may want to run `ssh -v your-machine` and read the log. If everything is good, you should see the following log.
72+
* You may want to run `ssh -v your-server` and read the log. If everything is working correctly, you should see lines similar to these.
7173

7274
```
7375
debug1: get_agent_identities: bound agent to hostkey
7476
debug1: get_agent_identities: agent returned XXX keys
7577
```
7678

77-
### Check the log of wsl2-ssh-agent
79+
### Check the wsl2-ssh-agent log
7880

79-
* Run `wsl2-ssh-agent` in verbose and foreground mode and read the log. This is an example output.
81+
To see detailed logs, stop the agent and restart it in verbose foreground mode.
8082

8183
```
8284
# Stop the existing server if any
8385
$ $HOME/wsl2-ssh-agent -stop
8486
8587
# Run in foreground mode
8688
$ $HOME/wsl2-ssh-agent --verbose --foreground
87-
[L] 2023/02/10 20:30:00 check the version of ssh.exe
88-
[L] 2023/02/10 20:30:01 the version of ssh.exe: "OpenSSH_for_Windows_8.6p1, LibreSSL 3.4.3"
89-
[L] 2023/02/10 20:30:01 ssh-agent.exe seems to be old; ignore OpenSSH extension messages
90-
[L] 2023/02/10 20:30:01 start listening on /home/mame/.ssh/wsl2-ssh-agent.sock
91-
[L] 2023/02/10 20:30:01 invoking [W] in PowerShell.exe
92-
[W] 2023/02/10 21:51:09 ready: PSVersion 5.1.22621.963
93-
[L] 2023/02/10 20:30:02 [W] invoked successfully
94-
[L] 2023/02/10 20:30:05 ssh: connected
95-
[L] 2023/02/10 20:30:05 ssh -> [L] (XXX B)
96-
[L] 2023/02/10 20:30:05 ssh <- [L] (5 B) <dummy for OpenSSH ext.>
97-
[L] 2023/02/10 20:30:05 ssh -> [L] (5 B)
98-
[L] 2023/02/10 20:30:05 [L] -> [W] (5 B)
99-
[W] 2023/02/10 21:51:12 [L] -> [W] -> ssh-agent.exe (5 B)
100-
[W] 2023/02/10 21:51:12 [L] <- [W] <- ssh-agent.exe (XXX B)
101-
[L] 2023/02/10 20:30:05 [L] <- [W] (XXX B)
102-
[L] 2023/02/10 20:30:05 ssh <- [L] (XXX B)
103-
[L] 2023/02/10 20:30:05 ssh -> [L] (XXX B)
104-
[L] 2023/02/10 20:30:05 [L] -> [W] (XXX B)
105-
[W] 2023/02/10 21:51:12 [L] -> [W] -> ssh-agent.exe (XXX B)
106-
[W] 2023/02/10 21:51:12 [L] <- [W] <- ssh-agent.exe (XXX B)
107-
[L] 2023/02/10 20:30:05 [L] <- [W] (XXX B)
108-
[L] 2023/02/10 20:30:05 ssh <- [L] (XXX B)
109-
[L] 2023/02/10 20:30:05 ssh: closed
110-
```
111-
112-
## How wsl2-ssh-agent works
113-
114-
Linux ssh client connects to ssh-agent via a UNIX domain socket, while ssh-agent.exe service on Windows is listening on a named pipe. This command connects those two in the following mechanism.
89+
[L] 2025/07/29 19:51:27 start listening on /path/to/wsl2-ssh-agent.sock
90+
[L] 2025/07/29 19:51:27 invoking [W] in PowerShell.exe
91+
[W] 2025/07/29 19:51:28 ssh-agent.exe version: 9.5.4.1 (ignoreOpenSSHExtensions: False)
92+
[L] 2025/07/29 19:51:28 [W] invoked successfully
93+
[W] 2025/07/29 19:51:28 ready: PSVersion 5.1.22621.5624
94+
[W] 2025/07/29 19:51:28 [W] named pipe: openssh-ssh-agent
95+
[L] 2025/07/29 19:51:33 ssh: connected
96+
[L] 2025/07/29 19:51:33 ssh -> [L] (XXX B)
97+
[L] 2025/07/29 19:51:33 [L] -> [W] (XXX B)
98+
[W] 2025/07/29 19:51:33 [W] named pipe: connected
99+
[W] 2025/07/29 19:51:33 [L] -> [W] -> ssh-agent.exe (XXX B)
100+
[L] 2025/07/29 19:51:33 [L] <- [W] (XXX B)
101+
[W] 2025/07/29 19:51:33 [L] <- [W] <- ssh-agent.exe (XXX B)
102+
[L] 2025/07/29 19:51:33 ssh <- [L] (XXX B)
103+
[L] 2025/07/29 19:51:33 ssh -> [L] (XXX B)
104+
[L] 2025/07/29 19:51:33 [L] -> [W] (XXX B)
105+
[W] 2025/07/29 19:51:33 [W] named pipe: disconnected
106+
[W] 2025/07/29 19:51:33 [W] named pipe: connected
107+
[W] 2025/07/29 19:51:33 [L] -> [W] -> ssh-agent.exe (XXX B)
108+
[L] 2025/07/29 19:51:33 [L] <- [W] (XXX B)
109+
[L] 2025/07/29 19:51:33 ssh <- [L] (XXX B)
110+
[W] 2025/07/29 19:51:33 [L] <- [W] <- ssh-agent.exe (XXX B)
111+
[W] 2025/07/29 19:51:33 [W] named pipe: disconnected
112+
[L] 2025/07/29 19:51:33 ssh -> [L] (XXX B)
113+
[L] 2025/07/29 19:51:33 [L] -> [W] (XXX B)
114+
[W] 2025/07/29 19:51:33 [W] named pipe: connected
115+
[W] 2025/07/29 19:51:33 [L] -> [W] -> ssh-agent.exe (XXX B)
116+
[L] 2025/07/29 19:51:33 [L] <- [W] (XXX B)
117+
[L] 2025/07/29 19:51:33 ssh <- [L] (XXX B)
118+
[W] 2025/07/29 19:51:33 [L] <- [W] <- ssh-agent.exe (XXX B)
119+
[W] 2025/07/29 19:51:33 [W] named pipe: disconnected
120+
[L] 2025/07/29 19:51:33 ssh: closed
121+
[L] 2025/07/29 19:51:33 ssh: connected
122+
[L] 2025/07/29 19:51:33 ssh: closed
123+
```
124+
125+
## How It Works
126+
127+
The SSH client in Linux communicates with an agent via a UNIX domain socket, while the ssh-agent.exe service on Windows listens on a named pipe. This tool connects the two using the following mechanism:
115128

116129
```mermaid
117130
graph TB
@@ -124,14 +137,14 @@ subgraph Windows
124137
end
125138
```
126139

127-
* wsl2-ssh-agent listens on a UNIX domain socket (by default, $HOME/.ssh/wsl2-ssh-agent.sock).
128-
* wsl2-ssh-agent invokes PowerShell.exe as a child process, which can communicate with ssh-agent.exe service via a named pipe.
129-
* wsl2-ssh-agent and PowerShell.exe communicates via stdin/stdout thanks to WSL2 interop.
140+
* wsl2-ssh-agent starts a server that listens on a UNIX domain socket in WSL2 (by default, $HOME/.ssh/wsl2-ssh-agent.sock).
141+
* It then invokes a PowerShell.exe child process on the Windows host.
142+
* The wsl2-ssh-agent process in WSL2 and the PowerShell process in Windows communicate via their stdin/stdout streams, which are connected by the WSL interop layer. The PowerShell process then forwards communication to the Windows ssh-agent.exe service via its named pipe.
130143

131-
## Note
144+
## Note on Windows OpenSSH Compatibility
132145

133-
Usually, ssh and ssh-agent should be the same version. However, OpenSSH on Ubuntu 22.04 is 8.9, while Windows bundles OpenSSH 8.6 (on my machine, as of this writing).
146+
My motivation for creating wsl2-ssh-agent was to work around a compatibility issue in OpenSSH. [The newer SSH client (version 8.9+) sends an extended protocol message](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.agent) that the older Windows agent (before 8.9) doesn't understand, which can cause the connection to fail. ([Japanese article](https://zenn.dev/qnighy/articles/8b992970b86653))
134147

135-
[OpenSSH has extended the ssh-agent protocol since 8.9](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.agent). However, ssh-agent.exe does not understand the extended message and will not communicate properly. ([Japanese article](https://zenn.dev/qnighy/articles/8b992970b86653))
148+
To fix this, wsl2-ssh-agent checks your Windows OpenSSH version. When it detects an older version (before 8.9), it intercepts these unsupported messages and sends a valid, compatible response back to the client. This prevents the old agent from failing and allows the connection to work.
136149

137-
To address this issue, wsl2-ssh-agent does not pass the extended message to ssh-agent.exe. Instead, it swallows the message and reply a dummy SSH_AGENT_SUCCESS message to ssh client. Note that this may reduce the security strength. Please use this tool at your own risk.
150+
Modern Windows now includes an updated OpenSSH (9.5 or newer), so this problem no longer exists on up-to-date systems. The fix is automatically applied only when necessary, so you can use this tool on any system without changing your settings.

0 commit comments

Comments
 (0)