<type>documentation</type>
<domain>proj</domain>
<id>ssh-setup-details-putty</id>
<title>Working With PuTTY</title>
<date>$Date: 2010-05-14 11:53:19 -0400 (Fri, 14 May 2010) $</date>
<version>$Revision: 22093 $</version>
<product-version>6+</product-version>
<product>pro+</product>

Use the following instructions to set up SSH access from Windows using Putty.

If you don't already have it, download and install the complete suite of tools provided by
`PuTTY <http://www.chiark.greenend.org.uk/~sgtatham/putty/>`__. You will need
``putty.exe``, ``plink.exe``, ``pscp.exe``, and ``puttygen.exe``. We recommend using the
``MSI`` installer, so you have all the necessary tools placed in a location where Wing can
find them.

Generating an SSH Key Pair
--------------------------

If you don't already have an SSH key set up, you will need to generate one by
running ``puttygen.exe``, pressing the ``Generate`` button, providing the
requested random input by moving your mouse over the blank area, entering and
confirming a passphrase, and then saving both the public and private key
files. The private key file is typically named ``id_rsa.ppk`` and the public
key file is ``id_rsa.pub``. Then paste the contents of the area labeled
``Public key for pasting into OpenSSH authorized_keys file`` into a file that
you will transfer to the remote host to add it to ``~/.ssh/authorized_keys``. 
You can right-click to select all and then copy from the ``puttygen.exe``
window.

Moving the SSH Public Key to the Remote Host
--------------------------------------------

Assuming you saved the OpenSSH formatted public key to a file named ``openssh.pub``
you can install it on the remote host as follows::

  plink username@remotehost "mkdir .ssh; chmod 700 .ssh"
  plink username@remotehost "sed -i -e '$a\' .ssh/authorized_keys"
  pscp openssh.pub username@remotehost:.ssh/pub.tmp
  plink username@remotehost "cat .ssh/pub.tmp >> .ssh/authorized_keys; rm .ssh/pub.tmp"

The first line above is only needed if you do not already have the directory ``~./ssh`` on the
remote system. The second line is only needed if you already have ``~.ssh/authorized_keys`` 
on the remote system, to ensure that it ends in a newline so your added key is on its own
line. The third and fourth lines transfer the OpenSSH formatted public key to the remote
host and add it as a key that is authorized to log in without entering a password. 

Loading the SSH Private Key into the User Agent
-----------------------------------------------

Finally, run ``pageant.exe``, right click on the small icon that appears in the lower
right of your screen, select ``Add Key``, and select your ``id_rsa.ppk`` private key file.

Note that you may need to restart ``pageant`` and load your key into it each time you
restart Windows or log out and back in.

Now you should be able to connect to the remote host without having to enter a password
as follows::

  plink username@remotehost
  
Using a Non-Default SSH Port
----------------------------

If your remote server is running SSH on a non-default port, then you will
also need to edit your SSH configuration on the host where the IDE is running to set 
that port.  This is done by running ``putty``, entering a host name or ip address and the 
port number to use, and saving that host name as a saved session (all on the initial
``Session`` tab).  Once this is done, any connection to that host name, also if made
from the command line or Wing, will use the configured port.


