Merge lp:~adam-delvecchio/bzr/662448-sshkey-doc into lp:bzr

[Adam Del Vecchio]

Fixed bug #662448

[Martin Pool (mbp)]

Thanks!

The ReST markup is a bit wrong: in the wiki the headings have bars next to them whereas in rest they need an underline of the same length as the heading. Example terminal output or files should have a :: on the preceding line; inline examples should be in ``double backticks``. See http://docutils.sourceforge.net/docs/user/rst/quickref.html

Perhaps there are a few more points to make in the introduction:

 * you can authenticate over ssh by a key pair or by a password (or potentially by other mechanisms); the server chooses what it will accept
 * an ssh key is an assymetric key: there is a 'public' part you put on the server and a private part you keep

I think that using a master connection, while really useful to document, is not normally what people want and describing it first may cause counfusion?

+
+In some cases, ssh may refuse to work if your public key is in your ~/.ssh directory.
+
+ mv ~/.ssh/id_rsa.pub ~/id_rsa.pub
+should fix the problem.

I guess that's on the wiki page but I can't imagine why it would work and it seems like a kind of random suggestion.

s/exxe/exe

review: Needs Fixing

[Martin Pool (mbp)]

oh, also this probably needs to be mentioned in 'index.txt' to be included within the manual

[Adam Del Vecchio (adam-delvecchio)]

I will fix and re-commit :)

Also, as to the random suggestion, it works (in my experience), merely because on some servers (I've seen it at least twice), ssh doesn't like the public key in the same directory as the private key. Its mentioned a few times in various mailing lists and documents around the web, I believe :)

[Martin Pool (mbp)]

Hi, I just wanted to check this wasn't blocked on anything. If you'd like me to finish it off, just let me know.

[Vincent Ladeuil (vila)]

@Adam: Do you need help here (just say so :) ?

Also, I think we need you to execute the Canonical's Contributor Agreement: <http://www.canonical.com/contributors>.

Unmerged revisions

5505. By Adam Del Vecchio on 2010-10-18

Fixed bug #662448, added an ssh_keys help document

=== added file 'doc/en/user-guide/ssh_keys.txt'
--- doc/en/user-guide/ssh_keys.txt	1970-01-01 00:00:00 +0000
+++ doc/en/user-guide/ssh_keys.txt	2010-10-18 02:54:42 +0000
@@ -0,0 +1,109 @@
+bzr with SSH keys
+=================
+
+It is commonly wanted to prevent the need to enter a password for Bazaar 
+commands when using bzr+ssh:// or sftp:// transports. On Unix (and derivatives),
+bzr has the ability to use the same settings as the installed 'ssh' client. Thus,
+using bzr+ssh:// or sftp:// transports to access a remote branch follows the same
+procedure as for setting up authorization for a shell login.
+
+There are 2 ways to configure SSH to not use a password. 
+|* 1. Use a master connection, preventing the need for a password after an initial ssh
+session has been created.
+|* 2. Authenticating with a public/private key pair.
+
+Unix, Linux, and OS X
+------
+
+--Using a Master Connection--
+
+Before you can use a master connection you will need to configure your client so that it knows how to communicate with the master connection. This is done by specifying the path to a socket that will be used for communication purposes. Add the following lines to the ~/.ssh/config file (or create the file if it does not exist):
+
+	# Where to find the control path, if we have one
+	Host *
+	   ControlPath ~/.ssh/master-%r@%h:%p
+
+You can then open a master connection to the server using the -M option:
+
+
+	ssh -M [e-mail]
+As long as this master connection is not closed (i.e you do not exit the shell) you will be able to login to the machine without a password. It is also possible to configure ssh such that it always opens a master connection if there isn't already one open. This means you do not even need to pass the -M option to ssh. To do this add the following option to ~/.ssh/config:
+
+
+	ControlMaster auto
+
+--Using public/private key pairs--
+
+---Generating a key---
+If you have not previously generated a public/private key pair, you can use 'ssh-keygen' to do so for the first time.
+
+	$ ssh-keygen -t rsa
+	Generating public/private rsa key pair.
+	Enter file in which to save the key (/home/example/.ssh/id_rsa): 
+	Enter passphrase (empty for no passphrase):
+	Enter same passphrase again:
+	Your identification has been saved in /home/example/.ssh/id_rsa.
+	Your public key has been saved in /home/example/.ssh/id_rsa.pub.
+	The key fingerprint is:
+	49:c7:90:63:82:34:be:94:d5:ce:c9:ec:15:e7:06:c8 example@localhost
+
+Your public/private keypair is now generated. Your private key should not be distributed.
+We will use your public key to prove your identity.
+
+---Uploading your public key---
+If the ssh-copy-id command is installed then using that is the easiest way to upload your key to the server. You just need to enter:
+
+
+	ssh-copy-id [e-mail]
+If this command is not installed then you can also upload the key manually:
+
+Log into the host containing the remote branch.
+On the remote host, edit the file ~/.ssh/authorized_keys.
+Each line of this file contains the public half of the public/private key pair which is authorized to log in.
+Use a text editor to copy the contents of your local /home/example/.ssh/id_rsa.pub to the ~/.ssh/authorized_keys file on the remote server. Ensure that there are no line breaks, the key must all be on a single line. Save the file.
+Test that your client is now authorized by logging in again via ssh to the account. Assuming that works, you should now be able to use bzr+ssh:// and sftp:// to access branches on the remote host without requiring a password.
+
+Thats it!
+
+---Troubleshooting---
+
+In some cases, ssh may refuse to work if your public key is in your ~/.ssh directory.
+
+	mv ~/.ssh/id_rsa.pub ~/id_rsa.pub
+should fix the problem.
+
+Windows
+-------
+
+Like Unix, on Windows in order to avoid having to enter a password with the bzr+ssh:// and sftp:// transports you must create a public/private key pair and add it to the authorized_keys file on the remote server.
+
+However, configuring bzr to find and use the correct key pair can be done in different ways, and may be slightly more complicated than on Unix. The following instructions assume that you used the standalone Windows installer, not the Python-based installer.
+
+--Using the Unix way--
+On many Windows systems you can use a method analogous to what is described above for Unix systems. To generate the key pair, either use the ssh-keygen tool from a nearby Unix machine or install Cygwin on your Windows machine to provide ssh-keygen locally.
+
+Edit the ~/.ssh/authorized_keys file on the server just as described for Unix. Then add the id_rsa file to your Windows account the same way as is done in Unix, by:
+
+locate your home directory (something like C:\Documents and Settings\<username> on Windows XP and below, or C:\Users\<username>\ on Windows Vista and higher, and is usually pointed out by the environment variables %HOMEDRIVE%\%HOMEPATH% or %USERPROFILE%)
+if needed, create a ".ssh" sub-directory in the home directory (Windows Explorer may complain about names starting with ".", use a command prompt instead [mkdir "C:\Users\<username>\.ssh"] or [mkdir "C:\Documents and Settings\<username>\.ssh"])
+add the private key file id_rsa to the .ssh directory
+All done!
+
+--Using Puttygen and Pageant--
+If for some reason the above does not work for you, Bzr is capable of using pageant to be provided with the public/private key pair.
+
+Putty.exxe and pageant.exe can be downloaded from [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html].
+
+Run puttygen.exe. Push "Generate" and follow the instructions. Select "Save public key" and save the key to a file, and do the same for "Save private key".
+
+Run pageant.exe. This will create an icon in the system tray of a computer with a hat (?) on it. Click on that icon. This will open a window titled "Pageant Key List". Select "Add Key". It will then prompt you for a private key file, which should be the key you generated and saved in the previous step.
+
+Now log in to the remote host.
+
+On the remote host, edit the file ~/.ssh/authorized_keys. Each line of this file contains the public key half of the key pair which is authorized to log in.
+
+Use a text editor to copy the contents of the public key you just generated (which can be copy-and-pasted from puttygen, or from the contents of the public key file you saved) to the ~/.ssh/authorized_keys file on the remote server. Ensure that there are no line breaks, the key must all be on a single line. Save the file.
+
+Test that your client is now authorized by logging in again via ssh (using PuTTY) to the account. Assuming that works, you should now be able to use bzr+ssh:// and sftp:// to access branches on the remote host without requiring a password.
+
+