Skip to content

Instantly share code, notes, and snippets.

@gavinwy
Forked from strarsis/howto.md
Created March 2, 2023 08:10
Show Gist options
  • Save gavinwy/eb9961af218083de1b4aaaf3791de434 to your computer and use it in GitHub Desktop.
Save gavinwy/eb9961af218083de1b4aaaf3791de434 to your computer and use it in GitHub Desktop.
KeeAgent (for KeePass) on Bash on Windows / WSL (2)

Update (February 2022)

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.

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 (experimental) 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 /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. Download instructions (thanks @musm; thanks @dmwyatt):
wget https://github.com/rupor-github/wsl-ssh-agent/releases/download/v1.5.2/wsl-ssh-agent.zip -P /tmp
sudo 7z e -y /tmp/wsl-ssh-agent.zip -o/usr/local/bin/
sudo chmod +x /usr/local/bin/npiperelay.exe
rm /tmp/wsl-ssh-agent.zip
  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 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.

reboot

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

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

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