<type>documentation</type>
<domain>proj</domain>
<id>ssh-setup-details-openssh</id>
<title>Working With OpenSSH</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 these detailed instructions to set up SSH access with OpenSSH from a host running Linux,
OS X, or from Windows using Cygwin or Git Bash.

The necessary tools for SSH access are already installed on Linux and OS X
systems. They are also included in Cygwin on Windows if the ``openssh``
package is selected at installation time, and they come with Git Bash,
which is actually a scaled down version of Cygwin.

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

On these systems many developers already have an SSH key generated and in
use. If you do not already have one, you will need to generate one with
``ssh-keygen`` as follows on the system where you will be running Wing Pro.
On Windows, these commands need to be executed in the Cygwin or Git Bash 
terminal and not the Windows Console::

  mkdir ~/.ssh
  chmod 700 ~/.ssh
  ssh-keygen -t rsa

Use the default settings and enter a password for encrypting the private key.  This will 
produce ``~/.ssh/id_rsa`` (private key file) and ``~/.ssh/id_rsa.pub`` (public key file).

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

A copy of the public key needs to be transferred to the remote host you want to connect to
and added to ``~/.ssh/authorized_keys``. The following is one way to accomplish this::

  ssh username@remotehost "mkdir .ssh; chmod 700 .ssh"
  ssh username@remotehost "sed -i -e '$a\' .ssh/authorized_keys"
  scp ~/.ssh/id_rsa.pub username@remotehost:.ssh/pub.tmp
  ssh 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 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
-----------------------------------------------

Wing expects you to use an SSH user agent to store your private keys, so that ``ssh`` can
access them as needed without having to prompt you for a password. If you normally use a
command like ``ssh -i mykey.pem user@remote`` to connect to your remote host, you will
need to instead load your key into the user agent.

To do this, run ``ssh-add`` on the host where the IDE is running. You will be prompted for
the encryption password for the private key, if any, and then the key will be loaded into
the user agent.

**On OS X** Sierra, you will need to add the following to your ``~/.ssh/config``
to tell ``ssh`` to communicate with ``Keychain Access``::

  Host *
    UseKeychain yes
    AddKeysToAgent yes

**On Cygwin** you will first need to run ``ssh-agent bash`` and then ``ssh-add`` because
``ssh-agent`` is not running by default.

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

  ssh 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 in ``~/.ssh/config`` with an entry that looks like this::

  host myhost.mydomain.com
     port 8022

