New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve installation instructions #19

Merged
merged 2 commits into from Sep 2, 2013

Conversation

Projects
None yet
2 participants
@sun
Copy link
Contributor

sun commented Sep 1, 2013

  1. Many users (including me) are running into the executable bit trap (which isn't obvious on Windows).
  2. There's no usage example for the new --reuse option yet.

Regarding the latter, it actually took me some time to get ssh-pageant working with both Cygwin and MinGW (msysgit) at the same time, sharing a single socket.

The instructions added here are just a baseline, which might help new users to set it up more quickly.

In my particular case, msysgit did still not actually work, even after figuring out the socket file path hiccup (resorting to $TEMP fixed that) -- TortoiseGit/msysgit actually seems to ship with a OpenSSH/OpenSSL client version that is not compatible with ssh-pageant...

After lots of trial and error, I managed to get it working by making the MinGW bash force-use more current binaries from Cygwin, by putting the following at the top of .bashrc:

export PATH=/c/cygwin/bin:${PATH}

However, I don't know whether that is worth to document, as I don't know how common the TortoiseGit/MinGW + Cygwin combination is in the wild. I suspect it is quite common, but YMMV.

ssh-pageant seems to work correctly now - I only see one process running, regardless of how many shells I'm invoking (and regardless of provider).

What do you think? Is the example correct?

In addition, I considered to remove the other existing example, since the new --reuse option definitely appears to be preferable and is simpler to set up on top. But didn't touch that, so as to keep changes minimal.

Lastly, I think ssh-pageant is really useful, and would offer you to rewrite/redo README and INSTALL into a new and combined README.md file that encompasses everything new users ought to know. I'm aware that the separate files are common in *nix, but the primary "homepage" of your nice tool seems to be GitHub, and thus, the first thing that every potential new user reads is the readme → the simpler, shorter, better the readme, the more happy users. ;-) If you agree, I'll create a (separate) PR for that.

Thank you for developing this excellent piece of code!

@cuviper

This comment has been minimized.

Copy link
Owner

cuviper commented Sep 1, 2013

Hi, and thanks for your input!

The chmod instruction in INSTALL looks fine.

The --reuse example is trickier though. On my system, at least, Cygwin TEMP=/tmp, but temp=%LocalAppData%\Temp -- and same for TMP vs. tmp. Not sure why I have l the lowercase versions, but that creates trouble in your instructions.

I also can't get msysgit's ssh to talk to ssh-pageant, but I didn't try very hard. I'm guessing just that the socket implementations between MinGW and Cygwin are incompatible. I do know that cygwin32 and cygwin64 can work in either direction, even though their runtimes are distinct, but I guess they must share the same underlying Windows API somewhere. Apparently that's not so for MinGW.

So for those reasons, I'd leave the TEMP and MinGW comments out of a --reuse example. Maybe it can just note that one should use a full system path if the agent is to be shared across runtimes, with cygwin32/64 as an example.

I think your PATH hack to get msysgit to use Cygwin's openssh is outside the scope to mention here. But I noticed while I installed msysgit that it has the option to configure for plink instead, which could talk directly to Pageant. Why wouldn't you just use that? Does Tortoise not offer the plink option?

Finally, as for a README.md, I'm open to it. If you just intend to make it a simplified new-users guide, then I'd leave the existing README+INSTALL in place. (A little content duplication is not a big deal, since ssh-pageant rarely needs to be updated anyway.) Or if your new file keeps most of what I've written, just expanded, markdown formatted, and still legible in plain text, it could be a full replacement. Let me see what your propose. A separate PR is fine, so this doesn't block your quick updates here.

Thanks!

PS- I always find it amusing when many more words are spent discussing a change than the change itself... oh well, it is what it is. :)

@sun

This comment has been minimized.

Copy link
Contributor Author

sun commented Sep 2, 2013

Alrighty, I'll look into the readme after this one. And yeah, sorry for the length - since this appears to be the first ever PR for this project, I wanted to introduce myself "softly" ;)

Not sure why I have l the lowercase versions

That is indeed strange. Thanks for noting, that definitely complicates things ;)

I'm guessing just that the socket implementations between MinGW and Cygwin are incompatible.

AFAIK, yes, MinGW uses native Windows sockets, whereas Cygwin uses a port of unix sockets. I can only guess that my adjustment of $PATH to put Cygwin's binaries first, essentially makes msysgit use the ssh binaries of Cygwin, and thus also the right socket implementation.

Maybe it can just note that one should use a full system path if the agent is to be shared across runtimes

Yup, makes sense - I've just amended/replaced the second commit.

I noticed while I installed msysgit that it has the option to configure for plink instead, which could talk directly to Pageant. Why wouldn't you just use that? Does Tortoise not offer the plink option?

Yeah, that needs more explanation. TortoiseGit is really just a UI that invokes git on the msysgit shell under the hood. msysgit ships with MinGW, which comes with a basic set of ported unix utilities. The git environment uses the configured $GIT_SSH agent link (either in PuTTY or OpenSSH mode). However, at least on my system, the additional msysgit/MinGW SSH utilities like scp do not use plink as agent.

Now that you're mentioning it, I wonder whether my configuration just happens to be wrong, or whether that is a general issue with the msysgit/MinGW tools. However, I believe things are set up correctly - just for completeness:

$ env | egrep "SSH|PLINK"
GIT_SSH=C:\Program Files\TortoiseGit\bin\TortoisePlink.exe
PLINK_PROTOCOL=ssh
SSH_AUTH_SOCK=C:/Users/sun/AppData/Local/Temp/.ssh-pageant
SVN_SSH=C:\Program Files\TortoiseGit\bin\TortoisePlink.exe

All of that being said, it sounds like you are/were not using msysgit/MinGW, so I don't really want to bug you further about that, because that's certainly not your issue then. I already achieved all I wanted to achieve (making both Cygwin and msysgit/MinGW use PuTTY's Pageant for all SSH operations), so I'm not even sure whether I will or want to actually investigate that issue further ;-) I guess we can ignore that part for now; I'll create a separate PR, in case I'll gather further/better conclusions in the future :)

Thanks!

cuviper added a commit that referenced this pull request Sep 2, 2013

Merge pull request #19 from sun/docs
Improve installation instructions

@cuviper cuviper merged commit 707b2e7 into cuviper:master Sep 2, 2013

@cuviper

This comment has been minimized.

Copy link
Owner

cuviper commented Sep 2, 2013

Ok, I'll merge this, though I might tweak it more after thinking further. I hesitate on calling it "sharing with MinGW", because you're not really sharing at all - by invoking Cygwin's openssh, the socket is being used by all native Cygwin. I'll leave it for now though.

It's good that you are using Tortoise's plink - that's how I would recommend new users take advantage of Pageant, so they don't have to also go through the dance of installing Cygwin. The only advantage of running git through openssh is if you need stuff in .ssh/config, but that's a more advanced usage.

You could try to train yourself to use pscp instead of scp, if you wanted a more native Pageant experience, but it's fine if you're working well with Cygwin's openssh binaries. But I'd say you're venturing into "advanced" territory too. :) Heck, once you're placing Cygwin in your PATH, why not just use a real Cygwin shell for that stuff?

It might be interesting to make a native MinGW port of ssh-pageant, but a first try with make CC=i686-w64-mingw32-gcc doesn't bode well, with lots of missing system headers. It seems like that will require a lot of rewriting main.c, so maybe its not worth it.

@cuviper

This comment has been minimized.

Copy link
Owner

cuviper commented Sep 2, 2013

Oh, and thanks for contributing! :) You are indeed the first person to do more than report an issue or give thanks. I don't really worry about that, since this is such a small and feature-complete program, but it is nice to receive input.

@sun sun deleted the sun:docs branch Sep 2, 2013

@sun

This comment has been minimized.

Copy link
Contributor Author

sun commented Sep 3, 2013

Thanks! Btw, you are a great collaborator.

Of course, feel free to change the added docs entirely — change and improvement is just natural to evolution. And in the end, as the maintainer, you certainly know best what works and what doesn't :-)

In fact, I myself have strong Windows environment skills and a relatively good amount of *nix experience - however, the backdoor injection of *nix tools into Windows environments is still a red herring to me; certainly requires in-depth programming understanding of internal Windows APIs (which I don't have) in order to understand what's going on behind the scenes... Therefore, my contributions in this area certainly need to be taken with a fine grain of salt.

Anyway; during my brief research, I stumbled over some tutorials that had to explicitly mention the chmod fix, which was my initial trigger for this PR. And only after trying it out myself and studying recent commits, I was missing an example for the promising new --reuse parameter. And here we go; open-source at its best :-)

That said, I was also glancing over Charade, which is being mentioned as "friendly competition" here and elsewhere. Unless I've misunderstood its documentation, though, Charade is based on keychain and a dozen of other tools (which I did not want to install just for this), seemingly following the paradigm of dumping keys in pageant into your bash user environment - which may be interpreted as syncing but not really as a direct pageant access. Props of awesomeness for mentioning competitions, though clarifying about the actual difference is one piece of info I'd like to improve with the readme (and apparently, I have no idea what I'm talking about, so input on that is welcome ;-))

Are you tired already? Sorry, I'm too verbose today. ;) Hard-stop. Thanks again for doing and publicly sharing this! :)

@cuviper

This comment has been minimized.

Copy link
Owner

cuviper commented Sep 3, 2013

"Maintainer knows best" - ha! While I'm certainly familiar with my own code, it doesn't especially mean I've best explained how to use it, so receiving input on that is much appreciated. And who knows, you can probably find code bugs too if you dig - I have no delusions of perfection... :)

Charade does operate the same way as ssh-pageant, emulating an ssh-agent socket and passing messages to/from Pageant. The business with keychain is just a way to manage a single instance of the agent. Keychain doesn't actually handle ssh keys in your home or environment AFAIK; it just keeps track of the currently running ssh-agent to share it across shells. Since keychain doesn't know anything about charade, they chose to outright replace the ssh-agent binary in the install.sh script to trick keychain.

On systems where ssh-agent is holding the keys itself, keychain can be really useful to avoid unlocking keys over and over for multiple agents. Here where Pageant is the real key holder, I personally don't see the fuss over whether multiple agents are running, be it charade or ssh-pageant. But people do seem to care, which is why charade instructs you to use keychain, while I finally came up with the --reuse option for ssh-pageant. :)

So charade and ssh-pageant really are quite similar. It's just the usage instructions that are so different, though you could mostly use one as instructed by the other. I think the "friendly competition" with charade is to say that I'm not really trying to convince people one way or the other.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment