<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,
macOS.  This instructions also can be used on Windows using Cygwin, Git Bash, or Windows 10's 
native OpenSSH implementation.

The necessary tools for SSH access are already installed on Linux and macOS 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. Newer versions of Windows 10 also make OpenSSH available as an optional feature
that can be enabled as described in `Enabling Windows 10 OpenSSH Client
<ref:proj/ssh-win10-install>`__.

Using Login 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::

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

.. note::

  **Important:** On Windows, password authentication only works with PuTTY. If you are
  using OpenSSH on Windows you must instead use an SSH key pair stored into the keychain
  provided by ``ssh-agent``.
  Password authentication does work when using PuTTY on Windows, and with OpenSSH 
  on Linux and macOS.
  
If using passwords does not work because of the way that ``sshd`` is configured on the
remote system, because you are using OpenSSH on Windows, or if you wish to increase the
security of your connection, then you can instead generate and use an SSH key pair, as
described below.

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

If you do not already have an SSH key pair, you can generate one with ``ssh-keygen`` as
follows on the system where you will be running Wing Pro.  On Linux or macOS or 
when using Cygwin or Git Bash on Windows, you may first need to make sure that 
the directory ``.ssh`` exists in your home directory and that its permissions are
set in a way that will keep your private key safe::

  mkdir ~/.ssh
  chmod 700 ~/.ssh
  
Then you can generate your SSH key pair with the following command::

  ssh-keygen

Use the default settings and enter a passphrase for encrypting the private key.  This will 
produce ``id_rsa`` (private key file) and `id_rsa.pub`` (public key file) in your ``.ssh``
directory, which is by default in your home directory.

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. On some
systems, the ``\`` on this line must be written ``\\`` so the local shell does not try to
process it as an escape character.

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.

You should now be able to log into the remote system as follows::

  ssh username@remotehost
  
If you did not use the default naming for your SSH key pair, you may instead need to
point ``ssh`` to your key as follows::

  ssh -i /path/to/key username@remotehost
  
You will be prompted for the passphrase to unlock your private key before the connection
can be made. 

At this point you can start configuring your remote host inside Wing, and it will prompt
you for the passphrase as needed. However, this does not work if using OpenSSH on Windows.
In that case, or if you want to avoid Wing prompting you for the passphrase, then you can
load your private key into an SSH user agent, as described below.

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

Using the 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 ``ssh-add`` on the host where the IDE is running. You will be prompted for
the passphrase to descrypt your private key, if it is encrypted, and then the key will be
loaded into the user agent.

If your SSH key isn't the default ``id_rsa`` then you can add the path to the key to
the command line as follows::

  ssh-add /path/to/key

**On macOS** 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

Later versions of macOS seem to do this automatically.  You may want to open ``Keychain
Access`` to inspect what keys it has loaded and optionally set usage restrictions for
the key with ``Get Info`` from the ``File`` menu. Depending on how your key is configured
in ``Keychain Access`` you may need to unlock your key again or run ``ssh-add`` on the
command line each time you log in.

**On Linux** if ``ssh-agent`` is not running by default, , run ``ssh-agent bash`` followed
by ``ssh-add`` and then launch Wing from that command line with ``~~FULL_EXECUTABLE~~`` so
it inherits the necessary environment.  You will need to redo this each time you log into
your Linux system.

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

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.

The commands for moving your public key to the remote system, given earlier above, take
care of each of these requirements. If you transfered the key to the ``authorized_keys``
file some other way (for example, through a file share) then you will need to make sure
that these requirements are met.

In some custom environments, Wing may not be able to gain access to the SSH user agent
because its environment does not contain the necessary environment variables. In this
case, type ``set | grep SSH_``, copy the ``SSH_AGENT_PID`` and ``SSH_AUTH_SOCK`` lines,
and paste them into the ``Environment`` in Wing's ``Project Properties``. You will need to
redo this each time you restart the system where Wing is running, or if you restart
``ssh-agent``, since the contents of the environment variables will change.

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

  host myhost.mydomain.com
     port 8022

