Working With OpenSSH

Index of All Documentation » Wing Pro Reference Manual » Remote Development » SSH Setup Details »


Use these detailed instructions to set up SSH access with OpenSSH from a host running Linux, OS X. This instructions also can be used on Windows using Cygwin, Git Bash, or Windows 10's native OpenSSH implementation. However, we still recommend using PuTTY since it seems to be prone to fewer problems.

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

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

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

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 earlier above take care of each of these requirements. If you transfer 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.

For more detail on solving SSH configuration problems, see How to Troubleshoot SSH Authentication Issues and How to Troubleshoot SSH Connectivity Issues.

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