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

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.

Important: On Windows, password authentication only works with PuTTY. If you are using OpenSSH on Windows you must instead use an SSH key pair and SSH user 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 wing8.3 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 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