Permalink
Browse files

Fixed #20: Improved README, installation and usage instructions, and…

… documentation.
  • Loading branch information...
sun committed Sep 16, 2013
1 parent 707b2e7 commit 6245c2ac7d543c85a75ff2d4fd4d33a7ab7ed84c
Showing with 166 additions and 101 deletions.
  1. +1 −1 Makefile
  2. +0 −90 README
  3. +155 −0 README.md
  4. +10 −10 main.c
View
@@ -7,7 +7,7 @@ PROGRAM = ssh-pageant.exe
SRCS = main.c winpgntc.c
HDRS = winpgntc.h
MANPAGE = ssh-pageant.1
-DOCS = README COPYING COPYING.PuTTY
+DOCS = README.md COPYING COPYING.PuTTY
OBJS = $(SRCS:.c=.o)
DEPS = $(OBJS:.o=.d)
View
90 README
@@ -1,90 +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; e.g.:
-
-~/.bashrc:
- # ssh-pageant
- # Note: To share the socket between Cygwin and MinGW, ensure to use a path
- # that resolves to the same location in both via: cygpath --windows {path}
- eval $(/usr/bin/ssh-pageant -ra /tmp/.ssh-pageant)
-
-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.
View
155 README.md
@@ -0,0 +1,155 @@
+# ssh-pageant
+_An SSH authentication agent for Cygwin 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] shell environments.
+
+You can use ssh-pageant to automate SSH connections from the Cygwin shell, 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 the [64-bit] release.
+
+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 -ra /tmp/.ssh-pageant)
+
+ 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.
+ * 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.
+ * Usage of `eval` to load the environment variables is the usual approach.
+ By default, ssh-pageant outputs sh-style commands. Use the `-c` option
+ for csh-style commands.
+ * To share the socket between Cygwin and [msysgit/MinGW](http://msysgit.github.io/),
+ ensure to use a path that resolves to the same location in both
+ environments via `cygpath --windows {path}`
+
+
+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.
+
+
+## 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
+
+* 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.
+* [OpenSSH]: The SSH client shipped by Cygwin.
+* [Charade]: The friendly competition to ssh-pageant.
+
+------------------------------------------------------------------------------
+Copyright (C) 2009-2013 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 `LICENSE` file for details.
+Part of ssh-pageant is derived from the PuTTY program, whose original license is
+in the file `LICENSE.PuTTY`.
+
+
+[binary releases]: https://github.com/cuviper/ssh-pageant/releases
+[32-bit]: https://github.com/cuviper/ssh-pageant/releases/tag/v1.3-prebuilt
+[64-bit]: https://github.com/cuviper/ssh-pageant/releases/tag/v1.3-prebuilt64
+[issues]: http://github.com/cuviper/ssh-pageant/issues
+[PuTTY]: http://www.chiark.greenend.org.uk/~sgtatham/putty/
+[Cygwin]: http://www.cygwin.com/
+[OpenSSH]: http://www.openssh.com/
+[Charade]: http://github.com/wesleyd/charade
View
20 main.c
@@ -323,16 +323,16 @@ main(int argc, char *argv[])
case 'h':
printf("Usage: %s [options] [command [arg ...]]\n", prog);
printf("Options:\n");
- printf(" -h, --help Display this help information\n");
- printf(" -v, --version Display version information\n");
- printf(" -c Use C-style shell commands\n");
- printf(" -s Use Bourne-style shell commands\n");
- printf(" -k Kill the current %s\n", prog);
- printf(" -d Enable debug mode\n");
- printf(" -q Enable quiet mode\n");
- printf(" -a SOCKET Bind to a specific socket address\n");
- printf(" -r, --reuse Allow reusing an existing -a SOCKET\n");
- printf(" -t TIME Limit key lifetime (not supported by Pageant)\n");
+ printf(" -h, --help Show this help.\n");
+ printf(" -v, --version Display version information.\n");
+ printf(" -c Generate C-shell commands on stdout.\n");
+ printf(" -s Generate Bourne shell commands on stdout. (default)\n");
+ printf(" -k Kill the current %s.\n", prog);
+ printf(" -d Enable debug mode.\n");
+ printf(" -q Enable quiet mode.\n");
+ printf(" -a SOCKET Create socket on a specific path.\n");
+ printf(" -r, --reuse Allow to reuse an existing -a SOCKET.\n");
+ printf(" -t TIME Limit key lifetime in seconds (not supported by Pageant).\n");
return 0;
case 'v':

0 comments on commit 6245c2a

Please sign in to comment.