diff --git a/INSTALL b/INSTALL index f66083b..fa815f8 100644 --- a/INSTALL +++ b/INSTALL @@ -1,7 +1,8 @@ FROM THE BINARY PACKAGE: -Just copy the exe into your PATH, e.g.: +Just copy the exe into your PATH and ensure it is executable, e.g.: $ cp ssh-pageant.exe /usr/bin/ +$ chmod 755 /usr/bin/ssh-pageant.exe Optionally, copy the manpage as well: $ cp ssh-pageant.1 /usr/share/man/man1/ diff --git a/README b/README deleted file mode 100644 index b542a4f..0000000 --- a/README +++ /dev/null @@ -1,84 +0,0 @@ -ssh-pageant 1.3 ------------------------------------------------------------------------------- -Home: http://cuviper.github.io/ssh-pageant/ -Issues: http://github.com/cuviper/ssh-pageant/issues ------------------------------------------------------------------------------- - -ssh-pageant is an SSH authentication agent for Cygwin that links OpenSSH to -PuTTY's Pageant. It acts very much like ssh-agent, except it leaves the key -storage to Pageant. You can use ssh-pageant to automate SSH connections from -the Cygwin shell, and I find this is most helpful for those services built on -top of SSH, like SFTP file transfers or pushing to secure git repositories. - -Like ssh-agent, ssh-pageant starts by setting up the auth socket, and then it -prints the environment variables that will let openssh connections use that -socket. The usual approach is to use your shell's "eval" command to load -those environment variables automatically. By default, ssh-pageant outputs -sh-style commands, but the -c option will change that to csh-style commands. - -For example, I just add the following lines to my bash configuration: - -~/.bash_profile: - if [ -z "$SSH_AUTH_SOCK" -a -x /usr/bin/ssh-pageant ]; then - eval $(/usr/bin/ssh-pageant -q) - fi - trap logout HUP - -~/.bash_logout: - if [ -x /usr/bin/ssh-pageant -a ! -z "$SSH_PAGEANT_PID" ]; then - eval $(/usr/bin/ssh-pageant -qk 2>/dev/null) - fi - -This will start a new ssh-pageant instance for each login shell. That's not a -big deal since they all talk to the same Pageant instance, so you only have to -add your ssh keys once. You could also rename ssh-pageant to ssh-agent and -then use something like keychain to manage a single instance, but I don't find -that necessary. - -Another option starting with ssh-pageant 1.3 is "--reuse". When used along -with "-a SOCKET", ssh-pageant will only start a new daemon if that specific -path is not already accepting connections. If that path does appear active, -ssh-pageant will just set SSH_AUTH_SOCK and exit. When using this, you should -not kill ssh-pageant in your logout scripts, as other shells might be reusing -the same socket. - -Note that Pageant itself is not started by ssh-pageant. It is recommended to -add Pageant to the Windows startup configuration so it is always available. - -If Pageant is running, but the agent still reports SSH_AGENT_FAILURE, this -might be an old SID bug. This is believed to be generally fixed in release -1.1, but it also requires updating Pageant to version 0.62 or later. The other -known workaround is to launch Pageant using cygstart. - -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. - -Version History: -* Sun Jun 23 2013 - 1.3 - allow reusing existing sockets [-r/--reuse] -* Sat Nov 24 2012 - 1.2 - mirror the exit status of child processes -* Tue Dec 06 2011 - 1.1 - fixed SID issues -* Mon Sep 20 2010 - 1.0 - initial release - -Links: -* PuTTY: An SSH client, including the Pageant authentication agent. - http://www.chiark.greenend.org.uk/~sgtatham/putty/ -* Cygwin: A Linux-like environment for Windows. - http://www.cygwin.com/ -* OpenSSH: The SSH client shipped by Cygwin. - http://www.openssh.com/ -* Charade: The friendly competition to ssh-pageant. - http://github.com/wesleyd/charade - ------------------------------------------------------------------------------- -Copyright (C) 2009-2013 Josh Stone -License GPLv3+: 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 file COPYING for license details. Part of ssh-pageant is derived from -the PuTTY program, whose original license is in the file COPYING.PuTTY. diff --git a/README.md b/README.md new file mode 100644 index 0000000..968e0f7 --- /dev/null +++ b/README.md @@ -0,0 +1,168 @@ +# 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 + +The `INSTALL` file describes how to build and install `ssh-pageant` from source, +but the easiest way is to use the readily-available [binary releases]: + +1. Download the pre-built [32-bit] or [64-bit] release for Cygwin, or +the [32-bit][32-bit-msys] 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/ + + +## 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 outputs sh-style commands. Use the `-c` option + for csh-style commands. + +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](http://msysgit.github.io/), 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: + + $ 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. (default) + -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. +* [OpenSSH]: The SSH client shipped by Cygwin. +* [Charade]: The friendly competition to ssh-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 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`. + + +[binary releases]: https://github.com/cuviper/ssh-pageant/releases +[32-bit]: https://github.com/cuviper/ssh-pageant/releases/tag/v1.4-prebuilt-cygwin32 +[64-bit]: https://github.com/cuviper/ssh-pageant/releases/tag/v1.4-prebuilt-cygwin64 +[32-bit-msys]: https://github.com/cuviper/ssh-pageant/releases/tag/v1.4-prebuilt-msys32 +[issues]: http://github.com/cuviper/ssh-pageant/issues +[PuTTY]: http://www.chiark.greenend.org.uk/~sgtatham/putty/ +[Cygwin]: http://www.cygwin.com/ +[MSYS]: http://www.mingw.org/wiki/MSYS +[OpenSSH]: http://www.openssh.com/ +[Charade]: http://github.com/wesleyd/charade diff --git a/ssh-pageant.1 b/ssh-pageant.1 index 2b41cf3..a664690 100644 --- a/ssh-pageant.1 +++ b/ssh-pageant.1 @@ -1,4 +1,4 @@ -.TH ssh\-pageant 1 2013-06-23 1.3 Cygwin +.TH ssh\-pageant 1 2014-11-23 1.4 Cygwin .SH NAME ssh\-pageant - authentication agent @@ -90,7 +90,7 @@ Holds the agent's process ID, used by \fB\-k\fP to kill it. Please report bugs or suggest enhancements via the issue tracker at <\fIhttp://github.com/cuviper/ssh-pageant/issues\fP>. .SH COPYRIGHT -Copyright (C) 2009-2013 Josh Stone +Copyright (C) 2009-2014 Josh Stone .br License GPLv3+: GNU GPL version 3 or later <\fIhttp://gnu.org/licenses/gpl.html\fP>. diff --git a/ssh-pageant.exe b/ssh-pageant.exe index 64eaf3f..8edd18f 100755 Binary files a/ssh-pageant.exe and b/ssh-pageant.exe differ