{"id":13719920,"url":"https://github.com/vuori/weasel-pageant","last_synced_at":"2025-05-07T12:30:37.657Z","repository":{"id":174877815,"uuid":"95376598","full_name":"vuori/weasel-pageant","owner":"vuori","description":"Deprecated: An ssh-agent compatible helper for interacting with Pageant from processes running on the Windows Subsystem for Linux.","archived":true,"fork":false,"pushed_at":"2020-06-15T09:57:42.000Z","size":80,"stargazers_count":248,"open_issues_count":1,"forks_count":18,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-14T09:39:03.212Z","etag":null,"topics":["pageant","putty","ssh","ssh-agent","ssh-agent-forwarding","windows-subsystem-linux","wsl"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vuori.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-06-25T17:56:32.000Z","updated_at":"2024-11-11T05:12:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"889058b3-b7f5-4ec9-8738-b34a2efe690b","html_url":"https://github.com/vuori/weasel-pageant","commit_stats":null,"previous_names":["vuori/weasel-pageant"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuori%2Fweasel-pageant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuori%2Fweasel-pageant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuori%2Fweasel-pageant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vuori%2Fweasel-pageant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vuori","download_url":"https://codeload.github.com/vuori/weasel-pageant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252876286,"owners_count":21818156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pageant","putty","ssh","ssh-agent","ssh-agent-forwarding","windows-subsystem-linux","wsl"],"created_at":"2024-08-03T01:00:57.716Z","updated_at":"2025-05-07T12:30:37.161Z","avatar_url":"https://github.com/vuori.png","language":"C","funding_links":[],"categories":["C","WSL Tools"],"sub_categories":["10. GUI Apps"],"readme":"weasel-pageant development has ended\n------------------------------------\n\n**End of life notice:** Native support for Unix domain sockets appeared over two years ago\nin Windows 10 1803. At this point it no longer makes sense to maintain `weasel-pageant`, which relies\non the older pipe-based and bug-prone WSL-Win32 interop method. Therefore, with the exception of critical\nsecurity patches, *support for `weasel-pageant` will cease on April 14, 2020*; this date is also the EOL\nfor Windows 10 1709, the last desktop edition of Windows without support for Unix domain sockets.\n\nUsers are advised to migrate to more modern equivalents. I use\n[WinCryptSSHAgent](https://github.com/buptczq/WinCryptSSHAgent), which offers convenient\nsupport for PIV smartcard certificates and also promises WSL2/Hyper-V support in the latest\nversion. [wsl-ssh-pageant](https://github.com/benpye/wsl-ssh-pageant) appears to offer a more\ntraditional alternative for Pageant users, but I have not tested it myself.\n\n*Update, Apr 14 2020*: The EOL date has arrived and hence the issue tracker will be closed. Extended support\nfor security issues continues until June 14, 2020.\n\n*Update, Jun 15 2020*: Final end of support date has passed. No further changes will be accepted.\n\nAll users are advised to upgrade to a supported alternative as soon as possible.\n\nThanks to all the users over the years and happy SSH'ing.\n---\n\n`weasel-pageant` allows you to use SSH keys held by [PuTTY's](https://www.chiark.greenend.org.uk/~sgtatham/putty/)\nPageant \"daemon\" (or compatible, such as the version of Pageant included in \n[PuTTY-CAC](https://github.com/NoMoreFood/putty-cac) or the SSH agent mode in\n[Gpg4win](https://www.gpg4win.org/)) from inside the\n[Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about).\n\nThe source (and this documentation) is heavily based on\n[`ssh-pageant`](https://github.com/cuviper/ssh-pageant) 1.4 by Josh Stone, which allows\ninteracting with Pageant from Cygwin/MSYS programs.\n\n`weasel-pageant` works like `ssh-agent`, except that it leaves the key storage to\nPuTTY's Pageant.  It sets up an authentication socket and prints the environment\nvariables, which allows the OpenSSH client to use it. It works by executing from the\nWSL side a Win32 helper program which interfaces with Pageant and communicating with\nit through pipes.\n\nIt is probably the most useful if your SSH keys can't be copied to the WSL environment,\nsuch as when using a smart card for SSH authentication. Testing is mainly performed\nwith Pageant-CAC, though Gpg4win has been seen to work in the past. Note that when\nusing Gpg4win, only the SSH agent part will be forwarded. There is no support for\nforwarding the GPG agent socket.\n\n**SECURITY NOTICE:** All the usual security caveats applicable to WSL apply.\nMost importantly, all interaction with the Win32 world happens with the credentials of\nthe user who started the WSL environment. In practice, *if you allow someone else to\nlog in to your WSL environment remotely, they may be able to access the SSH keys stored in\nyour Pageant with `weasel-pageant`.* This is a fundamental feature of WSL; if you\nare not sure of what you're doing, do not allow remote access to your WSL environment\n(e.g. by starting an SSH server).\n\n`weasel-pageant` does not work on a version of Windows 10 older\nthan 1703 (\"Creators Update\"), because it requires the\n[Windows/Ubuntu interoperability support](https://blogs.msdn.microsoft.com/wsl/2016/10/19/windows-and-ubuntu-interoperability/)\nfeature shipped with that version. It has been verified to work with versions\nup to and including Windows 10 release 1909.\n\n## Installation\n\n### From binaries\n\nDownload the zip file from the [releases page](https://github.com/vuori/weasel-pageant/releases)\nand unpack it in a convenient location *on the Windows part of your drive*.\n\nBecause WSL can only execute Win32 binaries from `drvfs` locations, `weasel-pageant`\n*will not work* if unpacked inside the WSL filesystem (onto an `lxfs` mount).\nAdvanced users may place only `helper.exe` on `drvfs`, but in general it is easier\nto keep the pieces together.\n\n### From source\n\nA VS2019 project is included. You will need the \"Desktop development with C++\" and\n\"Linux development with C++\" features. To build:\n\n1. Optional: In Visual Studio, set up an SSH connection to a Linux machine. If you want\n   to build using your local WSL environment, the default configuration should work.\n\n2. Optional: If you intend to work on the Linux sources, copy the contents of\n   `/usr/include` into `linux/include` under the project directory.\n   This is not required for the build, but will make Intellisense more useful.\n\n3. Hit Build Solution. Both the Linux executable and the Win32 helper will be built.\n\nIf you want to create a binary package, you can use the `create_pkg.py` script\nat the root of the project. This should work with Python 3.4 or newer on either\nWindows or Linux.\n\nAlternatively you can build the Linux executable directly on Linux and only use\nVisual Studio for the Win32 helper (no Makefile or similar is supplied at the moment).\nIn theory the helper should be buildable with MinGW-w64 for a fully Linux-based\nbuild, but this has not been tested.\n\nThe release binaries have been built with VS2019 16.2.0.\n\n## Usage\n\nUsing `weasel-pageant` is generally similar to using `ssh-agent` on Linux and\nsimilar operating systems. \n\n1. Ensure that PuTTY's Pageant is running (and holds your SSH keys).\n    * `weasel-pageant` does not start Pageant itself.\n    * Recommended: Add Pageant to your Windows startup/Autostart configuration\n      so it is always available.\n\n2. Edit your `~/.bashrc` (or `~/.bash_profile`) to add the following:\n\n        eval $(\u003clocation where you unpacked the zip\u003e/weasel-pageant -r)\n\n    To explain:\n\n    * This leverages the `-r`/`--reuse` option which will only start a new daemon if\n      one is not already running in the current window. If the agent socket appears to\n      be active, it will just print environment variables and exit.\n\n    * Using `eval` will set the environment variables in the current shell.\n      By default, `weasel-pageant` tries to detect the current shell and output\n      appropriate commands. If detection fails, then use the `-S SHELL` option\n      to define a shell type manually.\n\n3. Restart your shell or type (when using bash) `. ~/.bashrc`. Typing `ssh-add -l`\n   should now list the keys you have registered in Pageant.\n\n### Note regarding the `-a` flag\n\nA previous version of this manual suggested using the `-a` flag to set a fixed\nsocket path which could be reused by all open WSL consoles. Due to the limitations of\nWSL-Win32 interop, this causes problems including hanging SSH agent connections\nand hanging `conhost` processes in many use cases. Unless you have a specific need\nfor a fixed socket path, it is better to remove the `-a` flag froom your `weasel-pageant`\nstartup command. A `weasel-pageant` instance will then be started for each WSL console\nyou open.\n\nHowever, with Windows 10 version 1809 or newer, it is now possible to use a fixed\nsocket path reliably. In addition to the `-a` flag, also set the `-b` to prevent\nthe `weasel-pageant` process from exiting with its parent console. For example\nto create a persistent socket in your home directory:\n\n    eval $(\u003clocation where you unpacked the zip\u003e/weasel-pageant -rb -a $HOME/.weasel-pageant.sock)\n\n## Options\n\n`weasel-pageant` aims to be compatible with `ssh-agent` options, with a few extras:\n\n    $ weasel-pageant -h\n    Usage: weasel-pageant [options] [command [arg ...]]\n    Options:\n      -h, --help     Show this help.\n      -v, --version  Display version information.\n      -c             Generate C-shell commands on stdout.\n      -s             Generate Bourne shell commands on stdout.\n      -S SHELL       Generate shell command for \"bourne\", \"csh\", or \"fish\".\n      -k             Kill the current weasel-pageant.\n      -d             Enable debug mode.\n      -q             Enable quiet mode.\n      -a SOCKET      Create socket on a specific path.\n      -r, --reuse    Allow to reuse an existing -a SOCKET.\n      -H, --helper   Path to the Win32 helper binary (default: /mnt/c/Program Files/weasel-pageant/helper.exe).\n      -t TIME        Limit key lifetime in seconds (not supported by Pageant).\n      -b             Do not exit when tty closes (only use on Windows 10 version 1809 and newer).\n\nBy default, the Win32 helper will be searched for in the same directory where `weasel-pageant`\nis installed. If you have placed `helper.exe` elsewhere, the `-H` flag can be used to set the\nlocation.\n\n## Known issues\n\n* If you have an `SSH_AUTH_SOCK` variable set inside `screen`, `tmux` or similar,\n  you exit the WSL console from which the `screen` was *initially started* and attach\n  to the session from another window, the agent connection will not be usable. This is\n  due to WSL/Win32 interop limitations. This can be circumvented on Windows 10 version\n  1809 and newer by adding the `-b` flag to the `weasel-pageant` command line.\n\n* There is a slight delay when exiting a WSL console before the window actually closes.\n  This is due to a polling loop which works around a WSL incompatibility with Unix session\n  semantics.\n\n## Uninstallation\n\nTo uninstall, just remove the extracted files and any modifications you made\nto your shell initialization files (e.g. `.bashrc`).\n\n## Version History\n\n* 2017-06-25: 1.0 - Initial release.\n* 2018-03-30: 1.1 - Fixed console/agent connection hangs and enabled restarting of the helper.\n  **Upgrade note:** remove the `-a` flag from the `weasel-pageant` command line unless you\n  know you need it.\n* 2019-01-06: 1.2 - Fixed unexpected daemon exits caused by a signal handling issue.\n* 2019-03-10: 1.3 - Added the `-b` flag to prevent the daemon from exiting when its\n  parent terminal closes. Requires Windows 10 1809 or newer. Thanks to @niklasholm for\n  the patch.\n* 2019-08-04: 1.4 - Added a workaround for a Win32 interop bug in Windows 10 1903 that wedged\n  the WSL init process into an infinite loop. Also switched to static linking the Linux\n  binary for compatibility with non-glibc distributions such as Alpine.\n\n## Bug reports and contributions\n\nBug reports may be sent using Github's [issues feature](https://github.com/vuori/weasel-pageant/issues).\nInclude your `weasel-pageant` version and command line, describe how to reproduce the problem,\nand include logs from running in debug mode if possible: run `weasel-pageant` with the `-d` flag\nin either subprocess mode or in a separate terminal in daemon mode (copy/paste the environment\nvariables to your main terminal).\n\nPlease do not send bug reports by e-mail.\n\nPull requests are also welcome, though if you intend to do major changes it's recommended to open an\nissue first.\n\n## Related projects\n\nThere are several projects that provide similar functionality (I have not tested all\nof these):\n\n  * [ssh-pageant](https://github.com/cuviper/ssh-pageant): the Cygwin program on\n    which `weasel-pageant` is based on.\n  * [wsl-ssh-pageant](https://github.com/benpye/wsl-ssh-pageant): a Win32 app that\n    uses the Unix domain socket support introduced in Windows 10 1803 to provide\n    agent connectivity.\n  * [ssh-agent-wsl](https://github.com/rupor-github/ssh-agent-wsl): a fork of\n    `weasel-pageant` that includes support for using keys held by Microsoft's\n    SSH Agent service.\n\n\n------------------------------------------------------------------------------\nCopyright 2017-2019  Valtteri Vuorikoski \u0026 contributors\n\nBased on `ssh-pageant`, copyright (C) 2009-2014  Josh Stone  \n\nLicensed under the GNU GPL version 3 or later, http://gnu.org/licenses/gpl.html\n\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law.\n\nSee the `COPYING` file for license details.  \nPart of `weasel-pageant` is derived from the PuTTY program, whose original license is\nin the file `COPYING.PuTTY`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvuori%2Fweasel-pageant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvuori%2Fweasel-pageant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvuori%2Fweasel-pageant/lists"}