ssh-pageant

An SSH authentication agent for Cygwin/MSYS that links OpenSSH to PuTTY's Pageant.

ssh-pageant is a tiny tool for Windows that allows you to use SSH keys from
PuTTY's Pageant in Cygwin and MSYS shell environments.

You can use ssh-pageant to automate SSH connections from those shells, which
is useful for services built on top of SSH, like SFTP file transfers or pushing
to secure git repositories.

ssh-pageant works like ssh-agent, except that it leaves the key storage to
PuTTY's Pageant. It sets up an authentication socket and prints the environment
variables, which allows OpenSSH connections to use it.

Installation

You can install the latest release of ssh-pageant for Cygwin using the
standard setup.exe program. For MSYS2, just run pacman -S ssh-pageant.

Otherwise, you can use the readily-available binary releases:

1. Download the pre-built 32-bit or 64-bit release for Cygwin, or
   the 32-bit release for MSYS.

2. Just copy the exe into your PATH and ensure it is executable:

    $ cp ssh-pageant.exe /usr/bin/
    $ chmod 755 /usr/bin/ssh-pageant.exe
   

3. Optionally, copy the manpage as well:

    $ cp ssh-pageant.1 /usr/share/man/man1/
   

The INSTALL file describes how to build and install ssh-pageant from source.

Usage

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

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

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

    # ssh-pageant
    eval $(/usr/bin/ssh-pageant -r -a "/tmp/.ssh-pageant-$USERNAME")
   

   To explain:

   • This leverages the -r/--reuse option (available since 1.3) in
     combination with -a SOCKET, which will only start a new daemon if the
     specified path does not accept connections already. If the socket appears
     to be active, it will just set SSH_AUTH_SOCK and exit.

   • The exact path used for -a is arbitrary. The socket will be created
     with only user-accessible permissions, as long as the filesystem is not
     mounted noacl, but you may still want to use a more private path than
     shown above on multi-user systems.

   • When using this, the ssh-pageant daemon remains to be active (and
     visible in your task manager). You should not kill the process, since
     open shells might still be using the socket.

   • Using eval will set the environment variables in the current shell.
     By default, ssh-pageant tries to detect the current shell and output
     appropriate commands. If detection fails, then use the -S SHELL option
     to define a shell type manually.

You could also rename ssh-pageant to ssh-agent and then use something like
keychain to manage a single instance (the approach of Charade), but that is
unnecessary with the --reuse option.

It may be possible to share a Cygwin socket with external tools like
msysgit, if you use a socket path accessible by
both runtimes. Use cygpath --windows {path} to help normalize paths for
system-wide use.

Options

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

$ ssh-pageant -h
Usage: ssh-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 ssh-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.
  -t TIME        Limit key lifetime in seconds (not supported by Pageant).

Known issues

• Pageant is running, but the agent reports SSH_AGENT_FAILURE.
  • Fixed in release 1.1.
  • Ensure you have PuTTY Pageant 0.62 or later.
  • Another known workaround is to launch Pageant using cygstart.

Uninstallation

To uninstall, just remove the copied files:

$ rm /usr/bin/ssh-pageant.exe
$ rm /usr/share/man/man1/ssh-pageant.1

Version History

• 2014-11-23: 1.4 - MSYS support and more robust socket paths.
• 2013-06-23: 1.3 - Allow reusing existing sockets via -r/--reuse.
• 2012-11-24: 1.2 - Mirror the exit status of child processes.
• 2011-06-12: 1.1 - Fixed SID issues.
• 2010-09-20: 1.0 - Initial release.

Contributions

ssh-pageant is considered stable at this point and rarely needs to be updated.

However, in case you encounter any issues, feel free to create one. Pull
requests are even more welcome. :)

Project History

Once upon a time I privately developed a Cygwin terminal based on PuTTY, which
I wanted because I could use Cygwin-native ptys with PuTTY's interface. As part
of that I also added an SSH_AUTH_SOCK shim which talked to Pageant. Then I
discovered MinTTY, which does the terminal part much better.

The author wasn't interested in including the SSH_AUTH_SOCK functionality
though, so instead I split that out into this program, ssh-pageant, and I
finally published the code in April 2009.

Links

• PuTTY: An SSH client for Windows (including the Pageant authentication agent).
• Cygwin: A Linux-like environment for Windows.
• MSYS: Another Linux-like environment, made to supplement MinGW.
• MSYS2: The modern successor to MSYS, staying closer to Cygwin development.
• OpenSSH: The SSH client shipped by Cygwin/MSYS.
• Charade: The friendly competition to ssh-pageant.
• weasel-pageant: ssh-pageant for the Windows Subsystem for Linux.

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 the COPYING file for license details.
Part of ssh-pageant is derived from the PuTTY program, whose original license is
in the file COPYING.PuTTY.