From d11ae45887f48afd0279626982c68a0162489c7f Mon Sep 17 00:00:00 2001 From: Mark Polesky Date: Sat, 20 Feb 2010 23:13:04 -0800 Subject: [PATCH] Doc: CG: Improve instructions for using SSH. --- Documentation/contributor/source-code.itexi | 120 +++++++++++++++++++++++++--- 1 file changed, 111 insertions(+), 9 deletions(-) diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 12e89138b8..3c08090d15 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -1242,12 +1242,14 @@ you visit the link, follow the steps for including the CAcert root certificate in your browser, given at @uref{http://savannah.gnu.org/tls/tutorial/}. + @item After registering, if you are not logged in automatically, login at @uref{https://savannah.gnu.org/account/login.php}---this should take you to your @qq{my} page (@uref{https://savannah.gnu.org/my/}). + @item Click on the @qq{My Groups} link to access the @qq{My Group Membership} page. From there, find the @qq{Request for Inclusion} @@ -1261,13 +1263,60 @@ Manager activates your membership. Once your membership is activated, LilyPond should appear under the heading @qq{Groups I'm Contributor of} on your @qq{My Group Membership} page. + +@item +Generate an SSH @q{dsa} key pair. Enter the following at the +command prompt: + +@example +ssh-keygen -t dsa +@end example + +When prompted for a location to save the key, press to +accept the default location (@file{~/.ssh/id_dsa}). + +Next you are asked to enter an optional passphrase. On most +systems, if you use a passphrase, you will likely be prompted for +it every time you use @command{git@tie{}push} or +@command{git@tie{}pull}. You may prefer this since it can protect +you from your own mistakes (like pushing when you mean to pull), +though you may find it tedious to keep re-entering it. + +You can change/enable/disable your passphrase at any time with: + +@example +ssh-keygen -f ~/.ssh/id_dsa -p +@end example + +Note that the GNOME desktop has a feature which stores your +passphrase for you for an entire GNOME session. If you use a +passphrase to @qq{protect you from yourself}, you will want to +disable this feature, since you'll only be prompted once. Run the +following command, then logout of GNOME and log back in: + +@example +gconftool-2 --set -t bool \ + /apps/gnome-keyring/daemon-components/ssh false +@end example + +After setting up your passphrase, your private key is saved as +@file{~/.ssh/id_dsa} and your public key is saved as +@file{~/.ssh/id_dsa.pub}. + + @item -Go to the @qq{My Account Configuration} page. From there, click -on @qq{Edit SSH Keys} and follow the instructions given. +Register your public SSH @q{dsa} key with Savannah. From the +@qq{My Account Configuration} page, click on @qq{Edit SSH Keys}, +then paste the contents of your @file{~/.ssh/id_dsa.pub} file into +one of the @qq{Authorized keys} text fields, and click +@qq{Update}. + +Savannah should respond with something like: -FIXME: Explain the confusing warning I always get. -mp +@example +Success: Key #1 seen Keys registered +@end example -FIXME: Maybe add a note about enabling/disabling SSH passphrase? @item Configure Git to use the SSH protocol (instead of the GIT @@ -1281,13 +1330,66 @@ git config remote.origin.url \ @noindent where @var{user} is your username on Savannah. + @item -After your membership has been activated and you've configured Git -to use SSH, try doing a @command{git@tie{}pull} or -@command{git@tie{}pull@tie{}-r}. If that succeeds, this indicates -that your SSH key stored at Savannah is working properly. +After your membership has been activated and you’ve configured Git +to use SSH, test the connection with: + +@example +git pull --verbose +@end example + +SSH should issue the following warning: + +@example +The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't +be established. +RSA key fingerprint is +80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5. +Are you sure you want to continue connecting (yes/no)? +@end example + +Make sure the RSA key fingerprint displayed matches the one above. +If it doesn't, respond @qq{no} and check that you configured Git +properly in the previous step. If it does match, respond +@qq{yes}. SSH should then issue another warning: + +@example +Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to +the list of known hosts. +@end example + +The list of known hosts is stored in the file +@file{~/.ssh/known_hosts}. + +At this point, you are prompted for your passphrase if you have +one, then Git will attempt a pull. + +If @command{git@tie{}pull@tie{}--verbose} fails, you should see +error messages like these: + +@example +Permission denied (publickey). +fatal: The remote end hung up unexpectedly +@end example + +If you get the above error, you may have made a mistake when +registering your SSH key at Savannah. If the key is properly +registered, you probably just need to wait for the Savannah server +to activate it. It usually takes a few minutes for the key to be +active after registering it, but if it still doesn't work after an +hour, ask for help on the mailing list. + +If @command{git@tie{}pull@tie{}--verbose} succeeds, the output +will include a @q{From} line that shows @q{ssh} as the protocol: + +@example +From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond +@end example + +If the protocol shown is not @q{ssh}, check that you configured +Git properly in the previous step. -FIXME: show what success/failure look like. @item Test your commit access with a dry run: -- 2.11.4.GIT