Skip to content

Instantly share code, notes, and snippets.

@strarsis
Last active March 22, 2024 13:53
Show Gist options
  • Star 60 You must be signed in to star a gist
  • Fork 12 You must be signed in to fork a gist
  • Save strarsis/e533f4bca5ae158481bbe53185848d49 to your computer and use it in GitHub Desktop.
Save strarsis/e533f4bca5ae158481bbe53185848d49 to your computer and use it in GitHub Desktop.
KeeAgent (for KeePass) on Bash on Windows / WSL (2)

Update (March 2023) (Last checked: March 2024)

Side note: The latest edge build of KeeAgent plugin offers an option for creating a WSL compatible socket. This would be very handy. I already tried to use that socket, but the socket file is currently empty and ssh inside WSL 2 is unable to use it. This appears to be a very new, unreleased and unstable feature. I will follow the development of it and when it finally works (well, for me) I will update this HOWTO. But until then, please use the proven wsl-ssh-agent/npiperelay.exe approach below.

Thanks to the instructions for WSL 2 of the wsl-ssh-agent project, KeeAgent works great in WSL 2 now: https://github.com/rupor-github/wsl-ssh-agent#wsl-2-compatibility The approach uses minimal and well maintained tools.

Mini-changelog

  • (16.03.2024) Add: Ensure 7z and wslvar being available (thanks @johnzielke).
  • (15.03.2024) Add: Note about issues with SSH key agent suddenly not working anymore due to issue with WSL 2 itself (Input/output error).
  • (03.03.2023) Change: Place the npiperelay.exe not onto the devfs filesystem but rather Windows filesystem (thanks @NOBUTOKA) which fixes strange delays when using the SSH keys.

Installation/setup (proven/best approach (wsl-ssh-agent+npiperelay.exe))

  1. Install the KeeAgent plugin for KeePass (2.x).
  2. The OpenSSH Authentication Agent Windows service must be stopped. For being sure that it stays stopped, even after rebooting, disable the service (when it is stopped).
  3. Open the KeeAgent options via KeePass Menu → Tools → Options → KeeAgent Tab. Enable the option Enable agent for Windows OpenSSH. Note: You may have to scroll down a bit in the list to find that option. A possible error message Windows OpenSSH agent is already running. KeeAgent cannot listen for Windows OpenSSH requests. can be ignored, everything will still work fine. (You may still find the Workarounds / troubleshooting section at the end of this HOWTO interesting). No socket files need to be created, the options can be left disabled.
  4. Necessary step (thanks @jacobblock): socat must also be installed:
sudo apt install socat
  1. Place the npiperelay.exe under the Windows filesystem (not onto the WSL system (devfs) filesystem! (thanks @NOBUTOKA)).

Place the npiperelay.exe under /usr/local/bin/npiperelay.exe inside your WSL 2 installation. It must be on the devfs filesystem, see https://github.com/rupor-github/wsl-ssh-agent#wsl-2-compatibility. Note on this change: Although the deprecated approach (of putting npiperelay.exe onto the devfs filesystem) still worked, it introduced strange delays. An user here noticed that placing npiperelay.exe onto the Windows filesystem (one can still symlink it into /usr/local/bin/ if one likes, not only didn't prevent it from running, but also fixed the delay. And indeed, the npiperelay repository itself states the opposite: The npiperelay.exe should be placed onto the windows filesystem, not onto devfs filesystem (interestingly, it would not have even run at that time as WSL hadn't supported running exe files in devfs, but apparently it also would introduce these delays).

Download instructions (thanks @musm; thanks @dmwyatt; thanks @johnzielke):

One suitable directory on the Windows filesystem can be C:\Users\<username>\wsl-keeagent\npiperelay.exe (%USERPROFILE%\wsl-keeagent\npiperelay.exe). You can easily get the compatible path in WSL by using this handy command: wslpath "$(wslvar USERPROFILE)".

# ensure wslvar is available (thanks @johnzielke)
sudo apt install wslu

# just to be sure the path is right
echo $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent)

# create dedicated directory on Windows filesystem
mkdir -p $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent/)

# Download release ZIP into /tmp
# Release v1.5.2
wget https://github.com/rupor-github/wsl-ssh-agent/releases/download/v1.5.2/wsl-ssh-agent.zip -P /tmp

# Ensure 7z is available (thanks @johnzielke)
sudo apt install p7zip-full

# Extract directly to the prepared Windows directory
sudo 7z e -y /tmp/wsl-ssh-agent.zip -o$(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent/)

# Make the file executable
sudo chmod +x $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent/npiperelay.exe)

# (optional) Clean up downloaded ZIP file
rm /tmp/wsl-ssh-agent.zip

# Symlink `npiperelay.exe` back into `/usr/local/bin/npiperelay.exe`
sudo ln -s $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent/npiperelay.exe) /usr/local/bin/npiperelay.exe

What if I followed this guide before this change (pre 3rd March 2023) and I already have npiperelay.exe at /usr/local/bin/npiperelay.exe? No problem, you can just move it out onto the Windows filesystem and even symlink it from there back to /usr/local/bin/npiperelay.exe, as this doesn't reintroduce the delay issue! See the instructions here

  1. Create a new script file ~/bin/wsl-ssh-agent-forwarder (thanks @r2evans) with the following contents:
#!/bin/bash
# Usage: wsl-ssh-agent-forward [ -k | -r ]
# Options:
#    -k    Kill the current process (if exists) and do not restart it.
#    -r    Kill the current process (if exists) and restart it.
# Default operation is to start a process only if it does not exist.

export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock

sshpid=$(ss -ap | grep "$SSH_AUTH_SOCK")
if [ "$1" = "-k" ] || [ "$1" = "-r" ]; then
    sshpid=${sshpid//*pid=/}
    sshpid=${sshpid%%,*}
    if [ -n "${sshpid}" ]; then
        kill "${sshpid}"
    else
        echo "'socat' not found or PID not found"
    fi
    if [ "$1" = "-k" ]; then
        exit
    fi
    unset sshpid
fi

if [ -z "${sshpid}" ]; then
    rm -f $SSH_AUTH_SOCK
    ( setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"/usr/local/bin/npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork & ) >/dev/null 2>&1
fi

Ensure the script (text) file uses proper UNIX (LF) line endings - especially when you create/edit that file from a Windows editor. You can ensure proper UNIX line endings by using the handy dos2unix tool: (e.g. install it using apt-install -y dos2unix) dos2unix ~/bin/wsl-ssh-agent-forwarder. A telling symptom for incorrect line endings are errors like

command not found: ^M
command not found: ^M
parse error near `fi'

The bash script parser encountered characters that are used as line endings on non-UNIX systems, trying to interpret them and failing in the process. (thanks @jetzerb)

  1. Make the script executable: chmod +x ~/bin/wsl-ssh-agent-forwarder
  2. Add the following line to your .bashrc (~/.bashrc) to execute the script above:
# KeeAgent
. ~/bin/wsl-ssh-agent-forwarder

It is important that the script is sourced (. is shorthand for source), not just executed inside .basrc, as otherwise the exported environment variables would be used for the child process. The VSCode terminal is a case for this.

  1. Important: Ensure the socket file exists (even just as an empty placeholder file)!
mkdir -p $HOME/.ssh
touch $HOME/.ssh/agent.sock
  1. (Tip) Reload .bashrc config in current bash session:
$ source ~/.bashrc
  1. You can check the key agent functionality by either connecting via SSH or listing the keys with ssh-add -l (thanks @jacobblock). KeePass should automatically show the authentication prompt and/or notify that SSH keys have been accessed. Note: The KeePass program must be running when KeeAgent should be used. Turning on KeePass autostart could be a good idea.

Workarounds / troubleshooting

ssh-add -l

ssh-add -l is helpful for debugging as it simply tries to connect to the SSH Agent to list the available keys, reporting potential issues.

ssh suddenly doesn't use KeeAgent anymore / "Windows OpenSSH agent is already running" error message / TortoiseGit/TortoiseSVN

Once in a while I encounter the issue where ssh suddenly doesn't use KeeAgent anymore. The "Windows OpenSSH agent is already running" error message when closing/confirming the KeeAgent options dialog (KeePass Menu → Tools → Options → KeeAgent Tab) also appears then. This could be caused by a deeper, underlying issue: I noticed that this happens when updating TortoiseGit or TortoiseSVN (I have both installed). These tools also install their own version of PuTTY/Pageant - this may cause issues with KeeAgent which also tries to run its own SSH agent. Uninstalling TortoiseGit and TortoiseSVN appears to alleviate the issue. Of course, one still wants to use TortoiseGit and TortoiseSVN. An uninstall isn't necessary. It should be sufficient to just disable the PuTTY Pageant(s) that ships with TortoiseGit and TortoiseSVN, so they don't interfere with KeeAgent (and they aren't used anyway).

~/bin/wsl-ssh-agent-forwarder

The ~/bin/wsl-ssh-agent-forwarder script can also be manually invoked with a -r or -k paramter. -r makes it restart the SSH agent forwarding process, while -k kills it without restarting it (see the script comments). When the SSH client has issues using the forwarded SSH agent, using wsl-ssh-agent-forwarder with -r and -k (and restarting/reloading the shell) can fix those issues without the need for rebooting the whole system.

WSL 2 I/O issue

From time to time WSL 2 I/O may simply stop working (unrelated to SSH agent/KeeAgent), until WSL 2 is restarted or the whole system is rebooted. Often the internal VSCode-WSL connection also starts hanging shortly thereafter. When accessing files on non-WSL filesystems, this error then occurs: Input/output error. You can easily check whether this happens, simply by accessing npiperelay.exe, e.g. ls /usr/local/bin/npiperelay.exe. When you get an Input/output error, then WSL 2 or the system has to be rebooted in order to fix this. The SSH Agent usually also stops working until the I/O issue is resolved.

reboot

Some issues (probably some stuck process or socket or pipe) can be fixed by simply rebooting the sytem.

Errata

npiperelay.exe should actually not be used from a devfs filesystem

What if I followed this guide before this change (pre 3rd March 2023) and I already have npiperelay.exe at /usr/local/bin/npiperelay.exe? No problem, you can just move it out onto the Windows filesystem and even symlink it from there back to /usr/local/bin/npiperelay.exe, as this doesn't reintroduce the delay issue!

# just to be sure the path is right
echo $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent)

# create dedicated directory on Windows filesystem
mkdir -p $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent/)

# Move `npiperelay.exe` from the `devfs` filesystem to Windows filesystem
sudo mv /usr/local/bin/npiperelay.exe $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent/)

# (optional) Change file ownership back from `root` to the normal user
sudo chown $USER npiperelay.exe

# Symlink `npiperelay.exe` back into `/usr/local/bin/npiperelay.exe`
sudo ln -s $(wslpath "$(wslvar USERPROFILE)"/wsl-keeagent/npiperelay.exe) /usr/local/bin/npiperelay.exe

Thanks to the symlink, nothing else (like paths) needs to be changed. You are done here, the fix is applied and the delays should be fixed now. No need to reload or restart either, as the binary is invoked each time, hence the next time the SSH agent is used, the binary at new location is used instead, which should fix the delay.

Note: Comments below may relate to the outdated Howto for WSL 1 and msysgit2unix-socket.py!

@Bond246
Copy link

Bond246 commented Sep 6, 2022

Hello everyone,

since some days on my business notebook the agent is not working anymore.
I tried to reinstall everything and checked everything i thought it could be:

  • reinstalled npiperelay
  • rewrite the wsl-ssh-agent-forwarder
  • reconfigured KeeAgent and so on

nothing works

agent.sock is 0 bytes and ssh-add -l just outputs
error fetching identities: communication with agent failed

Same configuration on my private Win11 machine is working fine.

Does anyone have an idea what to check?
Problem is that login via SSH needs much much moments until password-prompt appears which is really annoying.

Thanks

@Bond246
Copy link

Bond246 commented Sep 7, 2022

i don't get a error message like "openssh already running" when opening KeeAgent in Keepass-Options.

But is there any option to check oder any log to review to find a hint for what is going wrong?

@fracaron
Copy link

@Paullik74 I used this setup with Pycharm. To make it work, I had to create a bash script to wrap git:

#!/bin/bash
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
/usr/bin/git "$@"

In pycharm (or PHPStorm), go to Settings - Version Control - Git and choose the path to this bash script as the path to Git executable.

@strarsis
Copy link
Author

strarsis commented Oct 4, 2022

@Bond246; @sdettmer: A new version of KeeAgent recently released: https://github.com/dlech/KeeAgent/releases/tag/v0.13.2
Updating may help with the issue (the CHANGELOG comment Fix crash when process disappears before connecting to Windows OpenSSH agent (thanks Samuel D. Leslie). may relate to your issues).

@antoniozh
Copy link

I am having some delay issues using WSL2, ssh-add -l and other ssh commands using the ssh agent are delayed by 5 seconds, but on cmd they are executed instantly. Anyone else having these issues?

@strarsis
Copy link
Author

@antoniozh: Sometimes I have this issue sometimes. I am not sure what is causing it. 🤔

@antoniozh
Copy link

I suspect that npiperelay as the bridge between the Windows OpenSSH agent and WSL is causing the delay, since on cmd it works just fine.

@tueur-a-gage
Copy link

tueur-a-gage commented Feb 1, 2023

Same issue on my side (long delay for response).

@NOBUTOKA
Copy link

I found the solution for this delay issue.
Do NOT place npiperelay.exe in /usr/local/bin/ or other directory inside WSL.
Instead, place it under directory inside the Windows file system, such as /mnt/c.
If you want, create simlink to npiperelay.exe in /usr/local/bin.
The delay will be disappeared.

Refer: jstarks/npiperelay#26

@strarsis
Copy link
Author

strarsis commented Feb 21, 2023

@NOBUTOKA: That's interesting! Because basically the opposite is known to work/recommended: That npiperelay.exe should be placed inside /usr/local/bin/ or at least on the devfs filesystem in WSL. So these changes improved the performance for you? And it works? 🤔

@NOBUTOKA
Copy link

@strarsis Yes, it works for me.
I had experienced 5 seconds delay in every single ssh access while npiperelay is placed under /usr/local/bin directly,
and after it placed under /mnt/c, there is no delay.

@tueur-a-gage
Copy link

@strarsis, same things for me, npiperelay.exe was on /usr/local/bin as indicated, and since around 1 month (windows update ??) it was very slow. By putting it on /mnt/c/...somewhere and do a symbolic link as indicated by @NOBUTOKA no it works fine.
Many thanks for the trick !

@GlucNAc
Copy link

GlucNAc commented Feb 27, 2023

@strarsis Thanks for the tip it also help me to stop the freezing!

Otherwise, I've made a script to install the connection between my Debian distro and Windows SSH agent : https://gitlab.com/GlucNAc/wsl-use-windows-ssh-agent/-/blob/master/use_windows_ssh_agent.sh

Another interesting point is that you can use Docker images as WSL distro. So I've made a Debian slim docker image with that connection to windows SSH agent, and then I've install it as a WSL2 distro using this script : https://gitlab.com/GlucNAc/wsl-install-docker-image-as-distro/-/blob/master/load_and_run_docker_image_as_wsl_distro.bat.

In that way, no need to make an Ansible script or a custom shell script to install my set up :)

@strarsis
Copy link
Author

strarsis commented Mar 3, 2023

@NOBUTOKA, @tueur-a-gage, @GlucNAc, @antoniozh, @fracaron, @Bond246, @sdettmer:
Important update!
There were contradicting information on where to put the npiperelay.exe, either it has to be on the devfs filesystem or on the Windows filesystem.
It turns out that a) it can be now put onto the Windows filesystem without preventing its proper functionality and b) it should be actually put onto the Windows filesystem as this prevents the strange delay issues some users (including me) experienced (thanks @NOBUTOKA).

The guide as updated to reflect this (step 5), including extra instructions for those who already put the npiperelay.exe into the devfs filesystem, prior to this update:
https://gist.github.com/strarsis/e533f4bca5ae158481bbe53185848d49#:~:text=What%20if%20I%20followed%20this%20guide%20before%20this%20change
It is very simple to change and indeed, the delays went away.

@airtonix
Copy link

does this support the use of security keys like yubikey with the ssh key stored as a resident key?

setting that up is described here:

https://www.stavros.io/posts/u2f-fido2-with-ssh/

@johnzielke
Copy link

Just as a small comment, maybe consider adding sudo apt install p7zip-full wslu to the npiperelay script. Otherwise there are errors during execution and the symlink created points to an invalid location, which then needs to be manually created

@strarsis
Copy link
Author

@johnzielke: Thanks for these improvements! You can see the addition here.

Where should the wslu package installation be added? I assume that the wslu package is required for the wslpath command.
In the instructions above it is assumed that the command is wslpath, while the wslu package provides the wslupath command (both appear to be functionally equal).

@johnzielke
Copy link

johnzielke commented Mar 16, 2024 via email

@strarsis
Copy link
Author

strarsis commented Mar 16, 2024

provides the wslvar command

This makes sense, I added the commands with sudo. Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment