Repository files navigation

End of life notice: Native support for Unix domain sockets appeared over two years agoin Windows 10 1803. At this point it no longer makes sense to maintainweasel-pageant, which relieson the older pipe-based and bug-prone WSL-Win32 interop method. Therefore, with the exception of criticalsecurity patches,support forweasel-pageant will cease on April 14, 2020; this date is also the EOLfor Windows 10 1709, the last desktop edition of Windows without support for Unix domain sockets.

Users are advised to migrate to more modern equivalents. I useWinCryptSSHAgent, which offers convenientsupport for PIV smartcard certificates and also promises WSL2/Hyper-V support in the latestversion.wsl-ssh-pageant appears to offer a moretraditional alternative for Pageant users, but I have not tested it myself.

Update, Apr 14 2020: The EOL date has arrived and hence the issue tracker will be closed. Extended supportfor security issues continues until June 14, 2020.

Update, Jun 15 2020: Final end of support date has passed. No further changes will be accepted.

All users are advised to upgrade to a supported alternative as soon as possible.

weasel-pageant allows you to use SSH keys held byPuTTY'sPageant "daemon" (or compatible, such as the version of Pageant included inPuTTY-CAC or the SSH agent mode inGpg4win) from inside theWindows Subsystem for Linux.

The source (and this documentation) is heavily based onssh-pageant 1.4 by Josh Stone, which allowsinteracting with Pageant from Cygwin/MSYS programs.

weasel-pageant works likessh-agent, except that it leaves the key storage toPuTTY's Pageant. It sets up an authentication socket and prints the environmentvariables, which allows the OpenSSH client to use it. It works by executing from theWSL side a Win32 helper program which interfaces with Pageant and communicating withit through pipes.

It is probably the most useful if your SSH keys can't be copied to the WSL environment,such as when using a smart card for SSH authentication. Testing is mainly performedwith Pageant-CAC, though Gpg4win has been seen to work in the past. Note that whenusing Gpg4win, only the SSH agent part will be forwarded. There is no support forforwarding the GPG agent socket.

SECURITY NOTICE: All the usual security caveats applicable to WSL apply.Most importantly, all interaction with the Win32 world happens with the credentials ofthe user who started the WSL environment. In practice,if you allow someone else tolog in to your WSL environment remotely, they may be able to access the SSH keys stored inyour Pageant withweasel-pageant. This is a fundamental feature of WSL; if youare not sure of what you're doing, do not allow remote access to your WSL environment(e.g. by starting an SSH server).

weasel-pageant does not work on a version of Windows 10 olderthan 1703 ("Creators Update"), because it requires theWindows/Ubuntu interoperability supportfeature shipped with that version. It has been verified to work with versionsup to and including Windows 10 release 1909.

Download the zip file from thereleases pageand unpack it in a convenient locationon the Windows part of your drive.

Because WSL can only execute Win32 binaries fromdrvfs locations,weasel-pageantwill not work if unpacked inside the WSL filesystem (onto anlxfs mount).Advanced users may place onlyhelper.exe ondrvfs, but in general it is easierto keep the pieces together.

A VS2019 project is included. You will need the "Desktop development with C++" and"Linux development with C++" features. To build:

1. Optional: In Visual Studio, set up an SSH connection to a Linux machine. If you wantto build using your local WSL environment, the default configuration should work.

2. Optional: If you intend to work on the Linux sources, copy the contents of/usr/include intolinux/include under the project directory.This is not required for the build, but will make Intellisense more useful.

3. Hit Build Solution. Both the Linux executable and the Win32 helper will be built.

If you want to create a binary package, you can use thecreate_pkg.py scriptat the root of the project. This should work with Python 3.4 or newer on eitherWindows or Linux.

Alternatively you can build the Linux executable directly on Linux and only useVisual Studio for the Win32 helper (no Makefile or similar is supplied at the moment).In theory the helper should be buildable with MinGW-w64 for a fully Linux-basedbuild, but this has not been tested.

The release binaries have been built with VS2019 16.2.0.

Usingweasel-pageant is generally similar to usingssh-agent on Linux andsimilar operating systems.

1. Ensure that PuTTY's Pageant is running (and holds your SSH keys).

   • weasel-pageant does not start Pageant itself.
   • Recommended: Add Pageant to your Windows startup/Autostart configurationso it is always available.

2. Edit your~/.bashrc (or~/.bash_profile) to add the following:

    eval $(<location where you unpacked the zip>/weasel-pageant -r)

   To explain:

   • This leverages the-r/--reuse option which will only start a new daemon ifone is not already running in the current window. If the agent socket appears tobe active, it will just print environment variables and exit.

   • Usingeval will set the environment variables in the current shell.By default,weasel-pageant tries to detect the current shell and outputappropriate commands. If detection fails, then use the-S SHELL optionto define a shell type manually.

3. Restart your shell or type (when using bash). ~/.bashrc. Typingssh-add -lshould now list the keys you have registered in Pageant.

A previous version of this manual suggested using the-a flag to set a fixedsocket path which could be reused by all open WSL consoles. Due to the limitations ofWSL-Win32 interop, this causes problems including hanging SSH agent connectionsand hangingconhost processes in many use cases. Unless you have a specific needfor a fixed socket path, it is better to remove the-a flag froom yourweasel-pageantstartup command. Aweasel-pageant instance will then be started for each WSL consoleyou open.

However, with Windows 10 version 1809 or newer, it is now possible to use a fixedsocket path reliably. In addition to the-a flag, also set the-b to preventtheweasel-pageant process from exiting with its parent console. For exampleto create a persistent socket in your home directory:

eval $(<location where you unpacked the zip>/weasel-pageant -rb -a $HOME/.weasel-pageant.sock)

weasel-pageant aims to be compatible withssh-agent options, with a few extras:

$ weasel-pageant -hUsage: weasel-pageant [options] [command [arg ...]]Options:  -h, --help     Show this help.  -v, --version  Display version information.  -c             Generate C-shell commands on stdout.  -s             Generate Bourne shell commands on stdout.  -S SHELL       Generate shell command for "bourne", "csh", or "fish".  -k             Kill the current weasel-pageant.  -d             Enable debug mode.  -q             Enable quiet mode.  -a SOCKET      Create socket on a specific path.  -r, --reuse    Allow to reuse an existing -a SOCKET.  -H, --helper   Path to the Win32 helper binary (default: /mnt/c/Program Files/weasel-pageant/helper.exe).  -t TIME        Limit key lifetime in seconds (not supported by Pageant).  -b             Do not exit when tty closes (only use on Windows 10 version 1809 and newer).

By default, the Win32 helper will be searched for in the same directory whereweasel-pageantis installed. If you have placedhelper.exe elsewhere, the-H flag can be used to set thelocation.

• If you have anSSH_AUTH_SOCK variable set insidescreen,tmux or similar,you exit the WSL console from which thescreen wasinitially started and attachto the session from another window, the agent connection will not be usable. This isdue to WSL/Win32 interop limitations. This can be circumvented on Windows 10 version1809 and newer by adding the-b flag to theweasel-pageant command line.

• There is a slight delay when exiting a WSL console before the window actually closes.This is due to a polling loop which works around a WSL incompatibility with Unix sessionsemantics.

To uninstall, just remove the extracted files and any modifications you madeto your shell initialization files (e.g..bashrc).

• 2017-06-25: 1.0 - Initial release.
• 2018-03-30: 1.1 - Fixed console/agent connection hangs and enabled restarting of the helper.Upgrade note: remove the-a flag from theweasel-pageant command line unless youknow you need it.
• 2019-01-06: 1.2 - Fixed unexpected daemon exits caused by a signal handling issue.
• 2019-03-10: 1.3 - Added the-b flag to prevent the daemon from exiting when itsparent terminal closes. Requires Windows 10 1809 or newer. Thanks to @niklasholm forthe patch.
• 2019-08-04: 1.4 - Added a workaround for a Win32 interop bug in Windows 10 1903 that wedgedthe WSL init process into an infinite loop. Also switched to static linking the Linuxbinary for compatibility with non-glibc distributions such as Alpine.

Bug reports may be sent using Github'sissues feature.Include yourweasel-pageant version and command line, describe how to reproduce the problem,and include logs from running in debug mode if possible: runweasel-pageant with the-d flagin either subprocess mode or in a separate terminal in daemon mode (copy/paste the environmentvariables to your main terminal).

Please do not send bug reports by e-mail.

Pull requests are also welcome, though if you intend to do major changes it's recommended to open anissue first.

There are several projects that provide similar functionality (I have not tested allof these):

• ssh-pageant: the Cygwin program onwhichweasel-pageant is based on.
• wsl-ssh-pageant: a Win32 app thatuses the Unix domain socket support introduced in Windows 10 1803 to provideagent connectivity.
• ssh-agent-wsl: a fork ofweasel-pageant that includes support for using keys held by Microsoft'sSSH Agent service.

Copyright 2017-2019 Valtteri Vuorikoski & contributors

Based onssh-pageant, copyright (C) 2009-2014 Josh Stone

Licensed under the GNU GPL version 3 or later,http://gnu.org/licenses/gpl.html

This is free software: you are free to change and redistribute it.There is NO WARRANTY, to the extent permitted by law.

See theCOPYING file for license details.
Part ofweasel-pageant is derived from the PuTTY program, whose original license isin the fileCOPYING.PuTTY.