<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.

Logging in with Passwords
-------------------------

If you wish to authenticate using your password on the remote system, you can simply
connect as follows and enter your password when prompted::

  plink username@remotehost
  
In this case, you don't need any further configuration to prepare access to the remote
host before using it with Wing.  Wing will prompt you for your password as needed.

If using passwords does not work because of the way that ``sshd`` is configured on the
remote system, or if you wish to increase the security of your connection, you may
instead want to generate and use an SSH key pair as described below.

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``.

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

Next paste the contents of the area labeled ``Public key for pasting into OpenSSH
authorized_keys file`` in the ``puttygen`` window into a file that you will transfer to
the remote host to add it to ``~/.ssh/authorized_keys``. If you didn't just generate a new
key, you can instead start ``puttygen`` and load your existing key with the ``Load``
button. Then you can right-click to select all and then copy from the ``puttygen.exe``
window.

You may have to create the directory ``~/.ssh`` on the remote system and/or the
``authorized_keys`` file within it. Note that the directory ``~/.ssh`` must be readable
only by the login user and no one else. Otherwise ssh refuses to use it. You can make sure
it has the correct permissions with ``chmod 700 ~/.ssh``.

Once this is done you should be able to test connecting to your remote system with::

  plink -i \path\to\ide_rsa.ppk username@remotehost
  
You will be prompted for the passphrase to unlock your private key before the connection
can be made. To avoid being prompted each time you connect, you can load your private key
into the keychain managed by PuTTY's SSH user agent ``pageant``, as described below.  This is not, however, a requirement for
you to be able to use your SSH key to connect Wing to the remote host.  Wing will prompt
for the passphrase as needed.

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

Using PuTTY's SSH user agent to store your private keys allows you to enter your passphrase
to unlock the key just once.  After that ``ssh`` can access the key as needed without 
having to prompt you again each time you connect. 

To do this, run ``pageant.exe`` on Windows. Then right-click on the small icon that
appears in the tray area of the task bar, usually in the lower right of your screen.
Select ``Add Key`` and choose your ``id_rsa.ppk`` private key file. The private key file
can also be passed to ``pageant.exe`` on the command line. You will be prompted to enter
the key's passphrase, if it is encrypted.

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.  Be sure to run ``pageant`` as the same user that
is running Wing.  For example, if run in a console that is running as ``Administrator``
then Wing will not be able to connect to ``pageant``.

Now you should be able to test connecting to the remote host without having to specify the 
private key or enter a password as follows::

  plink username@remotehost
  
Trouble-Shooting
----------------

The most common cause of problems in making this work is misconfiguration of OpenSSH on
the remote host. OpenSSH will entirely ignore your ``.ssh`` directory if you do not
``chmod 700 .ssh`` to make its contents accessible only by its owner.

The ``.ssh`` directory must be in the home directory of the account used to connect to the
remote host, and must be owned by that user. The home directory on the remote host is
typically referred to as ``~`` and will be printed by ``echo ~`` on the remote host.

In addition, the ``authorized_keys`` file must contain ``\n`` line delimiters and not
Windows style ``\r\n`` newlines.

For more detail on solving SSH configuration problems, see `How to Troubleshoot SSH
Authentication Issues
<https://www.digitalocean.com/docs/droplets/resources/troubleshooting-ssh/authentication/>`__
and `How to Troubleshoot SSH Connectivity Issues
<https://www.digitalocean.com/docs/droplets/resources/troubleshooting-ssh/connectivity/>`__.
  
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 by Wing, will use the configured port.


